With the DataStore, you interface the following artifacts:
- -All the classes and interfaces mentioned here are defined in the org.eclipse.dstore.core plugin. - -
-The ClientConnection class is used for establishing a DataStore connection. This class provides the -means to instantiate a client DataStore and connect to a server DataStore on a specified host running under a -specified port. The connection to the server DataStore may either be made directly or a startup -negotiation may be made with a remote daemon before connecting to the server. This class also provides the means -for disconnecting from the DataStore. -
- -
-The DataStore class is the heart of the DataStore communications framework. An instance of a DataStore contains a tree
-of DataElements. This tree can be referred to as the DataStore repository because
-it consists of all the schema information and data content used. Any type of object or relationship defined, command definition or
-peice of data that needs to be communicated between the client and server are stored in the DataStore repository.
-The DataStore class can be used for finding, creating and deleting DataElements and for communicating commands
-to miner. The DataStore class encapsulates all remote synchronizations between the client and the
-server via it's command and refresh APIs.
-
-The DataElement is the unit of information in a DataStore repository. Each DataElement has a set of attributes that describe -the object it represents and is related to other DataElements by containing other DataElements. DataElements represent both the meaning -of data as well as the data itself. -
--For more information about DataElements, see the section, DataElements and the DataStore model. -
- --A Miner is an extension point to the DataStore. Miners are classes, residing on the server-side, that implement a common -interface used by the DataStore for communication information between the DataStore and the tools. -
--For more information about Miners, see the section, Miners. -
- - - - - + + + + + + +With the DataStore, you interface the following artifacts:
+ +All the classes and interfaces mentioned here are defined in the org.eclipse.dstore.core plugin. + +
+The ClientConnection class is used for establishing a DataStore connection. This class provides the +means to instantiate a client DataStore and connect to a server DataStore on a specified host running under a +specified port. The connection to the server DataStore may either be made directly or a startup +negotiation may be made with a remote daemon before connecting to the server. This class also provides the means +for disconnecting from the DataStore. +
+ +
+The DataStore class is the heart of the DataStore communications framework. An instance of a DataStore contains a tree
+of DataElements. This tree can be referred to as the DataStore repository because
+it consists of all the schema information and data content used. Any type of object or relationship defined, command definition or
+piece of data that needs to be communicated between the client and server are stored in the DataStore repository.
+The DataStore class can be used for finding, creating and deleting DataElements and for communicating commands
+to miner. The DataStore class encapsulates all remote synchronizations between the client and the
+server via its command and refresh APIs.
+
+The DataElement is the unit of information in a DataStore repository. Each DataElement has a set of attributes that describe +the object it represents and is related to other DataElements by containing other DataElements. DataElements represent both the meaning +of data as well as the data itself. +
++For more information about DataElements, see the section, DataElements and the DataStore model. +
+ ++A Miner is an extension point to the DataStore. Miners are classes, residing on the server-side, that implement a common +interface used by the DataStore for communication information between the DataStore and the tools. +
++For more information about Miners, see the section, Miners. +
+ + + + + diff --git a/rse/doc/org.eclipse.dstore.doc.isv/guide/ClientSide.html b/rse/doc/org.eclipse.dstore.doc.isv/guide/ClientSide.html index 8debb2d8347..c2fb661a7b3 100755 --- a/rse/doc/org.eclipse.dstore.doc.isv/guide/ClientSide.html +++ b/rse/doc/org.eclipse.dstore.doc.isv/guide/ClientSide.html @@ -1,171 +1,171 @@ - - - - - - --If you're writing an RSE subsystem to connect to a local standalone DataStore, the following needs -to be done during the connect: -
- - -
- ...
- ClientConnection clientConnection = new ClientConnection(connectionName);
-
- // initialize the local datastore
- clientConnection.localConnect();
-
- DataStore dataStore = clientConnection.getDataStore();
-
- // specify miners to load
- dataStore.addMinersLocation("."); // initializes the default miners
-
- // initialize miners
- dataStore.getSchema();
- dataStore.initMiners();
- ...
-
-
-
-
-
-If you're writing an RSE subsystem to connect to a remote DataStore, the only difference
-from the local scenario is that connect is called rather than localConnect.
-
- ...
- ClientConnection clientConnection = new ClientConnection(connectionName);
-
- // prepare connection
- clientConnection.setHost(hostName);
- clientConnection.setPort(port);
-
- // connect
- clientConnection.connect(ticket);
-
- DataStore dataStore = clientConnection.getDataStore();
-
- // specify miners to load
- dataStore.addMinersLocation("."); // initializes the default miners
-
- // initialize miners
- dataStore.getSchema();
- dataStore.initMiners();
- ...
-
-
-
-
--If the new miner has been registered via the default minerFile.dat file, then -no further steps are required to load it. Otherwise, after the subsystem is -connected to the remote DataStore, you need to tell the DataStore to load the -miner as follows. -
- - -- ... - dataStore.addMinersLocation(location); - dataStore.getSchema(); - ... -- - -
-This tells the host DataStore to instantiate and initialize all miners listed in -the specified minerFile.dat file. -
- - -
-To send a command to a miner, the required command descriptor must first be optained
-using the method DataStore.localDescriptorQuery. The method DataStore.command is then called with command
-descriptor and the subject of the command. For example, a query might need to be called on the miner as shown in the following code segment.
-
- ... - // the UI model object - MyRemoteObject obj = getMyRemoteObject(); - - // get the corresponding DataElement for this object - DataElement deObj = obj.getDataElement(); - - // get the DataStore from the DataElement - DataStore ds = deObj.getDataStore(); - - // get the query command descriptor for the subject - DataElement queryCmd = ds.localDescriptorQuery(deObj.getDescriptor(), "MY_QUERY_COMMAND"); - - // send the command - DataElement status = ds.command(queryCmd, deObj, true); - ... -- - -
-After a command is sent to a miner, you might want to receive information that the miner produced in response to the command.
-DataStore commands and responses are sent asynchronously, much like events. On the server, the
-Server Command Handler reacts to incoming commands by calling the handleCommand
-method on the appropriate miner. For the client, the Client Command Handler
-reacts to incoming responses by firing domain notifications. In order to receive miner responses, asynchronously,
-you need to implement a DataStore domain listener.
-
-A domain listener implements the IDomainListener interface. An instance of an IDomainListener needs to be added to the DataStore domain listener -list. The following is what a simple domain listener looks like: -
- - -
- public class MyDomainListener implements IDomainListener
- {
- public boolean listeningTo(DomainEvent e)
- {
- // check if we care about this event
- ...
- }
-
- public void domainChanged(DomainEvent e)
- {
- // get the data from this event
- ...
- }
- }
-
-
-
-
-A domain listener may either listen for the duration of a DataStore session or may be transient, to be used for
-a receiving data from a particular command. For example, after calling DataStore.command, which returns
-the status of the command instance, a listener can be added as follows:
-
- ... - MyDomainListener listener = new MyDomainListener(shell); - `ds.getDomainNotifier().addDomainListener(listener); - listener.setStatus(status); - ... -- - + + + + + + +
+If you're writing an RSE subsystem to connect to a local standalone DataStore, the following needs +to be done during the connect: +
+ + +
+ ...
+ ClientConnection clientConnection = new ClientConnection(connectionName);
+
+ // initialize the local datastore
+ clientConnection.localConnect();
+
+ DataStore dataStore = clientConnection.getDataStore();
+
+ // specify miners to load
+ dataStore.addMinersLocation("."); // initializes the default miners
+
+ // initialize miners
+ dataStore.getSchema();
+ dataStore.initMiners();
+ ...
+
+
+
+
+
+If you're writing an RSE subsystem to connect to a remote DataStore, the only difference
+from the local scenario is that connect is called rather than localConnect.
+
+ ...
+ ClientConnection clientConnection = new ClientConnection(connectionName);
+
+ // prepare connection
+ clientConnection.setHost(hostName);
+ clientConnection.setPort(port);
+
+ // connect
+ clientConnection.connect(ticket);
+
+ DataStore dataStore = clientConnection.getDataStore();
+
+ // specify miners to load
+ dataStore.addMinersLocation("."); // initializes the default miners
+
+ // initialize miners
+ dataStore.getSchema();
+ dataStore.initMiners();
+ ...
+
+
+
+
++If the new miner has been registered via the default minerFile.dat file, then +no further steps are required to load it. Otherwise, after the subsystem is +connected to the remote DataStore, you need to tell the DataStore to load the +miner as follows. +
+ + ++ ... + dataStore.addMinersLocation(location); + dataStore.getSchema(); + ... ++ + +
+This tells the host DataStore to instantiate and initialize all miners listed in +the specified minerFile.dat file. +
+ + +
+To send a command to a miner, the required command descriptor must first be obtained
+using the method DataStore.localDescriptorQuery. The method DataStore.command is then called with command
+descriptor and the subject of the command. For example, a query might need to be called on the miner as shown in the following code segment.
+
+ ... + // the UI model object + MyRemoteObject obj = getMyRemoteObject(); + + // get the corresponding DataElement for this object + DataElement deObj = obj.getDataElement(); + + // get the DataStore from the DataElement + DataStore ds = deObj.getDataStore(); + + // get the query command descriptor for the subject + DataElement queryCmd = ds.localDescriptorQuery(deObj.getDescriptor(), "MY_QUERY_COMMAND"); + + // send the command + DataElement status = ds.command(queryCmd, deObj, true); + ... ++ + +
+After a command is sent to a miner, you might want to receive information that the miner produced in response to the command.
+DataStore commands and responses are sent asynchronously, much like events. On the server, the
+Server Command Handler reacts to incoming commands by calling the handleCommand
+method on the appropriate miner. For the client, the Client Command Handler
+reacts to incoming responses by firing domain notifications. In order to receive miner responses, asynchronously,
+you need to implement a DataStore domain listener.
+
+A domain listener implements the IDomainListener interface. An instance of an IDomainListener needs to be added to the DataStore domain listener +list. The following is what a simple domain listener looks like: +
+ + +
+ public class MyDomainListener implements IDomainListener
+ {
+ public boolean listeningTo(DomainEvent e)
+ {
+ // check if we care about this event
+ ...
+ }
+
+ public void domainChanged(DomainEvent e)
+ {
+ // get the data from this event
+ ...
+ }
+ }
+
+
+
+
+A domain listener may either listen for the duration of a DataStore session or may be transient, to be used for
+a receiving data from a particular command. For example, after calling DataStore.command, which returns
+the status of the command instance, a listener can be added as follows:
+
+ ... + MyDomainListener listener = new MyDomainListener(shell); + `ds.getDomainNotifier().addDomainListener(listener); + listener.setStatus(status); + ... ++ + \ No newline at end of file diff --git a/rse/doc/org.eclipse.dstore.doc.isv/guide/Communications.html b/rse/doc/org.eclipse.dstore.doc.isv/guide/Communications.html index 453c1f3c3f1..3cad8e80440 100755 --- a/rse/doc/org.eclipse.dstore.doc.isv/guide/Communications.html +++ b/rse/doc/org.eclipse.dstore.doc.isv/guide/Communications.html @@ -1,159 +1,159 @@ - - - - - - -
-Communication in the DataStore is asynchronous and symmetric. Commands sent and results received are all represented in the same form, -DataElements and the underlying means of transmitting this information is basically the same for each. -When a command is issued, it gets queued and then later routed to the appropriate miner where it gets executed. -A miner returns results by updating the DataStore repository with information. Like commands, these -results are queued and then later notifications are sent out to any listener that requires the results. -
--The asynchronous routing of data and commands between a client and the tools is made possible by threads, called handlers. There are two -types of handlers - a Command Handler and an Update Handler. Each handler thread contains a queue -of data that needs to be transmitted and each periodically communicates the data contained in it's queue. -
- --The job of the Command Handler is to route commands to the miners. There are two types of command handlers. -
- --The Client Command Handler is a command handler responsible for transmitting it's queue of DataStore commands across a network to -the server DataStore. This handler encapsulates the communication of DataStore client data to a DataStore server. The Client Command Handler -interfaces the DataStore communication layer, where it's queue of commands gets serialized into XML before being sent over a TCP/IP socket -to the server. -
- --The job of the Update Handler is to notify the client that some results have been received or changed. There are two types of -update handlers. -
- --The Client Update Handler is an update handler responsible for sending out domain notifications for each unit of data -contained in it's queue. -
- --The Server Update Handler is an update handler responsible for transmitting it's queue of DataStore objects across a network to -the client DataStore. This handler encapsulates the communication of DataStore server data to a DataStore client. The Server Update Handler -interfaces the DataStore communication layer, where it's queue of data gets serialized into XML before being sent over a TCP/IP socket -to the client. -
- --Communication between a client and tools may either occur locally and remotely depending on how the -user chooses to connect to the DataStore. The client interface and the server tooling are the same regardless of -whether the DataStore is standalone or client/server based. The communication differences are encapsulated by -the DataStore handlers. -
- --Locally, the DataStore may be used standalone such that all communication through the DataStore goes directly to between the miners -and the client, all running within the same process. In this case, there is only a single DataStore and no communication goes -over the network. For it's handlers, the local DataStore uses a Client Update Handler and a Server Command Handler. -
- -
-
--In the above dialog, the path of commands to the tools is shown with solid lines, while the path of data to client is shown with dotted lines. - -
-In the remote case, a DataStore client is part of the Eclipse process, while the DataStore server is run -in a separate process on a remote host. Information is transferred between the two DataStore repositories over -a TCP/IP socket. Any data that is created or changed on either the client or the server is asynchronously -propagated over to the other side via serialization/deserialization of the delta. - -Like in the standalone case, the client DataStore uses a Client Update Handler, but instead of using -a Server Command Handler it uses a Client Command Handler. The server DataStore uses a Server Update Handler -and a Server Command Handler. -
- -
-
-+Communication in the DataStore is asynchronous and symmetric. Commands sent and results received are all represented in the same form, +DataElements and the underlying means of transmitting this information is basically the same for each. +When a command is issued, it gets queued and then later routed to the appropriate miner where it gets executed. +A miner returns results by updating the DataStore repository with information. Like commands, these +results are queued and then later notifications are sent out to any listener that requires the results. +
++The asynchronous routing of data and commands between a client and the tools is made possible by threads, called handlers. There are two +types of handlers - a Command Handler and an Update Handler. Each handler thread contains a queue +of data that needs to be transmitted and each periodically communicates the data contained in it's queue. +
+ ++The job of the Command Handler is to route commands to the miners. There are two types of command handlers. +
+ ++The Client Command Handler is a command handler responsible for transmitting its queue of DataStore commands across a network to +the server DataStore. This handler encapsulates the communication of DataStore client data to a DataStore server. The Client Command Handler +interfaces the DataStore communication layer, where its queue of commands gets serialized into XML before being sent over a TCP/IP socket +to the server. +
+ ++The job of the Update Handler is to notify the client that some results have been received or changed. There are two types of +update handlers. +
+ ++The Client Update Handler is an update handler responsible for sending out domain notifications for each unit of data +contained in its queue. +
+ ++The Server Update Handler is an update handler responsible for transmitting its queue of DataStore objects across a network to +the client DataStore. This handler encapsulates the communication of DataStore server data to a DataStore client. The Server Update Handler +interfaces the DataStore communication layer, where its queue of data gets serialized into XML before being sent over a TCP/IP socket +to the client. +
+ ++Communication between a client and tools may either occur locally and remotely depending on how the +user chooses to connect to the DataStore. The client interface and the server tooling are the same regardless of +whether the DataStore is standalone or client/server based. The communication differences are encapsulated by +the DataStore handlers. +
+ ++Locally, the DataStore may be used standalone such that all communication through the DataStore goes directly to between the miners +and the client, all running within the same process. In this case, there is only a single DataStore and no communication goes +over the network. For its handlers, the local DataStore uses a Client Update Handler and a Server Command Handler. +
+ +
+
++In the above dialog, the path of commands to the tools is shown with solid lines, while the path of data to client is shown with dotted lines. + +
+In the remote case, a DataStore client is part of the Eclipse process, while the DataStore server is run +in a separate process on a remote host. Information is transferred between the two DataStore repositories over +a TCP/IP socket. Any data that is created or changed on either the client or the server is asynchronously +propagated over to the other side via serialization/deserialization of the delta. + +Like in the standalone case, the client DataStore uses a Client Update Handler, but instead of using +a Server Command Handler it uses a Client Command Handler. The server DataStore uses a Server Update Handler +and a Server Command Handler. +
+ +
+
+
-All information in the DataStore repository is stored in the form of DataElements. DataElements are objects
-that have attributes and may contain other DataElements. The attributes of a DataElement are stored as an array of
-strings. A particular attribute is retrieved by calling getAttribute(attribute index).
-A particular attribute is set by calling setAttribute(attribute index, attribute value).
-The attribute indices that can be used are as follows:
-
| Attribute | Description |
A_TYPE | Attribute indicating the type of object. The type can be used to indicate the type of an instance of data, a descriptor, a relationship or a commnad. |
A_NAME | Attribute indicating the name of object. |
A_VALUE | Attribute indicating the more information about that object |
A_SOURCE | Attribute indicating source information about an object, if applicable |
A_ISREF | Attribute indicating whether a the object is a reference or not. In the DataStore, a reference to another DataElement is represented with a DataElement |
A_ID | The unique ID of a DataElement. |
-Rather than representing different types of objects as different classes, the type attribute of a DataElement -indicates it's type. There are two general categories of DataElements. There are schema elements, descriptors, and instances of -those schema elements, instances. -
- -
-A descriptor is a DataElement that describes some type of object. The A_TYPE attribute of a descriptor indicates what type of
-descriptor it is. The A_NAME attribute of a descriptor identifies the type that the descriptor describes.
-
-A descriptor may be of one of the following types: -
-T_OBJECT_DESCRIPTOR | Describes a type of object |
T_RELATION_DESCRIPTOR | Describes a type of relationship that may exist between two DataElements. |
T_COMMAND_DESCRIPTOR | Describes a type of command |
-Object descriptors describe the different types of data that can be represented in the DataStore repository. Object descriptors -can describe types of object instances as well as other types of object descriptors. Each object descriptor is related to other object, -relationship and command descriptors. -
- --Relation descriptors describe the different types of relationships that can be represented in the DataStore repository. Relation -descriptors describe types of relationships between object instances, object descriptors, command instances and command descriptors. -
- -
-Command descriptors describe the different types of commands that can be executed on an object in the DataStore repository.
-In the DataStore schema, object descriptors are related to command descriptors to indicate that an object instance of a certain type can
-have the described command run on it. Command descriptors are always contained by the object descriptors they are associated with. The
-A_SOURCE attribute of a command descriptor indicates which miner(s) may execute an instance of such a command.
-
-These three types of objects are used to define the DataStore schema. Instances of relation descriptors are used to define -relationships between descriptors in the schema. -
- - -
-An instance object is a DataElement that is an instance of a descriptor. An instance may either by an object, a
-relation or a command. An instance uses it's descriptor's A_NAME attribute as it's A_TYPE attribute.
-
-Objects are instances of object descriptors. Objects are used to the represent the external or internal -entities that are being interacted with. An instance object can be related in a certain way to another type of -instance object if it's object descriptor has the same kind of relationship to the other object's object descriptor. -An instance object may be associated with a particular command if it's object descriptor is associated with the command descriptor -for that command. -
- -
-Relations are instances of relation descriptors. A relation is really a typed reference to another object. Relations
-may exist from one object to another if the schema indicates that the object descriptor for the first object may have a relationship
-of that type to the other object's descriptor. Relations are used to describe the relationship between two instances, the
-relationship between two descriptors and the relationship between an instance and a descriptor. A relation is able to reference
-another element by storing the other element's A_ID attribute in it's A_SOURCE attribute. If a relation object
-needs to be dereferenced, it uses this attribute to query the DataStore for the object being referenced.
-
-A relation is typically represented by having an instance object DataElement contain a relation DataElement. -There are two types of relationships between elements that are implicit. These are the contains and -the parent of relationships. If an element is directly contained within another element, the -relationship between those two elements is implied to be contains/parent of relationships. -
- -
-Commands are instances of command descriptors. A command is always associated with a instance object such that
-the command is to be performed on that object. The object associated with a command is referred to as the subject of
-the command. Only a command that has a command descriptor that is related to the object descriptor of the subject may be
-constructed. A command object is constructed when the DataStore method command() is called. The command is
-created with a reference to the subject, an optional set of arguments, also instance objects, and a status object instance, used
-to indicate the state of the command. The tree of elements for a command is communicated, via the DataStore comm layer, to
-the appropriate miner(s), where it is interpretted and executed.
-
-The structure of a command looks like the following: -
--As an example, suppose the DataStore is being used for browsing a filesystem. The filesystem entities and how to interact -with the filesystem needs to be defined in the schema. The following descriptors could be used to describe this. -
- --Now that all the required descriptors are defined, relations between descriptors are needed. Note that the -symbol "->" implies a "contains" relationship and "IO()" implies an instance of a specified descriptor. -
- -
-DataStore schemas are created by the DataStore miners. Each tool contributes it's
-own schema or to the DataStore schema, referencing descriptors of other schemas, such
-that one tool can contribute to another tool. All the command descriptors that are
-contributed by a miner are expected to be handled by the contributing miner. Whenever
-a miner creates a new command descriptor, the A_SOURCE attribute indicates
-to the DataStore that an instance of that command should be routed to that miner when
-it's issued.
-
- -
-See the section, Miners to find out how miners contribute schemas -and execute commands. -
- + + + + + + +
+All information in the DataStore repository is stored in the form of DataElements. DataElements are objects
+that have attributes and may contain other DataElements. The attributes of a DataElement are stored as an array of
+strings. A particular attribute is retrieved by calling getAttribute(attribute index).
+A particular attribute is set by calling setAttribute(attribute index, attribute value).
+The attribute indices that can be used are as follows:
+
| Attribute | Description |
A_TYPE | Attribute indicating the type of object. The type can be used to indicate the type of an instance of data, a descriptor, a relationship or a commnad. |
A_NAME | Attribute indicating the name of object. |
A_VALUE | Attribute indicating the more information about that object |
A_SOURCE | Attribute indicating source information about an object, if applicable |
A_REF_TYPE | Attribute indicating whether the object is a normal object ("value"), a spirit ("spirit"), or a reference to another DataElement ("reference"). In the DataStore, a reference to another DataElement is represented with a DataElement. For more information on spirit elements, see Memory Management in DataStore |
A_ID | The unique ID of a DataElement. |
+Rather than representing different types of objects as different classes, the type attribute of a DataElement +indicates its type. There are two general categories of DataElements. There are schema elements, descriptors, and instances of +those schema elements, instances. +
+ +
+A descriptor is a DataElement that describes some type of object. The A_TYPE attribute of a descriptor indicates what type of
+descriptor it is. The A_NAME attribute of a descriptor identifies the type that the descriptor describes.
+
+A descriptor may be of one of the following types: +
+T_OBJECT_DESCRIPTOR | Describes a type of object |
T_RELATION_DESCRIPTOR | Describes a type of relationship that may exist between two DataElements. |
T_COMMAND_DESCRIPTOR | Describes a type of command |
+Object descriptors describe the different types of data that can be represented in the DataStore repository. Object descriptors +can describe types of object instances as well as other types of object descriptors. Each object descriptor is related to other object, +relationship and command descriptors. +
+ ++Relation descriptors describe the different types of relationships that can be represented in the DataStore repository. Relation +descriptors describe types of relationships between object instances, object descriptors, command instances and command descriptors. +
+ +
+Command descriptors describe the different types of commands that can be executed on an object in the DataStore repository.
+In the DataStore schema, object descriptors are related to command descriptors to indicate that an object instance of a certain type can
+have the described command run on it. Command descriptors are always contained by the object descriptors they are associated with. The
+A_SOURCE attribute of a command descriptor indicates which miner(s) may execute an instance of such a command.
+
+These three types of objects are used to define the DataStore schema. Instances of relation descriptors are used to define +relationships between descriptors in the schema. +
+ + +
+An instance object is a DataElement that is an instance of a descriptor. An instance may either by an object, a
+relation or a command. An instance uses its descriptor's A_NAME attribute as its A_TYPE attribute.
+
+Objects are instances of object descriptors. Objects are used to the represent the external or internal +entities that are being interacted with. An instance object can be related in a certain way to another type of +instance object if its object descriptor has the same kind of relationship to the other object's object descriptor. +An instance object may be associated with a particular command if its object descriptor is associated with the command descriptor +for that command. +
+ +
+Relations are instances of relation descriptors. A relation is really a typed reference to another object. Relations
+may exist from one object to another if the schema indicates that the object descriptor for the first object may have a relationship
+of that type to the other object's descriptor. Relations are used to describe the relationship between two instances, the
+relationship between two descriptors and the relationship between an instance and a descriptor. A relation is able to reference
+another element by storing the other element's A_ID attribute in its A_SOURCE attribute. If a relation object
+needs to be dereferenced, it uses this attribute to query the DataStore for the object being referenced.
+
+A relation is typically represented by having an instance object DataElement contain a relation DataElement. +There are two types of relationships between elements that are implicit. These are the contains and +the parent of relationships. If an element is directly contained within another element, the +relationship between those two elements is implied to be contains/parent of relationships. +
+ +
+Commands are instances of command descriptors. A command is always associated with an instance object such that
+the command is to be performed on that object. The object associated with a command is referred to as the subject of
+the command. Only a command that has a command descriptor that is related to the object descriptor of the subject may be
+constructed. A command object is constructed when the DataStore method command() is called. The command is
+created with a reference to the subject, an optional set of arguments, also instance objects, and a status object instance, used
+to indicate the state of the command. The tree of elements for a command is communicated, via the DataStore comm layer, to
+the appropriate miner(s), where it is interpreted and executed.
+
+The structure of a command looks like the following: +
++As an example, suppose the DataStore is being used for browsing a filesystem. The filesystem entities and how to interact +with the filesystem needs to be defined in the schema. The following descriptors could be used to describe this. +
+ ++Now that all the required descriptors are defined, relations between descriptors are needed. Note that the +symbol "->" implies a "contains" relationship and "IO()" implies an instance of a specified descriptor. +
+ +
+DataStore schemas are created by the DataStore miners. Each tool contributes it's
+own schema to the DataStore schema, referencing descriptors of other schemas, such
+that one tool can contribute to another tool. All the command descriptors that are
+contributed by a miner are expected to be handled by the contributing miner. Whenever
+a miner creates a new command descriptor, the A_SOURCE attribute indicates
+to the DataStore that an instance of that command should be routed to that miner when
+it's issued.
+
+ +
+See the section, Miners to find out how miners contribute schemas +and execute commands. +
+ \ No newline at end of file diff --git a/rse/doc/org.eclipse.dstore.doc.isv/guide/Extending.html b/rse/doc/org.eclipse.dstore.doc.isv/guide/Extending.html index 206d88b8684..a136e4b6de3 100755 --- a/rse/doc/org.eclipse.dstore.doc.isv/guide/Extending.html +++ b/rse/doc/org.eclipse.dstore.doc.isv/guide/Extending.html @@ -1,18 +1,18 @@ - - - - - - --This section describes the basic steps required for to extending the server DataStore with -a DataStore miner and how to interact with the miners from an RSE subsystem. -
- + + + + + + ++This section describes the basic steps required for extending the server DataStore with +a DataStore miner and how to interact with the miners from an RSE subsystem. +
+ \ No newline at end of file diff --git a/rse/doc/org.eclipse.dstore.doc.isv/guide/Miners.html b/rse/doc/org.eclipse.dstore.doc.isv/guide/Miners.html index 4dacb9448ac..525a9d79375 100755 --- a/rse/doc/org.eclipse.dstore.doc.isv/guide/Miners.html +++ b/rse/doc/org.eclipse.dstore.doc.isv/guide/Miners.html @@ -1,142 +1,142 @@ - - - - - - --Miners are remote tooling extensions to the DataStore. Each miner describes the model -that it works with as well as the commands associated with the model that it implements. Each -miner is responsible for extending the DataStore schema and providing implementations for -commands that it defines. -
-
-All miners are derived from the abstract class Miner. To write a miner, the
-following APIs need to be implemented:
-
- public abstract void extendSchema(DataElement schemaRoot); - public abstract DataElement handleCommand(DataElement theCommand); --
-The first method, extendSchema, is implemented by a miner to contribute the types of objects, relationships and commands that
-it deals with. The second method, handleCommand, is implemented by a miner so that it can execute the commands it defines.
-
-A miner extends the DataStore schema by populating the schemaRoot with descriptors. -The DataStore repository tree is structured so that there is a single node where schema descriptors reside. All -object descriptors and relation descriptors -are created under this schema root. Command descriptors are created under the -object descriptors that they apply to. Each miner contributes to this global DataStore schema, so each may also extend or leverage the -information from another miner's schema. -
-
-A miner implements extendSchema(DataElement) to add new descriptors to the DataStore schema. If a miner creates representations
-of objects that are not already represented by some other miner's schema, then it needs to define descriptors for those new types of objects.
-Sometimes new relationship types also need to be defined by a miner for it's particular model. In order for a miner to be interacted with,
-via handleCommand, it needs to define command descriptors for object descriptors in the schema. The code below illustrates the
-typical structure of an extendSchema implementation:
-
- public void extendSchema(DataElement schemaRoot)
- {
- // create object descriptors
- DataElement myObjectType1 = createObjectDescriptor(schemaRoot, "my object type 1");
- DataElmeent myObjectType2 = createObjectDescriptor(schemaRoot, "my object type 2");
- DataElement myObjectContainerType = createObjectDescriptor(schemaRoot, "my object container");
-
- // create relation descriptors
- DataElement myRelationType = createRelationDescriptor(schemaRoot, "my relation type");
-
- // create command descriptors
- createCommandDescriptor(myObjectType1, "My Command 1", MY_COMMAND_1);
- createCommandDescriptor(myObjectType2, "My Command 2", MY_COMMAND_2);
- createCommandDescriptor(myObjectContainerType, "Query", MY_QUERY);
-
- // establish relationships between object types
- createReference(myObjectType1, myObjectType2, myRelationType); // myObjectType1 instances can be associated with myObjectType2 instances by myRelationType
- createReference(myObjectContainerType, myObjectType1); // myObjectContainerType instances can contain myObjectType1 instances
- createReference(myObjectContainerType, myObjectType2); // myObjectContainerType instances can contain myObjectType2 instances
-
- ...
- }
-
-
-
--The DataStore does not enforce that instance element trees are structured in the manner that the schema describes so the -establishing of relationships between object types, as done in this example, is unnecessary as a miner knows it's own -model, since it defined it. But by convention, it is a good thing to describe a model with those relationships explicitly stated -because other miners or client tools may want to leverage or extend the model for their own purposes. -
- - -
-The handleCommand method is called by the Server Command Handler
-if the descriptor for a command instance is associated with a particular miner. When this is called, it is up to the miner implementation
-to interpret and execute the command.
-
-A Command instance is a tree of DataElements representing the -command, the subject of the command, additional arguments to the command and the status of the command. The way this is normally interpretted -by a miner to mean perform the specified command on the subject using the specified arguments. Change the status to be "done" when the -operation is complete.. -
-
-The base miner class provides APIs to assist a miner implementation in extracting information from
-a command tree. The method getCommandName(DataElement) is used to extract the
-name of the command, getCommandStatus(DataElement) returns the status element of
-the command, and getCommandArgument(DataElement, int) returns an argument at the
-specified index. The first argument is always the subject. The code below illustrates
-the typical structure of a handleCommand implementation.
-
- public DataElement handleCommand(DataElement theElement)
- {
- String name = getCommandName(theElement);
- DataElement status = getCommandStatus(theElement);
- DataElement subject = getCommandArgument(theElement, 0);
-
- if (name.equals(MY_COMMAND_1))
- {
- handleMyCommand1(subject, arg1,...,argn, status);
- }
- ...
- status.setAttribute(DE.A_NAME, "done");
- _dataStore.refresh(status);
- }
-
-
--The results of a command may be returned in a variety of ways, depending one it's -purpose. One thing that is always returned is the status object. -
--Think of the status object as the return value of a method. The status object needs to be set to "done" -whenever a command is complete but it may also optionally contain results in the form -of DataElements. If a command is requesting transient information about something, then -the status object could be populated with the results. -
--Each miner has read and write access to the entire DataStore tree. If desired a miner -can modify that tree as a result of a command. For example, a miner used for browsing -a file system might populate the subject, a folder object, with other folder and file -objects, rather than transiently via the status object. In this way, a miner caches -data and expands the data available to the DataStore repository in response to user -requests. -
- + + + + + + ++Miners are remote tooling extensions to the DataStore. Each miner describes the model +that it works with as well as the commands associated with the model that it implements. Each +miner is responsible for extending the DataStore schema and providing implementations for +commands that it defines. +
+
+All miners are derived from the abstract class Miner. To write a miner, the
+following APIs need to be implemented:
+
+ public abstract void extendSchema(DataElement schemaRoot); + public abstract DataElement handleCommand(DataElement theCommand); ++
+The first method, extendSchema, is implemented by a miner to contribute the types of objects, relationships and commands that
+it deals with. The second method, handleCommand, is implemented by a miner so that it can execute the commands it defines.
+
+A miner extends the DataStore schema by populating the schemaRoot with descriptors. +The DataStore repository tree is structured so that there is a single node where schema descriptors reside. All +object descriptors and relation descriptors +are created under this schema root. Command descriptors are created under the +object descriptors that they apply to. Each miner contributes to this global DataStore schema, so each may also extend or leverage the +information from another miner's schema. +
+
+A miner implements extendSchema(DataElement) to add new descriptors to the DataStore schema. If a miner creates representations
+of objects that are not already represented by some other miner's schema, then it needs to define descriptors for those new types of objects.
+Sometimes new relationship types also need to be defined by a miner for its particular model. In order for a miner to be interacted with,
+via handleCommand, it needs to define command descriptors for object descriptors in the schema. The code below illustrates the
+typical structure of an extendSchema implementation:
+
+ public void extendSchema(DataElement schemaRoot)
+ {
+ // create object descriptors
+ DataElement myObjectType1 = createObjectDescriptor(schemaRoot, "my object type 1");
+ DataElmeent myObjectType2 = createObjectDescriptor(schemaRoot, "my object type 2");
+ DataElement myObjectContainerType = createObjectDescriptor(schemaRoot, "my object container");
+
+ // create relation descriptors
+ DataElement myRelationType = createRelationDescriptor(schemaRoot, "my relation type");
+
+ // create command descriptors
+ createCommandDescriptor(myObjectType1, "My Command 1", MY_COMMAND_1);
+ createCommandDescriptor(myObjectType2, "My Command 2", MY_COMMAND_2);
+ createCommandDescriptor(myObjectContainerType, "Query", MY_QUERY);
+
+ // establish relationships between object types
+ createReference(myObjectType1, myObjectType2, myRelationType); // myObjectType1 instances can be associated with myObjectType2 instances by myRelationType
+ createReference(myObjectContainerType, myObjectType1); // myObjectContainerType instances can contain myObjectType1 instances
+ createReference(myObjectContainerType, myObjectType2); // myObjectContainerType instances can contain myObjectType2 instances
+
+ ...
+ }
+
+
+
++The DataStore does not enforce that instance element trees are structured in the manner that the schema describes so the +establishing of relationships between object types, as done in this example, is unnecessary as a miner knows its own +model, since it defined it. But by convention, it is a good thing to describe a model with those relationships explicitly stated +because other miners or client tools may want to leverage or extend the model for their own purposes. +
+ + +
+The handleCommand method is called by the Server Command Handler
+if the descriptor for a command instance is associated with a particular miner. When this is called, it is up to the miner implementation
+to interpret and execute the command.
+
+A Command instance is a tree of DataElements representing the +command, the subject of the command, additional arguments to the command and the status of the command. The way this is normally interpretted +by a miner to mean perform the specified command on the subject using the specified arguments. Change the status to be "done" when the +operation is complete.. +
+
+The base miner class provides APIs to assist a miner implementation in extracting information from
+a command tree. The method getCommandName(DataElement) is used to extract the
+name of the command, getCommandStatus(DataElement) returns the status element of
+the command, and getCommandArgument(DataElement, int) returns an argument at the
+specified index. The first argument is always the subject. The code below illustrates
+the typical structure of a handleCommand implementation.
+
+ public DataElement handleCommand(DataElement theElement)
+ {
+ String name = getCommandName(theElement);
+ DataElement status = getCommandStatus(theElement);
+ DataElement subject = getCommandArgument(theElement, 0);
+
+ if (name.equals(MY_COMMAND_1))
+ {
+ handleMyCommand1(subject, arg1,...,argn, status);
+ }
+ ...
+ status.setAttribute(DE.A_NAME, "done");
+ _dataStore.refresh(status);
+ }
+
+
++The results of a command may be returned in a variety of ways, depending on its +purpose. One thing that is always returned is the status object. +
++Think of the status object as the return value of a method. The status object needs to be set to "done" +whenever a command is complete but it may also optionally contain results in the form +of DataElements. If a command is requesting transient information about something, then +the status object could be populated with the results. +
++Each miner has read and write access to the entire DataStore tree. If desired a miner +can modify that tree as a result of a command. For example, a miner used for browsing +a file system might populate the subject, a folder object, with other folder and file +objects, rather than transiently via the status object. In this way, a miner caches +data and expands the data available to the DataStore repository in response to user +requests. +
+ \ No newline at end of file diff --git a/rse/doc/org.eclipse.dstore.doc.isv/guide/ServerSide.html b/rse/doc/org.eclipse.dstore.doc.isv/guide/ServerSide.html index 15c06be9264..5ec50b7b93a 100755 --- a/rse/doc/org.eclipse.dstore.doc.isv/guide/ServerSide.html +++ b/rse/doc/org.eclipse.dstore.doc.isv/guide/ServerSide.html @@ -1,36 +1,36 @@ - - - - - - --This section describes the basic steps needed to extend the server side tooling using Miners. -
-+This section describes the basic steps needed to extend the server side tooling using Miners. +
+-The RSE uses the concept of subsystems as a common abstraction for remote tooling. Subsystems provide -public interfaces that are called when some remote tool or resource needs to be communicated with. As long as -the appropriate public interfaces are implemented, the means of communicating with these remote tools and resources -is up to the developer of the subsystem. Whatever that means might be, some kind of communication layer is required -to access tools on the host. One such means that is used by existing RSE Subsystems and can be reused is the -DataStore framework. -
--The DataStore communications framework is used to provide remote access and tooling for the Remote Systems Explorer. -It is a communications layer, in-memory data repository and a pluggable tooling framework. While Eclipse provides -the ability for local tools to plug into the Eclipse workbench, DataStore provides the ability to integrate -remote tools into the Remote Systems Explorer. When implementing subsystem APIs, a particular implementation -may provide remote function by leveraging DataStore. -
- -
-
--In an RSE subsystem, the goal of the DataStore is to provide the bridge to tools and resources on the host. -To interact with a remote tool, a DataStore client communicates over a network with a DataStore server. Data and -commands are transferred between the client and server via the DataStore communication layer. Information -that is communicated between each side is kept in memory with the DataStore repository. Both the client and server DataStores -have this repository and it is the responsability of the DataStore communication layer to keep the contents -of each of these repositories in synch. All the DataStore data on the server side is replicated to the client and -and vice versa. -
--The DataStore framework is generic in the sense that it can be used to facilitate any kind of remote tooling. There are -no specialized APIs or artifacts that are geered towards a particular use. How DataStore is used is determined by the -tool extensions, Miners. Miners are typically either adapters to -tools on the host or are tools themselves. These extensions determine the meaning of data used to represent objects, -relationships and the commands that can be issued on the represented objects. Miners shape the -DataStore by contributing schemas to the pool of information in a DataStore repository. -Because the client and server DataStore repositories are synchronized, the DataStore clients -have access to the miner schemas and, using that information, they are able to communicate with the tools on the host. -Because the server has access to those miner schemas, each Miners may also communicate with -other Miners on the host in the same way a client can. -
--A Filesystem miner can shape the DataStore by contributing a schema that -describes file systems and how they should be interacted with. The schema could describe -files, folders, properties of files and relationships between them as well as commands for querying folders or renaming files. -An RSE subsystem, can then provide browsing capabilities to a remote file system by sending commands -via the DataStore client to the Filesystem Miner on the host. Another miner can -contribute it's own schema or extend the existing Filesystem Miner schema -to leverage or contribute to the existing file system tool. -
--This guide explains all underlying -artifacts and model of the DataStore, it's relationship to RSE, and highlights the -important APIs available for your use. -
- + + + + + + ++The RSE uses the concept of subsystems as a common abstraction for remote tooling. Subsystems provide +public interfaces that are called when some remote tool or resource needs to be communicated with. As long as +the appropriate public interfaces are implemented, the means of communicating with these remote tools and resources +is up to the developer of the subsystem. Whatever that might be, some kind of communication layer is required +to access tools on the host. One such means that is used by existing RSE Subsystems and can be reused is the +DataStore framework. +
++The DataStore communications framework is used to provide remote access and tooling for the Remote Systems Explorer. +It is a communications layer, in-memory data repository and a pluggable tooling framework. While Eclipse provides +the ability for local tools to plug into the Eclipse workbench, DataStore provides the ability to integrate +remote tools into the Remote Systems Explorer. When implementing subsystem APIs, a particular implementation +may provide remote function by leveraging DataStore. +
+ +
+
++In an RSE subsystem, the goal of the DataStore is to provide the bridge to tools and resources on the host. +To interact with a remote tool, a DataStore client communicates over a network with a DataStore server. Data and +commands are transferred between the client and server via the DataStore communication layer. Information +that is communicated between each side is kept in memory with the DataStore repository. Both the client and server DataStores +have this repository and it is the responsibility of the DataStore communication layer to keep the contents +of each of these repositories in sync. All the DataStore data on the server side is replicated to the client and +and vice versa. +
++The DataStore framework is generic in the sense that it can be used to facilitate any kind of remote tooling. There are +no specialized APIs or artifacts that are geered towards a particular use. How DataStore is used is determined by the +tool extensions, Miners. Miners are typically either adapters to +tools on the host or are tools themselves. These extensions determine the meaning of data used to represent objects, +relationships and the commands that can be issued on the represented objects. Miners shape the +DataStore by contributing schemas to the pool of information in a DataStore repository. +Because the client and server DataStore repositories are synchronized, the DataStore clients +have access to the miner schemas and, using that information, they are able to communicate with the tools on the host. +Because the server has access to those miner schemas, each Miners may also communicate with +other Miners on the host in the same way a client can. +
++A Filesystem miner can shape the DataStore by contributing a schema that +describes file systems and how they should be interacted with. The schema could describe +files, folders, properties of files and relationships between them as well as commands for querying folders or renaming files. +An RSE subsystem, can then provide browsing capabilities to a remote file system by sending commands +via the DataStore client to the Filesystem Miner on the host. Another miner can +contribute its own schema or extend the existing Filesystem Miner schema +to leverage or contribute to the existing file system tool. +
++This guide explains all underlying +artifacts and model of the DataStore, its relationship to RSE, and highlights the +important APIs available for your use. +
+ \ No newline at end of file diff --git a/rse/doc/org.eclipse.rse.doc.isv/guide/Artifacts.html b/rse/doc/org.eclipse.rse.doc.isv/guide/Artifacts.html index 697c2ea1916..2ba4030d7df 100755 --- a/rse/doc/org.eclipse.rse.doc.isv/guide/Artifacts.html +++ b/rse/doc/org.eclipse.rse.doc.isv/guide/Artifacts.html @@ -1,288 +1,288 @@ - - - - - - - - -With the RSE, you can create and manipulate the following artifacts, which we introduce here:
-All the classes and interfaces mentioned here are defined in the org.eclipse.rse.core plugin. - -
-The RSE's Remote Systems view shows all existing Hosts to remote systems. -Hosts are objects that are persisted, containing the information needed to access a particular remote host. -The view contains a prompt to create new Hosts, and pop-up menu actions to rename, copy, delete, and reorder existing Hosts. -
-Hosts contain attributes, or data, that is saved between sessions of the workbench. These attributes are
-the host name, the remote system's host name and system type, an optional description, and a user Id that is
-used by default by each subordinate subsystem, at host time.
-Underneath, all Hosts are stored via RSE persistence in an Eclipse project named RemoteSystemshosts, which
-the user can enable for team support, allowing Hosts to be shared by a team.
-
-To facilitate team-shared and user-unique Hosts,
-Hosts are owned by profiles. These are simply folders in the RemoteSystemshosts
-project, as it turns out, within which all other data including Hosts are scoped. Internally profiles are realized as
-SystemProfile objects, managed by the SystemProfileManager.
-For each profile there is also a SystemhostPool object
-created to manage the Hosts within that profile. There are menu actions for the
-user to create and manage profiles. The collective of all Hosts of all active profiles are shown in the Remote Systems view,
-and the user can easily decide which profiles are active using the local pulldown menu of the Remote Systems view.
-The list of profiles currently active is stored locally on each user's workstation, and not shared by the team.
-By default, there exists a profile named Team, and a profile with a name unique to this user. When the first
-host is created the user is asked to supply this unique name, which defaults to the hostname of their
-workstation. Whenever a new host is created, the user is prompted for an active profile to contain the new
-host. Both default profiles are active initially, so all Hosts from each are shown. There is a preferences
-setting to show the host names qualified by their profile name. After synchronizing the RemoteSystemshost
-project with a team repository, using the RSE team view, all profiles of all members of
-the team will exist in the user's workspace, and hence
-all the Hosts created by all the team members. However, only the two default profiles are active, so the Hosts
-in the other profiles are not seen unless the user explicitly makes another profile active. This design allows
-for:
-
-As an aside, user IDs and passwords are not shared with the team repository, but rather stored only locally per -workstation. -Each subsystem can have a unique user ID, which if not set is inherited from its host, which in turn if not set is inherited from the -user ID preferences setting for the appropriate system type. -
- --When you expand a host, any tools registered with the Remote System Explorer are shown under the host. -These tools are referred to as subsystems. The tool provider registers a subsystem configuration -class via an RSE extension point, and whenever a new host is created, the configuration -is asked to create a new subsystem object for that host. This subsystem is responsible for communicating with the remote host, and -exposing artifacts and actions for working with remote resources. The subsystem configuration can elect not to -supply a subsystem for a given host if it does not support the system type of that host -
--IBM supplies two subsystem configurations that supply common subsystems for all Hosts: -
AS400 object
-for the current session, thus avoiding redundant signon requests for the user, and inheritence of existing
-job attributes. There is also a method for returning a JDBC host object for accessing DB2/400 databases
-on that iSeries host. Both of these getter methods are available in the
-ISeries system object all iSeries
-subsystems share. System objects are described next.
-
-While not seen by the user, subsystem objects are required to return a system object via the -getSystem() method. -A system object is an object implementing the ISystem interface. -A system object manages the live host to the remote system, and supports -lifecycle methods for that host such as -connect, -disconnect, and -isConnected. -The communication layer for that host is entirely the programmer's responsibility, and might use sockets, JDBC, HTTP or -SOAP. It is up the provider of the subsystem factory to author their own communication layer; the framework -only dictates the handful of methods in ISystem, that the RSE UI depends upon. The framework supplies a base -system class that is easily extended. -
-It may be the case that multiple subsystems, each from a different subsystem factory, share the same live -host for a given host object. To enable this, the framework supplies a base -system manager class -that can be used to manage a single shared system object across multiple subsystems. It uses a hashtable to store and -return the system objects, keyed by a subsystem interface that all subsystems sharing the same system object -are to implement. The subclass of the base system manager class supplies that interface. Further, the subclass -must also implement the method for instantiating new instances of the system class, when no instance is found -in the hashtable. -
--It is possible to author a subsystem factory whose subsystems simply use the same system object as that used by -the IBM-supplied subsystems. You might do this if the subsystem factory uses only the IBM-supplied APIs for -accessing remote objects, in which case there is no need for a unique communication layer. By sharing the -same system object, it prevents the user from being prompted to signon multiple times. To do this, simply access -any IBM-supplied subsystem for a given host, and ask for its -system manager -in your own subsystem's getSystemManager method. -
- --When a subsystem is expanded, users usually see filters. Since subsystems typically list remote artifacts, -it is typical that a mechanism is needed to allow users to define which artifacts they wish to see, with some -form of filtering criteria. Filters are this mechanism. The filter support is fully supplied by the RSE framework. -A filter is simply a SystemFilter -object containing a name and a collection of filter strings. Filter strings are just strings, which -the subsystem is required to interpret. When a user expands a filter, the owning subsystem is asked to resolve -the filter strings within the filter. The subsystem typically interprets each filter string as some form of -filtering pattern, and returns a list of remote artifacts matching one or more of the filter string patterns in -the filter. For example, file subsystems expect each filter string to represent a folder, and a file name pattern. Then, all files in the folder, matching the name pattern, are returned. The subsystem supplies the user interface the -you use to create and change filter strings, so it is responsible for defining what the filter strings -look like and for subsequently resolving those filter strings on a filter expansion. A default user interface for -the filter string prompt is supplied, but it is a simple entry field. -
--It is possible to author a subsystem that does not support filters, if this is desired. -
- --Subsystems do not actually "own" filters. Since each host has unique subsystems, if each subsystem owned its -own filters then filters could not be shared across Hosts, which is sometimes desirable. Instead, filters are -actually contained within filter pools. Filter pools are simply -SystemFilterPool -objects which have a name and a collection of filters. -Filter pools are owned by subsystem configurations, per profile. That is, each subsystem factory will contain filter pools -scoped by profile. Each such factory plus profile grouping is known internally as a -filter pool manager. -Subsystems contain references -to filter pools. By default, each subsystem factory automatically creates one filter pool -for each profile, named the "xxx Filter Pool", where "xxx" is the name of the profile. Subsystems contain references to -filter pools, so that as the filters in the pool are created, changed, deleted or re-ordered, those changes are automatically -reflected in every subsystem (and hence host) that references that filter pool. By default, subsystems are given a -reference to the default filter pool in their host's profile (for their parent subsystem factory, so file filters -are not used in command subsystems, for example). -
--By default, users do not see filter pools. Instead, filters are created in the default filter pool referenced by this subsystem. -As a result, users will see the same list of filters for every host. However, users can use a preference setting to see -filter pools. In this case, when a subsystem is expanded, the users see the filter pools referenced by this subsystem. -Only then when a filter pool is expanded will the user see the filters within that filter pool. In this mode, users also -see new actions to create filter pools and to add and remove references to filter pools within a subsystem. Whenever filters -are changed by the user, this change is reflected in all subsystems that reference the parent filter pool. This design -of filter pools owned by profiles, and subsystems that reference filter pools, facilitates filter sharing: -
-If the subsystem factory returns true to the
-supportsUserDefinedActions
-method, users can create their own actions
-that appear in the pop-up menu for remote objects, using the Work With User Actions action and
-dialog. User actions use substitution variables that are resolved at
-runtime to various attributes of the selected remote objects. The actions themselves are run
-on the remote system
-of the host where the objects are listed from. User actions are instances of the
-SystemUDAActionElement
-class from the org.eclipse.rse.core.ui.uda package.
-
-
-User actions can be scoped to only appear for objects of a
-particular type. To facilitate this, users can create named types which are names that represent
-one or more types of remote objects. Internally, they are
-SystemUDTypeElement objects.
-This is done using the Work With Named Types action and
-dialog.
-User actions are contained by each subsystem factory, scoped by profile. You can programmatically access them by calling -getActionSubSystem -in a subsystem factory object. They are scoped to the factory, not the subsystem, -so the same list of actions is available for every host. The User Actions cascading menu -for remote objects lists all the actions defined for all active profiles, whose file type scoping criteria matches the -types of the currently selected remote objects. When users define new actions, they specify the profile to contain them. -This design allows for: -
Named types, however, are not scoped by profile. Rather, there is only one master list, per subsystem factory. -It is assumed there will be fewer of these, and they are not likely to be different per user. -
- --If the subsystem factory returns true to the -supportsCompileActions -method, users will see a Compile action in -the pop-up menu for compilable source files. Clearly, this support usually only makes sense for subsystems that -list remote source files. Whether a selected file is compilable or not is decided by the subsystem factory. It -actually defers this request to a compile manager, which must be programmed by subclassing the supplied base -class for this. The compile manager is also responsible for pre-supplying default compile commands. -
--The framework also supplies a Work With Compile Commands action and dialog, -by which users can create their own compile commands, -per source type. Compile commands internally are SystemCompileCommand objects. -These compile commands are stored per subsystem factory, such that they are usable across all Hosts. -They are also scoped by profile, and the cascading compile action will list all compile commands from all active profiles, -for the selected file's source type. This scoping by profile, as with user actions, enables team support such that -users can see and can easily access their own compile commands and any shared compile commands. -
- --Many of the default characterics of the Remote System Explorer view and perspective are configurable by each user -by way of the Remote Systems node of the Preferences window, accessible from the Window pull-down of the main menu. -Furthermore, many of these preferences are directly accessible from the pull-down menu of the title bar for the Remote -Systems view. These preferences, like all preferences, are unique to each user and not shared by the team, although they can -be exported and imported. -
- -The programmatic front door to all the artifacts in the RSE is the -System Registry, which is an object implementing -SystemRegistry. -This is a singleton object that you -can access by calling the static method -getTheSystemRegistry() in the -SystemPlugin -class in the org.eclipse.rse.core plugin. -
- + + + + + + + + +With the RSE, you can create and manipulate the following artifacts, which we introduce here:
+All the classes and interfaces mentioned here are defined in the org.eclipse.rse.core plugin. + +
+The RSE's Remote Systems view shows all existing Hosts to remote systems. +Hosts are objects that are persisted, containing the information needed to access a particular remote host. +The view contains a prompt to create new Hosts, and pop-up menu actions to rename, copy, delete, and reorder existing Hosts. +
+Hosts contain attributes, or data, that is saved between sessions of the workbench. These attributes are
+the host name, the remote system's host name and system type, an optional description, and a user Id that is
+used by default by each subordinate subsystem, at host time.
+Underneath, all Hosts are stored via RSE persistence in an Eclipse project named RemoteSystemshosts, which
+the user can enable for team support, allowing Hosts to be shared by a team.
+
+To facilitate team-shared and user-unique Hosts,
+Hosts are owned by profiles. These are simply folders in the RemoteSystemshosts
+project, as it turns out, within which all other data including Hosts are scoped. Internally profiles are realized as
+SystemProfile objects, managed by the SystemProfileManager.
+For each profile there is also a SystemhostPool object
+created to manage the Hosts within that profile. There are menu actions for the
+user to create and manage profiles. The collective of all Hosts of all active profiles are shown in the Remote Systems view,
+and the user can easily decide which profiles are active using the local pulldown menu of the Remote Systems view.
+The list of profiles currently active is stored locally on each user's workstation, and not shared by the team.
+By default, there exists a profile named Team, and a profile with a name unique to this user. When the first
+host is created the user is asked to supply this unique name, which defaults to the hostname of their
+workstation. Whenever a new host is created, the user is prompted for an active profile to contain the new
+host. Both default profiles are active initially, so all Hosts from each are shown. There is a preferences
+setting to show the host names qualified by their profile name. After synchronizing the RemoteSystemshost
+project with a team repository, using the RSE team view, all profiles of all members of
+the team will exist in the user's workspace, and hence
+all the Hosts created by all the team members. However, only the two default profiles are active, so the Hosts
+in the other profiles are not seen unless the user explicitly makes another profile active. This design allows
+for:
+
+As an aside, user IDs and passwords are not shared with the team repository, but rather stored only locally per +workstation. +Each subsystem can have a unique user ID, which if not set is inherited from its host, which in turn if not set is inherited from the +user ID preferences setting for the appropriate system type. +
+ ++When you expand a host, any tools registered with the Remote System Explorer are shown under the host. +These tools are referred to as subsystems. The tool provider registers a subsystem configuration +class via an RSE extension point, and whenever a new host is created, the configuration +is asked to create a new subsystem object for that host. This subsystem is responsible for communicating with the remote host, and +exposing artifacts and actions for working with remote resources. The subsystem configuration can elect not to +supply a subsystem for a given host if it does not support the system type of that host +
++RSE supplies two subsystem configurations that supply common subsystems for all Hosts: +
AS400 object
+for the current session, thus avoiding redundant signon requests for the user, and inheritence of existing
+job attributes. There is also a method for returning a JDBC host object for accessing DB2/400 databases
+on that iSeries host. Both of these getter methods are available in the
+ISeries system object all iSeries
+subsystems share. System objects are described next.
+
+While not seen by the user, subsystem objects are required to return a connectorservice object via the +getConnectorService() method. +A connectorService object is an object implementing the IConnectorService interface. +A connectorService object manages the live host to the remote system, and supports +lifecycle methods for that host such as +connect, +disconnect, and +isConnected. +The communication layer for that host is entirely the programmer's responsibility, and might use sockets, JDBC, HTTP or +SOAP. It is up the provider of the subsystem factory to author their own communication layer; the framework +only dictates the handful of methods in IConnectorService, that the RSE UI depends upon. The framework supplies a base +system class that is easily extended. +
+It may be the case that multiple subsystems, each from a different subsystem configuration, share the same live +host for a given host object. To enable this, the framework supplies a base +connector service manager class +that can be used to manage a single shared connector service object across multiple subsystems. It uses a hashtable to store and +return the connector service objects, keyed by a subsystem interface that all subsystems sharing the same connector service object +are to implement. The subclass of the base connector service manager class supplies that interface. Further, the subclass +must also implement the method for instantiating new instances of the connector service class, when no instance is found +in the hashtable. +
++It is possible to author a subsystem configuration whose subsystems simply use the same connector service object as that used by +the RSE-supplied subsystems. You might do this if the subsystem configuration uses only the RSE-supplied APIs for +accessing remote objects, in which case there is no need for a unique communication layer. By sharing the +same connector service object, it prevents the user from being prompted to signon multiple times. To do this, simply access +any RSE-supplied subsystem for a given host, and ask for its +connector service manager +in your own subsystem's getConnectorServiceManager method. +
+ ++When a subsystem is expanded, users usually see filters. Since subsystems typically list remote artifacts, +it is typical that a mechanism is needed to allow users to define which artifacts they wish to see, with some +form of filtering criteria. Filters are this mechanism. The filter support is fully supplied by the RSE framework. +A filter is simply a ISystemFilter +object containing a name and a collection of filter strings. Filter strings are just strings, which +the subsystem is required to interpret. When a user expands a filter, the owning subsystem is asked to resolve +the filter strings within the filter. The subsystem typically interprets each filter string as some form of +filtering pattern, and returns a list of remote artifacts matching one or more of the filter string patterns in +the filter. For example, file subsystems expect each filter string to represent a folder, and a file name pattern. Then, all files in the folder, matching the name pattern, are returned. The subsystem supplies the user interface the +you use to create and change filter strings, so it is responsible for defining what the filter strings +look like and for subsequently resolving those filter strings on a filter expansion. A default user interface for +the filter string prompt is supplied, but it is a simple entry field. +
++It is possible to author a subsystem that does not support filters, if this is desired. +
+ ++Subsystems do not actually "own" filters. Since each host has unique subsystems, if each subsystem owned its +own filters then filters could not be shared across Hosts, which is sometimes desirable. Instead, filters are +actually contained within filter pools. Filter pools are simply +ISystemFilterPool +objects which have a name and a collection of filters. +Filter pools are owned by subsystem configurations, per profile. That is, each subsystem configuration will contain filter pools +scoped by profile. Each such configuration plus profile grouping is known internally as a +filter pool manager. +Subsystems contain references +to filter pools. By default, each subsystem configuration automatically creates one filter pool +for each profile, named the "xxx Filter Pool", where "xxx" is the name of the profile. Subsystems contain references to +filter pools, so that as the filters in the pool are created, changed, deleted or re-ordered, those changes are automatically +reflected in every subsystem (and hence host) that references that filter pool. By default, subsystems are given a +reference to the default filter pool in their host's profile (for their parent subsystem configuration, so file filters +are not used in command subsystems, for example). +
++By default, users do not see filter pools. Instead, filters are created in the default filter pool referenced by this subsystem. +As a result, users will see the same list of filters for every host. However, users can use a preference setting to see +filter pools. In this case, when a subsystem is expanded, the users see the filter pools referenced by this subsystem. +Only then when a filter pool is expanded will the user see the filters within that filter pool. In this mode, users also +see new actions to create filter pools and to add and remove references to filter pools within a subsystem. Whenever filters +are changed by the user, this change is reflected in all subsystems that reference the parent filter pool. This design +of filter pools owned by profiles, and subsystems that reference filter pools, facilitates filter sharing: +
+If the subsystem configuration returns true to the
+supportsUserDefinedActions
+method, users can create their own actions
+that appear in the pop-up menu for remote objects, using the Work With User Actions action and
+dialog. User actions use substitution variables that are resolved at
+runtime to various attributes of the selected remote objects. The actions themselves are run
+on the remote system
+of the host where the objects are listed from. User actions are instances of the
+SystemUDAActionElement
+class from the org.eclipse.rse.core.ui.uda package.
+
+
+User actions can be scoped to only appear for objects of a
+particular type. To facilitate this, users can create named types which are names that represent
+one or more types of remote objects. Internally, they are
+SystemUDTypeElement objects.
+This is done using the Work With Named Types action and
+dialog.
+User actions are contained by each subsystem factory, scoped by profile. You can programmatically access them by calling +getSubSystemActions +in a subsystem configuration object. They are scoped to the configuration, not the subsystem, +so the same list of actions is available for every host. The User Actions cascading menu +for remote objects lists all the actions defined for all active profiles, whose file type scoping criteria matches the +types of the currently selected remote objects. When users define new actions, they specify the profile to contain them. +This design allows for: +
Named types, however, are not scoped by profile. Rather, there is only one master list, per subsystem factory. +It is assumed there will be fewer of these, and they are not likely to be different per user. +
+ ++If the subsystem configuration returns true to the +supportsCompileActions +method, users will see a Compile action in +the pop-up menu for compilable source files. Clearly, this support usually only makes sense for subsystems that +list remote source files. Whether a selected file is compilable or not is decided by the subsystem factory. It +actually defers this request to a compile manager, which must be programmed by subclassing the supplied base +class for this. The compile manager is also responsible for pre-supplying default compile commands. +
++The framework also supplies a Work With Compile Commands action and dialog, +by which users can create their own compile commands, +per source type. Compile commands internally are SystemCompileCommand objects. +These compile commands are stored per subsystem configuration, such that they are usable across all Hosts. +They are also scoped by profile, and the cascading compile action will list all compile commands from all active profiles, +for the selected file's source type. This scoping by profile, as with user actions, enables team support such that +users can see and can easily access their own compile commands and any shared compile commands. +
+ ++Many of the default characteristics of the Remote System Explorer view and perspective are configurable by each user +by way of the Remote Systems node of the Preferences window, accessible from the Window pull-down of the main menu. +Furthermore, many of these preferences are directly accessible from the pull-down menu of the title bar for the Remote +Systems view. These preferences, like all preferences, are unique to each user and not shared by the team, although they can +be exported and imported. +
+ +The programmatic front door to all the artifacts in the RSE is the +System Registry, which is an object implementing +ISystemRegistry. +This is a singleton object that you +can access by calling the static method +getSystemRegistry() in the +SystemStartHere +class in the org.eclipse.rse.ui plugin. +
+ \ No newline at end of file diff --git a/rse/doc/org.eclipse.rse.doc.isv/guide/Model.html b/rse/doc/org.eclipse.rse.doc.isv/guide/Model.html index 9dc6b02a8b2..0246777b463 100755 --- a/rse/doc/org.eclipse.rse.doc.isv/guide/Model.html +++ b/rse/doc/org.eclipse.rse.doc.isv/guide/Model.html @@ -1,53 +1,53 @@ - - - - - - - -The underlying containment model for the RSE artifacts is shown here. -
-The underlying containment model for the RSE artifacts is shown here. +
+In Eclipse, we typically launch our dialogs and wizards and menu items from an action, which is -a class that implements the JFace IAction interface. The Remote System Explorer offers classes to -help simplify the creation of action classes, especially when used together with the RSE classes for -dialogs and wizards. -
-There are two ways the Remote System Explorer API set can help you when it comes to actions: -
Here are the primary base classes the RSE supplies for actions, all of which are found in the -package com.ibm.etools.systems.core.ui.actions -in the plugin com.ibm.etools.systems.core:
-| Class | -Description | -
|---|---|
| SystemBaseAction | -This is the base action class for the other classes, and is only used directly for actions that do not - result in a dialog or wizard being presented to the user. It extends the JFace Action class, - adding to it support for properties such as the current shell and viewer and selection, as well as - overridable methods for easily enabling/disabling the action based on the selection, and a method for - setting the context help for the action. There are many other useful methods, such - as allowOnMultipleSelection(boolean) - and setContextMenuGroup(String), to - simplify when the action is enabled and where it appears in a popup menu. - | -
| SystemBaseSubMenuAction | -This base action class extends SystemBaseAction, and is used as the parent class when - for popup menu actions that are to cascade. A cascading menu is itself another menu, really, containing actions just like the primary - menu does. So, to create a cascading menu action, you simply subclass this class and override the method - populateSubMenu, where - you add all the actions to show in this cascading menu. And yes, one or more of those can themselves be cascading. The RSE views will - automatically call the method getSubMenu when populating the initial popup menu, but your own views will need to do this. | -
| SystemBaseDialogAction | -This base action class extends SystemBaseAction, and is used when the action presents the - user with a dialog, preferably a dialog that extends the RSE - SystemPromptDialog class. To use this class, subclass it and override the methods | -
| SystemBaseWizardAction | -This base action class extends SystemBaseAction, and is used when the action presents the - user with a wizard, preferably a wizard that extends the RSE AbstractSystemWizard class. | -
You may find some of the actions supplied by the RSE to be immediately re-usable in your own code, saving some -development and test effort. -All these actions can be found in package -com.ibm.etools.systems.core.ui.actions. -Further, you can find many useful actions related to the selection of remote files or folders, in package -com.ibm.etools.systems.files.ui.actions. -
- -In Eclipse, we typically launch our dialogs and wizards and menu items from an action, which is +a class that implements the JFace IAction interface. The Remote System Explorer offers classes to +help simplify the creation of action classes, especially when used together with the RSE classes for +dialogs and wizards. +
+There are two ways the Remote System Explorer API set can help you when it comes to actions: +
Here are the primary base classes the RSE supplies for actions, all of which are found in the +package +in the plugin org.eclipse.rse.ui:
+| Class | +Description | +
|---|---|
| SystemBaseAction | +This is the base action class for the other classes, and is only used directly for actions that do not + result in a dialog or wizard being presented to the user. It extends the JFace Action class, + adding to it support for properties such as the current shell and viewer and selection, as well as + overridable methods for easily enabling/disabling the action based on the selection, and a method for + setting the context help for the action. There are many other useful methods, such + as allowOnMultipleSelection(boolean) + and setContextMenuGroup(String), to + simplify when the action is enabled and where it appears in a popup menu. + | +
| SystemBaseSubMenuAction | +This base action class extends SystemBaseAction, and is used as the parent class when + for popup menu actions that are to cascade. A cascading menu is itself another menu, really, containing actions just like the primary + menu does. So, to create a cascading menu action, you simply subclass this class and override the method + populateSubMenu, where + you add all the actions to show in this cascading menu. And yes, one or more of those can themselves be cascading. The RSE views will + automatically call the method getSubMenu when populating the initial popup menu, but your own views will need to do this. | +
| SystemBaseDialogAction | +This base action class extends SystemBaseAction, and is used when the action presents the + user with a dialog, preferably a dialog that extends the RSE + SystemPromptDialog class. To use this class, subclass it and override the methods | +
| SystemBaseWizardAction | +This base action class extends SystemBaseAction, and is used when the action presents the + user with a wizard, preferably a wizard that extends the RSE AbstractSystemWizard class. | +
You may find some of the actions supplied by the RSE to be immediately re-usable in your own code, saving some +development and test effort. +All these actions can be found in package +org.eclipse.rse.ui.actions. +Further, you can find many useful actions related to the selection of remote files or folders, in package +org.eclipse.rse.files.ui.actions. +
+ +This is an example of a sample dialog written on top of the RSE base dialog class, and with -typical full error checking. -
-
-package com.ibm.etools.systems.samples.ui.frameworks.dialogs;
-
-import org.eclipse.swt.widgets.*;
-import org.eclipse.swt.events.*;
-
-import com.ibm.etools.systems.samples.*;
-
-import com.ibm.etools.systems.core.ui.dialogs.SystemPromptDialog;
-import com.ibm.etools.systems.core.ui.*;
-import com.ibm.etools.systems.core.ui.widgets.*;
-import com.ibm.etools.systems.core.ui.messages.*;
-import com.ibm.etools.systems.core.ui.validators.*;
-
-/**
- * A simple example of using the SystemPromptDialog class as the basis for a new dialog.
- */
-public class SampleDialog extends SystemPromptDialog
-{
- // gui widgets
- private SystemHistoryCombo namePrompt;
- private Text yearPrompt, monthPrompt, dayPrompt;
- // input
- private SampleCustomer inpCust;
- // validators
- private ISystemValidator nameValidator, yearValidator, monthValidator, dayValidator;
- // message
- private SystemMessage errorMessage;
-
- /**
- * Constructor for SampleDialog.
- */
- public SampleDialog(Shell shell)
- {
- super(shell, SamplesPlugin.getString("com.ibm.etools.systems.samples.ui.dialogs.dialog1.title"));
- setHelp(SamplesPlugin.HELPPREFIX + "dlg11000");
- nameValidator = new SampleNameValidator();
- yearValidator = new SampleBirthYearValidator();
- monthValidator = new SampleBirthMonthValidator();
- dayValidator = new SampleBirthDayValidator();
- }
-
- /**
- * Required parent override.
- * This is where we populate the client area
- */
- protected Control createInner(Composite parent)
- {
- int nbrColumns = 2;
- Composite parentComposite = SystemWidgetHelpers.createComposite(parent, nbrColumns);
-
- // add gui widgets...
- SystemWidgetHelpers.createLabel(parentComposite, SamplesPlugin.getResourceBundle(), "com.ibm.etools.systems.samples.ui.dialogs.dialog1.name.");
- boolean readonly = false;
- namePrompt = SystemWidgetHelpers.createHistoryCombo(parentComposite, null, "name.history.key", readonly,
- SamplesPlugin.getResourceBundle(), "com.ibm.etools.systems.samples.ui.dialogs.dialog1.name.tooltip");
-
- addSeparatorLine(parentComposite, nbrColumns);
- boolean wantBorder = false;
- SystemWidgetHelpers.createLabel(parentComposite, SamplesPlugin.getResourceBundle(),
- "com.ibm.etools.systems.samples.ui.dialogs.dialog1.birthday.verbage.", nbrColumns, wantBorder);
-
- yearPrompt = SystemWidgetHelpers.createLabeledTextField(parentComposite, null,
- SamplesPlugin.getResourceBundle(), "com.ibm.etools.systems.samples.ui.dialogs.dialog1.birthday.year.");
- monthPrompt = SystemWidgetHelpers.createLabeledTextField(parentComposite, null,
- SamplesPlugin.getResourceBundle(), "com.ibm.etools.systems.samples.ui.dialogs.dialog1.birthday.month.");
- dayPrompt = SystemWidgetHelpers.createLabeledTextField(parentComposite, null,
- SamplesPlugin.getResourceBundle(), "com.ibm.etools.systems.samples.ui.dialogs.dialog1.birthday.day.");
-
- // if given an existing object, prefill it...
- inpCust = (SampleCustomer)getInputObject();
- if (inpCust != null)
- {
- namePrompt.setText(inpCust.getName());
- yearPrompt.setText(inpCust.getYear());
- monthPrompt.setText(inpCust.getMonth());
- dayPrompt.setText(inpCust.getDay());
- }
-
-
- // add modify listeners...
- namePrompt.addModifyListener( new ModifyListener()
- {
- public void modifyText(ModifyEvent event)
- {
- if (validateName())
- validate(namePrompt.getCombo());
- }
- } );
- yearPrompt.addModifyListener( new ModifyListener()
- {
- public void modifyText(ModifyEvent event)
- {
- if (validateYear())
- validate(yearPrompt);
- }
- } );
- monthPrompt.addModifyListener( new ModifyListener()
- {
- public void modifyText(ModifyEvent event)
- {
- if (validateMonth())
- validate(monthPrompt);
- }
- } );
- dayPrompt.addModifyListener( new ModifyListener()
- {
- public void modifyText(ModifyEvent event)
- {
- if (validateDay())
- validate(monthPrompt);
- }
- } );
-
- // initialize enabled state...
- setPageComplete(isPageComplete());
-
- return parentComposite;
- }
-
- /**
- * Required parent override.
- * This is where we return the first input control, to give it focus when the dialog appears.
- */
- protected Control getInitialFocusControl()
- {
- return namePrompt.getCombo();
- }
-
- /**
- * Typical parent override.
- * This is where we get control when the user presses OK.
- */
- protected boolean processOK()
- {
- errorMessage = null;
- Control controlInError = validate(null);
- if (controlInError != null)
- controlInError.setFocus();
- else
- {
- SampleCustomer newCust = inpCust;
- if (newCust == null)
- newCust = new SampleCustomer();
- newCust.setName(namePrompt.getText().trim());
- newCust.setYear(yearPrompt.getText().trim());
- newCust.setMonth(monthPrompt.getText().trim());
- newCust.setDay(dayPrompt.getText().trim());
- setOutputObject(newCust);
-
- SystemMessage completionMsg = null;
- if (inpCust == null)
- completionMsg = SamplesPlugin.getPluginMessage("SPPD1010");
- else
- completionMsg = SamplesPlugin.getPluginMessage("SPPD1011");
- completionMsg.makeSubstitution(newCust.getName());
- SystemMessageDialog msgDlg = new SystemMessageDialog(getShell(), completionMsg);
- msgDlg.open();
- }
- return isPageComplete();
- }
-
- // ---------------------
- // Validation methods...
- // ---------------------
- /**
- * Do full validation of all entry fields, optionally skipping a given one.
- * @return first control that is found to contain errors. Can be used to set focus.
- */
- protected Control validate(Control controlToSkip)
- {
- Control controlInError = null;
-
- if ((controlToSkip != namePrompt.getCombo()) && !validateName())
- controlInError = namePrompt.getCombo();
- if ((controlInError==null) && (controlToSkip != yearPrompt) && !validateYear())
- controlInError = yearPrompt;
- if ((controlInError==null) && (controlToSkip != monthPrompt) && !validateMonth())
- controlInError = monthPrompt;
- if ((controlInError==null) && (controlToSkip != dayPrompt) && !validateDay())
- controlInError = dayPrompt;
-
- return controlInError;
- }
- /**
- * Validate the customer name prompt. We only ensure it is not-empty.
- */
- protected boolean validateName()
- {
- String input = namePrompt.getText().trim();
- setErrorMessageAndPageCompletionStatus(nameValidator.validate(input));
- return (errorMessage==null);
- }
- /**
- * Validate the customer birth year prompt.
- */
- protected boolean validateYear()
- {
- String input = yearPrompt.getText().trim();
- setErrorMessageAndPageCompletionStatus(yearValidator.validate(input));
- return (errorMessage==null);
- }
- /**
- * Validate the customer birth month prompt.
- */
- protected boolean validateMonth()
- {
- String input = monthPrompt.getText().trim();
- setErrorMessageAndPageCompletionStatus(monthValidator.validate(input));
- return (errorMessage==null);
- }
- /**
- * Validate the customer birth day prompt.
- */
- protected boolean validateDay()
- {
- String input = dayPrompt.getText().trim();
- setErrorMessageAndPageCompletionStatus(dayValidator.validate(input));
- return (errorMessage==null);
- }
-
- /**
- * A convenience method that issues or clears the error message on the message line,
- * and sets the page completion status
- */
- protected void setErrorMessageAndPageCompletionStatus(SystemMessage errorMessage)
- {
- this.errorMessage = errorMessage;
- if (errorMessage == null)
- clearErrorMessage();
- else
- setErrorMessage(errorMessage);
- setPageComplete(isPageComplete());
- }
- /**
- * Return true if the OK button can be enabled.
- */
- protected boolean isPageComplete()
- {
- return ((errorMessage == null) &&
- (namePrompt.getText().trim().length()>0) &&
- (yearPrompt.getText().trim().length()>0) &&
- (monthPrompt.getText().trim().length()>0) &&
- (dayPrompt.getText().trim().length()>0));
- }
-}
-
-This is an example of a sample dialog written on top of the RSE base dialog class, and with +typical full error checking. +
+
+package org.eclipse.rse.samples.ui.frameworks.dialogs;
+
+import org.eclipse.swt.widgets.*;
+import org.eclipse.swt.events.*;
+
+import org.eclipse.rse.samples.*;
+
+import org.eclipse.rse.ui.dialogs.SystemPromptDialog;
+import org.eclipse.rse.ui.*;
+import org.eclipse.rse.ui.widgets.*;
+import org.eclipse.rse.ui.messages.*;
+import org.eclipse.rse.ui.validators.*;
+
+/**
+ * A simple example of using the SystemPromptDialog class as the basis for a new dialog.
+ */
+public class SampleDialog extends SystemPromptDialog
+{
+ // gui widgets
+ private SystemHistoryCombo namePrompt;
+ private Text yearPrompt, monthPrompt, dayPrompt;
+ // input
+ private SampleCustomer inpCust;
+ // validators
+ private ISystemValidator nameValidator, yearValidator, monthValidator, dayValidator;
+ // message
+ private SystemMessage errorMessage;
+
+ /**
+ * Constructor for SampleDialog.
+ */
+ public SampleDialog(Shell shell)
+ {
+ super(shell, SamplesPlugin.getString("org.eclipse.rse.samples.ui.dialogs.dialog1.title"));
+ setHelp(SamplesPlugin.HELPPREFIX + "dlg11000");
+ nameValidator = new SampleNameValidator();
+ yearValidator = new SampleBirthYearValidator();
+ monthValidator = new SampleBirthMonthValidator();
+ dayValidator = new SampleBirthDayValidator();
+ }
+
+ /**
+ * Required parent override.
+ * This is where we populate the client area
+ */
+ protected Control createInner(Composite parent)
+ {
+ int nbrColumns = 2;
+ Composite parentComposite = SystemWidgetHelpers.createComposite(parent, nbrColumns);
+
+ // add gui widgets...
+ SystemWidgetHelpers.createLabel(parentComposite, SamplesPlugin.getResourceBundle(), "org.eclipse.rse.samples.ui.dialogs.dialog1.name.");
+ boolean readonly = false;
+ namePrompt = SystemWidgetHelpers.createHistoryCombo(parentComposite, null, "name.history.key", readonly,
+ SamplesPlugin.getResourceBundle(), "org.eclipse.rse.samples.ui.dialogs.dialog1.name.tooltip");
+
+ addSeparatorLine(parentComposite, nbrColumns);
+ boolean wantBorder = false;
+ SystemWidgetHelpers.createLabel(parentComposite, SamplesPlugin.getResourceBundle(),
+ "org.eclipse.rse.samples.ui.dialogs.dialog1.birthday.verbage.", nbrColumns, wantBorder);
+
+ yearPrompt = SystemWidgetHelpers.createLabeledTextField(parentComposite, null,
+ SamplesPlugin.getResourceBundle(), "org.eclipse.rse.samples.ui.dialogs.dialog1.birthday.year.");
+ monthPrompt = SystemWidgetHelpers.createLabeledTextField(parentComposite, null,
+ SamplesPlugin.getResourceBundle(), "org.eclipse.rse.samples.ui.dialogs.dialog1.birthday.month.");
+ dayPrompt = SystemWidgetHelpers.createLabeledTextField(parentComposite, null,
+ SamplesPlugin.getResourceBundle(), "org.eclipse.rse.samples.ui.dialogs.dialog1.birthday.day.");
+
+ // if given an existing object, prefill it...
+ inpCust = (SampleCustomer)getInputObject();
+ if (inpCust != null)
+ {
+ namePrompt.setText(inpCust.getName());
+ yearPrompt.setText(inpCust.getYear());
+ monthPrompt.setText(inpCust.getMonth());
+ dayPrompt.setText(inpCust.getDay());
+ }
+
+
+ // add modify listeners...
+ namePrompt.addModifyListener( new ModifyListener()
+ {
+ public void modifyText(ModifyEvent event)
+ {
+ if (validateName())
+ validate(namePrompt.getCombo());
+ }
+ } );
+ yearPrompt.addModifyListener( new ModifyListener()
+ {
+ public void modifyText(ModifyEvent event)
+ {
+ if (validateYear())
+ validate(yearPrompt);
+ }
+ } );
+ monthPrompt.addModifyListener( new ModifyListener()
+ {
+ public void modifyText(ModifyEvent event)
+ {
+ if (validateMonth())
+ validate(monthPrompt);
+ }
+ } );
+ dayPrompt.addModifyListener( new ModifyListener()
+ {
+ public void modifyText(ModifyEvent event)
+ {
+ if (validateDay())
+ validate(monthPrompt);
+ }
+ } );
+
+ // initialize enabled state...
+ setPageComplete(isPageComplete());
+
+ return parentComposite;
+ }
+
+ /**
+ * Required parent override.
+ * This is where we return the first input control, to give it focus when the dialog appears.
+ */
+ protected Control getInitialFocusControl()
+ {
+ return namePrompt.getCombo();
+ }
+
+ /**
+ * Typical parent override.
+ * This is where we get control when the user presses OK.
+ */
+ protected boolean processOK()
+ {
+ errorMessage = null;
+ Control controlInError = validate(null);
+ if (controlInError != null)
+ controlInError.setFocus();
+ else
+ {
+ SampleCustomer newCust = inpCust;
+ if (newCust == null)
+ newCust = new SampleCustomer();
+ newCust.setName(namePrompt.getText().trim());
+ newCust.setYear(yearPrompt.getText().trim());
+ newCust.setMonth(monthPrompt.getText().trim());
+ newCust.setDay(dayPrompt.getText().trim());
+ setOutputObject(newCust);
+
+ SystemMessage completionMsg = null;
+ if (inpCust == null)
+ completionMsg = SamplesPlugin.getPluginMessage("SPPD1010");
+ else
+ completionMsg = SamplesPlugin.getPluginMessage("SPPD1011");
+ completionMsg.makeSubstitution(newCust.getName());
+ SystemMessageDialog msgDlg = new SystemMessageDialog(getShell(), completionMsg);
+ msgDlg.open();
+ }
+ return isPageComplete();
+ }
+
+ // ---------------------
+ // Validation methods...
+ // ---------------------
+ /**
+ * Do full validation of all entry fields, optionally skipping a given one.
+ * @return first control that is found to contain errors. Can be used to set focus.
+ */
+ protected Control validate(Control controlToSkip)
+ {
+ Control controlInError = null;
+
+ if ((controlToSkip != namePrompt.getCombo()) && !validateName())
+ controlInError = namePrompt.getCombo();
+ if ((controlInError==null) && (controlToSkip != yearPrompt) && !validateYear())
+ controlInError = yearPrompt;
+ if ((controlInError==null) && (controlToSkip != monthPrompt) && !validateMonth())
+ controlInError = monthPrompt;
+ if ((controlInError==null) && (controlToSkip != dayPrompt) && !validateDay())
+ controlInError = dayPrompt;
+
+ return controlInError;
+ }
+ /**
+ * Validate the customer name prompt. We only ensure it is not-empty.
+ */
+ protected boolean validateName()
+ {
+ String input = namePrompt.getText().trim();
+ setErrorMessageAndPageCompletionStatus(nameValidator.validate(input));
+ return (errorMessage==null);
+ }
+ /**
+ * Validate the customer birth year prompt.
+ */
+ protected boolean validateYear()
+ {
+ String input = yearPrompt.getText().trim();
+ setErrorMessageAndPageCompletionStatus(yearValidator.validate(input));
+ return (errorMessage==null);
+ }
+ /**
+ * Validate the customer birth month prompt.
+ */
+ protected boolean validateMonth()
+ {
+ String input = monthPrompt.getText().trim();
+ setErrorMessageAndPageCompletionStatus(monthValidator.validate(input));
+ return (errorMessage==null);
+ }
+ /**
+ * Validate the customer birth day prompt.
+ */
+ protected boolean validateDay()
+ {
+ String input = dayPrompt.getText().trim();
+ setErrorMessageAndPageCompletionStatus(dayValidator.validate(input));
+ return (errorMessage==null);
+ }
+
+ /**
+ * A convenience method that issues or clears the error message on the message line,
+ * and sets the page completion status
+ */
+ protected void setErrorMessageAndPageCompletionStatus(SystemMessage errorMessage)
+ {
+ this.errorMessage = errorMessage;
+ if (errorMessage == null)
+ clearErrorMessage();
+ else
+ setErrorMessage(errorMessage);
+ setPageComplete(isPageComplete());
+ }
+ /**
+ * Return true if the OK button can be enabled.
+ */
+ protected boolean isPageComplete()
+ {
+ return ((errorMessage == null) &&
+ (namePrompt.getText().trim().length()>0) &&
+ (yearPrompt.getText().trim().length()>0) &&
+ (monthPrompt.getText().trim().length()>0) &&
+ (dayPrompt.getText().trim().length()>0));
+ }
+}
+
+There are two ways the Remote System Explorer API set can help you when it comes to dialogs: -
Dialogs are secondary windows that prompt the user for information or display information to the user. They are typically -modal, meaning the rest of the application (in this case eclipse) is disabled while the dialog is showing. -Eclipse supplies a raw dialog class in SWT, as well as more robust dialog class in JFace. The RSE supplies its own -class, -SystemPromptDialog -in package -com.ibm.etools.systems.core.ui.dialogs -, that extends -the JFace dialog class and adds to it the following capabilities inherited by all classes which extend it: -
-To create your own dialog:
-One of the more difficult efforts in building a dialog with multiple entry fields, is the code to do the validation of those entry fields. A common strategy is to add modify listeners to the entry fields, and for each one validate the data as it typed. If the validation fails, a message is issued. If the validation succeeds, then the other fields on the dialog are validated. At the end of the validation, the OK button is enabled or disabled depending on the error message status, and whether the required information has been supplied. The RSE can help with this effort, somewhat, through the use of re-usable validators for various types of input.
-
-Follow this link for an example of a fully-formed dialog class written on top of this RSE base class, complete with
-error checking.
Typically, after creating your dialog, you will create an action to invoke it. The RSE can help with this too, via the -supplied SystemBaseDialogAction base class. - -
You may find some of the dialogs supplied by the RSE to be immediately re-usable in your own code, saving some -development and test effort. All these dialogs are in package com.ibm.etools.systems.core.ui.dialogs: -
- - -| Class | -Description | -Sample | -Action | -
|---|---|---|---|
| SystemRenameDialog | -Rename multiple items. Provides a table listing the old names and new names, which are editable. If your input objects - do not adapt to ISystemViewElementAdapter - or ISystemRemoteElementAdapter, - you should call setNameValidator to specify a validator that ensures the new name is correct, and your - input objects should also either be IResource objects or implement - ISystemTypedObject. - | -Sample image | -SystemCommonRenameAction | -
| SystemRenameSingleDialog | -Rename a single item. Provides a simple entry field for the new name. If your input object - does not adapt to ISystemViewElementAdapter or - ISystemRemoteElementAdapter, - you should call setNameValidator to specify a validator that ensures the new name is correct, and your - input object should also either be an IResource object or implement ISystemTypedObject. - | -Sample image | -SystemCommonRenameAction | -
| SystemDeleteDialog | -Confirm delete of one or more items. Provides a table listing the names of input objects. If your input objects - do not adapt to ISystemViewElementAdapter or - ISystemRemoteElementAdapter, - your input objects should either be IResource objects or implement ISystemTypedObject. - | -Sample image | -SystemCommonDeleteAction | -
| SystemSelectFileTypesDialog | -Presents a dialog listing all the file types defined in the eclipse File Associations preferences page, and - allows the user to select one or more of these types, or enter additional types not defined in eclipse. | -Sample image | -SystemSelectFileTypesAction | -
| SystemSimpleSelectDialog | -Eclipse has a CheckboxTreeViewer that is designed to allow the user to select multiple items from a hierarchical model. - This is a nice viewer, but very difficult to program to, as you have to handle reflecting the state of the selected children - for each parent node yourself. This dialog makes that trivial. The trick is to create wrappers of your model objects using - SystemSimpleContentElement, maintaining the parent/child hierarchy, and pass the root element to the dialog. The rest is - done for you, and the result is the selected state set for those elements selected by the user. Note this can also be used - as a simple flat list checkbox selection dialog, just by passing a non-visible root with a flat list of children. | -Sample image | -None | -
While the dialogs can be instantiated directly, it is perhaps best to use them by instantiating their action class, and calling the run method on it.
-The action classes are all in com.ibm.etools.systems.core.ui.actions package.
-
In addition to these universal dialogs, there are dialogs specific to the Files subsystem supplied by IBM. These enable selection -of remote files or folders. They can be found in the -com.ibm.etools.systems.files.ui.dialogs package. -
-| Class | -Description | -Sample | -Action | -
|---|---|---|---|
| SystemSelectRemoteFileOrFolderDialog | -Allows users to select a remote file, or folder (configurable) using a dialog similar to what is used in Eclipse for local file or - folder selection. Can be configured to allow user to select from any existing connection, or to be scoped to a particular connection, - or even a particular folder in a particular connection. - | -Sample image | -SystemSelectRemoteFileAction or - SystemSelectRemoteFolderAction | -
There are two ways the Remote System Explorer API set can help you when it comes to dialogs: +
Dialogs are secondary windows that prompt the user for information or display information to the user. They are typically +modal, meaning the rest of the application (in this case eclipse) is disabled while the dialog is showing. +Eclipse supplies a raw dialog class in SWT, as well as more robust dialog class in JFace. The RSE supplies its own +class, +SystemPromptDialog +in package +org.eclipse.rse.ui.dialogs +, that extends +the JFace dialog class and adds to it the following capabilities inherited by all classes which extend it: +
+To create your own dialog:
+One of the more difficult efforts in building a dialog with multiple entry fields, is the code to do the validation of those entry fields. A common strategy is to add modify listeners to the entry fields, and for each one validate the data as it typed. If the validation fails, a message is issued. If the validation succeeds, then the other fields on the dialog are validated. At the end of the validation, the OK button is enabled or disabled depending on the error message status, and whether the required information has been supplied. The RSE can help with this effort, somewhat, through the use of re-usable validators for various types of input.
+
+Follow this link for an example of a fully-formed dialog class written on top of this RSE base class, complete with
+error checking.
Typically, after creating your dialog, you will create an action to invoke it. The RSE can help with this too, via the +supplied SystemBaseDialogAction base class. + +
You may find some of the dialogs supplied by the RSE to be immediately re-usable in your own code, saving some +development and test effort. All these dialogs are in package org.eclipse.rse.ui.dialogs: +
+ + +| Class | +Description | +Sample | +Action | +
|---|---|---|---|
| SystemRenameDialog | +Rename multiple items. Provides a table listing the old names and new names, which are editable. If your input objects + do not adapt to ISystemViewElementAdapter + or ISystemRemoteElementAdapter, + you should call setNameValidator to specify a validator that ensures the new name is correct, and your + input objects should also either be IResource objects or implement + ISystemTypedObject. + | +Sample image | +SystemCommonRenameAction | +
| SystemRenameSingleDialog | +Rename a single item. Provides a simple entry field for the new name. If your input object + does not adapt to ISystemViewElementAdapter or + ISystemRemoteElementAdapter, + you should call setNameValidator to specify a validator that ensures the new name is correct, and your + input object should also either be an IResource object or implement ISystemTypedObject. + | +Sample image | +SystemCommonRenameAction | +
| SystemDeleteDialog | +Confirm delete of one or more items. Provides a table listing the names of input objects. If your input objects + do not adapt to ISystemViewElementAdapter or + ISystemRemoteElementAdapter, + your input objects should either be IResource objects or implement ISystemTypedObject. + | +Sample image | +SystemCommonDeleteAction | +
| SystemSelectFileTypesDialog | +Presents a dialog listing all the file types defined in the eclipse File Associations preferences page, and + allows the user to select one or more of these types, or enter additional types not defined in eclipse. | +Sample image | +SystemSelectFileTypesAction | +
| SystemSimpleSelectDialog | +Eclipse has a CheckboxTreeViewer that is designed to allow the user to select multiple items from a hierarchical model. + This is a nice viewer, but very difficult to program to, as you have to handle reflecting the state of the selected children + for each parent node yourself. This dialog makes that trivial. The trick is to create wrappers of your model objects using + SystemSimpleContentElement, maintaining the parent/child hierarchy, and pass the root element to the dialog. The rest is + done for you, and the result is the selected state set for those elements selected by the user. Note this can also be used + as a simple flat list checkbox selection dialog, just by passing a non-visible root with a flat list of children. | +Sample image | +None | +
While the dialogs can be instantiated directly, it is perhaps best to use them by instantiating their action class, and calling the run method on it.
+The action classes are all in org.eclipse.rse.ui.actions package.
+
In addition to these universal dialogs, there are dialogs specific to the Files subsystem supplied by IBM. These enable selection +of remote files or folders. They can be found in the +org.eclipse.rse.files.ui.dialogs package. +
+| Class | +Description | +Sample | +Action | +
|---|---|---|---|
| SystemSelectRemoteFileOrFolderDialog | +Allows users to select a remote file, or folder (configurable) using a dialog similar to what is used in Eclipse for local file or + folder selection. Can be configured to allow user to select from any existing connection, or to be scoped to a particular connection, + or even a particular folder in a particular connection. + | +Sample image | +SystemSelectRemoteFileAction or + SystemSelectRemoteFolderAction | +
To use the RSE logging framework, you must first decide if you want your own log file, -or want to use the common RSE log file. -
- --The log file support is encapsulated in a separate plugin, com.ibm.etools.systems.logging, which -defines the primary com.ibm.etools.systems.logging.Logger class that manages the log file. -This log file support offers the ability to log the following types of log messages:
-To define your own logging file, in your plugin class:
-protected static Logger log = null;
-if (log == null) log = LoggerFactory.getInst(this);
-
- public static void logInfo(String message)
- {
- log.logInfo(message);
- }
- public static void logWarning(String message)
- {
- log.logWarning(message);
- }
- public static void logError(String message)
- {
- log.logError(message, null);
- }
- public static void logError(String message, Throwable exception)
- {
- log.logError(message, exception);
- }
- public static void logDebugMessage(String prefix, String message)
- {
- if (Logger.DEBUG)
- {
- log.logDebugMessage(prefix, message);
- }
- }
-
-
- LoggerFactory.freeInst(this);
-
-Typically your code will write a healthy number of messages to the log file, to help you determine -what went wrong in an error situation in production. However, since this can result in a large number of -messages in the log file, it is recommended that you offer the user's a preference page in which they -can specify the types of messages to record in the log file, which should default to error messages only. -In the event of a problem, they can then turn on a more verbose logging option and re-produce the problem, -sending the log file to you for additional information. For example, for the Remote System Explorer, this -preference page is supplied:
-
To log your messages to the common RSE log file in .metadata\plugins\com.ibm.etools.systems.core, -either base your plugin class on the com.ibm.etools.systems.core.SystemBasePlugin class and use -the inherited logging methods, or instead of instantiating your own Logging object, re-use the -RSE-supplied logging object by calling getDefault().getLog() in the com.ibm.etools.systems.core.SystemBasePlugin -class. -
- - -To use the RSE logging framework, you must first decide if you want your own log file, +or want to use the common RSE log file. +
+ ++The log file support is encapsulated in a separate plugin, org.eclipse.rse.logging, which +defines the primary org.eclipse.rse.logging.Logger class that manages the log file. +This log file support offers the ability to log the following types of log messages:
+To define your own logging file, in your plugin class:
+protected static Logger log = null;
+if (log == null) log = LoggerFactory.getInst(this);
+
+ public static void logInfo(String message)
+ {
+ log.logInfo(message);
+ }
+ public static void logWarning(String message)
+ {
+ log.logWarning(message);
+ }
+ public static void logError(String message)
+ {
+ log.logError(message, null);
+ }
+ public static void logError(String message, Throwable exception)
+ {
+ log.logError(message, exception);
+ }
+ public static void logDebugMessage(String prefix, String message)
+ {
+ if (Logger.DEBUG)
+ {
+ log.logDebugMessage(prefix, message);
+ }
+ }
+
+
+ LoggerFactory.freeInst(this);
+
+Typically your code will write a healthy number of messages to the log file, to help you determine +what went wrong in an error situation in production. However, since this can result in a large number of +messages in the log file, it is recommended that you offer the user's a preference page in which they +can specify the types of messages to record in the log file, which should default to error messages only. +In the event of a problem, they can then turn on a more verbose logging option and re-produce the problem, +sending the log file to you for additional information. For example, for the Remote System Explorer, this +preference page is supplied:
+
To log your messages to the common RSE log file in .metadata\plugins\org.eclipse.rse.core, +either base your plugin class on the org.eclipse.rse.core.SystemBasePlugin class and use +the inherited logging methods, or instead of instantiating your own Logging object, re-use the +RSE-supplied logging object by calling getDefault().getLog() in the org.eclipse.core.SystemBasePlugin +class. +
+ + +In addition to validating what a user types, we often need -to transform it prior to saving. For example, we may need to fold it to uppercase or lowercase. The RSE abstracts -and encapsulates this concept into massagers which can be re-used. A few are pre-supplied by RSE. -
- -The ISystemMassager interface is in package -com.ibm.etools.systems.core.ui. -It is a very simple interface with one method: -public String massage(String text). -Given input text, return the massaged text. While simple, by encapsulating this operation into an interface, -you will be able to write re-usable dialogs that take a massager as input. Further, tricky massaging can be -built as a re-usable object. -
- -The RSE supplies the following massagers in package com.ibm.etools.systems.core.ui: -
-| Massager Class | -Description | -
|---|---|
| MassagerFoldCase | -Simply folds the text to uppercase or lowercase | -
| MassagerFoldCaseOutsideQuotes | -Folds the text to uppercase or lowercase, except parts of the text that are surrounded by quotes or any given delimiter characters | -
| MassagerFoldCaseUnlessQuoted | -Folds the text to uppercase or lowercase, unless the whole text is surrounded by quotes or any given delimiter character | -
In addition to validating what a user types, we often need +to transform it prior to saving. For example, we may need to fold it to uppercase or lowercase. The RSE abstracts +and encapsulates this concept into massagers which can be re-used. A few are pre-supplied by RSE. +
+ +The ISystemMassager interface is in package +org.eclipse.rse.ui. +It is a very simple interface with one method: +public String massage(String text). +Given input text, return the massaged text. While simple, by encapsulating this operation into an interface, +you will be able to write re-usable dialogs that take a massager as input. Further, tricky massaging can be +built as a re-usable object. +
+ +The RSE supplies the following massagers in package org.eclipse.rse.ui: +
+| Massager Class | +Description | +
|---|---|
| MassagerFoldCase | +Simply folds the text to uppercase or lowercase | +
| MassagerFoldCaseOutsideQuotes | +Folds the text to uppercase or lowercase, except parts of the text that are surrounded by quotes or any given delimiter characters | +
| MassagerFoldCaseUnlessQuoted | +Folds the text to uppercase or lowercase, unless the whole text is surrounded by quotes or any given delimiter character | +
This is an example of a simple message file, say in sampleMessages.xml, which has defined messages for only a single component. -
- -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE MessageFile SYSTEM "../com.ibm.etools.systems.core/messageFile.dtd"> -<!-- This is an exammple of a message file used by SystemMessage and SystemMessageDialog --> -<MessageFile Version="1.0"> - <Component Name="Samples Plugin" Abbr="SPP"> - <Subcomponent Name="Dialogs" Abbr="D"> - <!-- Component 'D' for dialog sample messages --> - <MessageList> - <Message ID="1000" Indicator="E"> - <LevelOne>You must enter a name</LevelOne> - <LevelTwo>You have left the customer name empty. Specify a name.</LevelTwo> - </Message> - <Message ID="1001" Indicator="E"> - <LevelOne>You must enter a birth year</LevelOne> - <LevelTwo>You have left the birth year empty. Specify a year.</LevelTwo> - </Message> - <Message ID="1002" Indicator="E"> - <LevelOne>%1 is not a valid year</LevelOne> - <LevelTwo>The birth year specified is not within the valid range of %2 to %3.</LevelTwo> - </Message> - <Message ID="1003" Indicator="E"> - <LevelOne>Year %1 is out of range</LevelOne> - <LevelTwo>The value you specified for the birth year is not a valid number.</LevelTwo> - </Message> - <Message ID="1004" Indicator="E"> - <LevelOne>You must enter a birth month</LevelOne> - <LevelTwo>You have left the birth month empty. Specify a month.</LevelTwo> - </Message> - <Message ID="1005" Indicator="E"> - <LevelOne>%1 is not a valid month</LevelOne> - <LevelTwo>The value you specified for the birth month is not a valid number.</LevelTwo> - </Message> - <Message ID="1006" Indicator="E"> - <LevelOne>Month %1 is out of range</LevelOne> - <LevelTwo>The birth month specified is not within the valid range of %2 to %3.</LevelTwo> - </Message> - <Message ID="1007" Indicator="E"> - <LevelOne>You must enter a birth day</LevelOne> - <LevelTwo>You have left the birth day empty. Specify a day.</LevelTwo> - </Message> - <Message ID="1008" Indicator="E"> - <LevelOne>%1 is not a valid day</LevelOne> - <LevelTwo>The value you specified for the birth day is not a valid number.</LevelTwo> - </Message> - <Message ID="1009" Indicator="E"> - <LevelOne>Day %1 is out of range</LevelOne> - <LevelTwo>The birth day specified is not within the valid range of %2 to %3.</LevelTwo> - </Message> - <Message ID="1010" Indicator="I"> - <LevelOne>Customer %1 created successfully. Re-run to see update mode.</LevelOne> - <LevelTwo>The customer was created. Re-running the same sample action will show the dialog in update mode.</LevelTwo> - </Message> - <Message ID="1011" Indicator="I"> - <LevelOne>Customer %1 updated successfully.</LevelOne> - <LevelTwo>Congratulations!</LevelTwo> - </Message> - </MessageList> - </Subcomponent> - </Component> -</MessageFile> -- - -
This is an example of a simple message file, say in sampleMessages.xml, which has defined messages for only a single component. +
+ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE MessageFile SYSTEM "../org.eclipse.rse.ui/messageFile.dtd"> +<!-- This is an exammple of a message file used by SystemMessage and SystemMessageDialog --> +<MessageFile Version="1.0"> + <Component Name="Samples Plugin" Abbr="SPP"> + <Subcomponent Name="Dialogs" Abbr="D"> + <!-- Component 'D' for dialog sample messages --> + <MessageList> + <Message ID="1000" Indicator="E"> + <LevelOne>You must enter a name</LevelOne> + <LevelTwo>You have left the customer name empty. Specify a name.</LevelTwo> + </Message> + <Message ID="1001" Indicator="E"> + <LevelOne>You must enter a birth year</LevelOne> + <LevelTwo>You have left the birth year empty. Specify a year.</LevelTwo> + </Message> + <Message ID="1002" Indicator="E"> + <LevelOne>%1 is not a valid year</LevelOne> + <LevelTwo>The birth year specified is not within the valid range of %2 to %3.</LevelTwo> + </Message> + <Message ID="1003" Indicator="E"> + <LevelOne>Year %1 is out of range</LevelOne> + <LevelTwo>The value you specified for the birth year is not a valid number.</LevelTwo> + </Message> + <Message ID="1004" Indicator="E"> + <LevelOne>You must enter a birth month</LevelOne> + <LevelTwo>You have left the birth month empty. Specify a month.</LevelTwo> + </Message> + <Message ID="1005" Indicator="E"> + <LevelOne>%1 is not a valid month</LevelOne> + <LevelTwo>The value you specified for the birth month is not a valid number.</LevelTwo> + </Message> + <Message ID="1006" Indicator="E"> + <LevelOne>Month %1 is out of range</LevelOne> + <LevelTwo>The birth month specified is not within the valid range of %2 to %3.</LevelTwo> + </Message> + <Message ID="1007" Indicator="E"> + <LevelOne>You must enter a birth day</LevelOne> + <LevelTwo>You have left the birth day empty. Specify a day.</LevelTwo> + </Message> + <Message ID="1008" Indicator="E"> + <LevelOne>%1 is not a valid day</LevelOne> + <LevelTwo>The value you specified for the birth day is not a valid number.</LevelTwo> + </Message> + <Message ID="1009" Indicator="E"> + <LevelOne>Day %1 is out of range</LevelOne> + <LevelTwo>The birth day specified is not within the valid range of %2 to %3.</LevelTwo> + </Message> + <Message ID="1010" Indicator="I"> + <LevelOne>Customer %1 created successfully. Re-run to see update mode.</LevelOne> + <LevelTwo>The customer was created. Re-running the same sample action will show the dialog in update mode.</LevelTwo> + </Message> + <Message ID="1011" Indicator="I"> + <LevelOne>Customer %1 updated successfully.</LevelOne> + <LevelTwo>Congratulations!</LevelTwo> + </Message> + </MessageList> + </Subcomponent> + </Component> +</MessageFile> ++ + +
To work with messages, which are defined in an xml message file, -you use: -
-Once you have defined your message file, you must update your plugin class to load it at startup time.
-To do this, simply call the static method
-loadMessageFile
-in the RSE-supplied SystemBasePlugin class.
-
-
-After the message file is loaded into memory, you can extract messages from it by calling the static method
-getMessage
-from the same SystemBasePlugin class.
-
The following classes are all defined in the com.ibm.etools.systems.core.ui.messages package.
- -The loadMessageFile method in SystemBasePlugin, returns an instance of -SystemMessageFile, -representing the parsed message file. It is methods in this which return individual messages. -
To do message variable substitution, call the appropriate overload of the makeSubstitution method in -the message object, passing as many parameters as there are unique substitution variables in the message. -
-To get the first level message text, call getLevelOneText on the message object. To get -the second level help, call getLevelTwoText. -
- -To display a message in a dialog, instantiate SystemMessageDialog, passing -in a parent shell and the message object, and then call the appropriate open method in the dialog object. Here is what the message -dialog looks like, for a message of type Error (the type dictates the error icon): -
-
If you are extending the RSE class SystemPromptDialog for dialogs, -or AbstractSystemWizardPage for wizard pages -or SystemBasePropertyPage for property pages, you can display the message to the -user by calling the setErrorMessage method all these classes support. These classes all implement -the interface ISystemMessageLine, which also includes the method clearErrorMessage. For non-error -messages, use setMessage -and clearMessage.
--Here is what a system message issued in a SystemPromptDialog dialog looks like:
-
The user can select the question mark icon on the right to see the full message dialog, and hence access the second level help for the message. -
Here is what a system message issued in an AbstractSystemWizardPage looks like:
-
If the user clicks the mouse on the message or icon, they will see the full message dialog for the message.
- -Here is what a system message issued in a SystemBasePropertyPage looks like:
-
Again, if the user clicks the mouse on the message or icon, they will see the full message dialog for the message.
- -The following class is defined in the com.ibm.etools.systems.model package. - -
Many of the RSE APIs throw com.ibm.etools.systems.model.SystemMessageException, which -encapsulates a system message object. To get the encapsulated message, call getSystemMessage(). -To display the message in an RSE message dialog box, simply call displayMessage() on the exception object. -To get the first-level text, call getMessage(), or getSystemMessage().getLevelOneText() -
- -Declare the messages via the Message tag in a message file, such as sampleMessages.xml -
<?xml version="1.0" encoding='UTF-8'?> -<!DOCTYPE MessageFile SYSTEM "../com.ibm.etools.systems.core/messageFile.dtd"> -<!-- This is an exammple of a message file used by SystemMessage and SystemMessageDialog --> -<MessageFile Version="1.0"> - <Component Name="Samples Plugin" Abbr="SPP"> - <Subcomponent Name="Dialogs" Abbr="D"> - <!-- Component 'D' for dialog sample messages --> - <MessageList> - <Message ID="1003" Indicator="E"> - <LevelOne>%1 is not a valid year</LevelOne> - <LevelTwo>The birth year specified is not within the valid range of %2 to %3.</LevelTwo> - </Message> - <!-- repeat Message elements as needed --> - </MessageList> - </Subcomponent> - </Component> -</MessageFile> -- -
import com.ibm.etools.systems.core.ui.messages.*; // for message file classes -import com.ibm.etools.systems.core.*; // for SystemBasePlugin -... -private static SystemMessageFile messageFile = null; -... -messageFile = SystemBasePlugin.loadMessageFile(descriptor, "sampleMessages.xml"); // in constructor -... - -/** - * Retrieve a message from this plugin's message file - * @param msgId - the ID of the message to retrieve. This is the concatenation of the - * message's component abbreviation, subcomponent abbreviation, and message ID as declared - * in the message xml file. - */ -public static SystemMessage getPluginMessage(String msgId) -{ - return SystemBasePlugin.getMessage(messageFile, msgId); -}- -
SystemMessage errorMessage = SamplesPlugin.getPluginMessage("SPPD1003");
-errorMessage.makeSubstitution(input, "1900", "2003");
-
-setErrorMessage(errorMessage);- -
SystemMessageDialog msgDlg = new SystemMessageDialog(shell, errorMessage);msgDlg.open(); // to open with details not showing -//msgDlg.openWithDetails(); // to open with details already showing- -
-
To work with messages, which are defined in an xml message file, +you use: +
+Once you have defined your message file, you must update your plugin class to load it at startup time.
+To do this, simply call the static method
+loadMessageFile
+in the RSE-supplied SystemBasePlugin class.
+
+
+After the message file is loaded into memory, you can extract messages from it by calling the static method
+getMessage
+from the same SystemBasePlugin class.
+
The following classes are all defined in the org.eclipse.rse.ui.messages package.
+ +The loadMessageFile method in SystemBasePlugin, returns an instance of +SystemMessageFile, +representing the parsed message file. It is methods in this which return individual messages. +
To do message variable substitution, call the appropriate overload of the makeSubstitution method in +the message object, passing as many parameters as there are unique substitution variables in the message. +
+To get the first level message text, call getLevelOneText on the message object. To get +the second level help, call getLevelTwoText. +
+ +To display a message in a dialog, instantiate SystemMessageDialog, passing +in a parent shell and the message object, and then call the appropriate open method in the dialog object. Here is what the message +dialog looks like, for a message of type Error (the type dictates the error icon): +
+
If you are extending the RSE class SystemPromptDialog for dialogs, +or AbstractSystemWizardPage for wizard pages +or SystemBasePropertyPage for property pages, you can display the message to the +user by calling the setErrorMessage method all these classes support. These classes all implement +the interface ISystemMessageLine, which also includes the method clearErrorMessage. For non-error +messages, use setMessage +and clearMessage.
++Here is what a system message issued in a SystemPromptDialog dialog looks like:
+
The user can select the question mark icon on the right to see the full message dialog, and hence access the second level help for the message. +
Here is what a system message issued in an AbstractSystemWizardPage looks like:
+
If the user clicks the mouse on the message or icon, they will see the full message dialog for the message.
+ +Here is what a system message issued in a SystemBasePropertyPage looks like:
+
Again, if the user clicks the mouse on the message or icon, they will see the full message dialog for the message.
+ +The following class is defined in the org.eclipse.rse.services.clientserver.messages package. + +
Many of the RSE APIs throw org.eclipse.rse.services.clientserver.messages.SystemMessageException, which +encapsulates a system message object. To get the encapsulated message, call getSystemMessage(). +To display the message in an RSE message dialog box, simply call displayMessage() on the exception object. +To get the first-level text, call getMessage(), or getSystemMessage().getLevelOneText() +
+ +Declare the messages via the Message tag in a message file, such as sampleMessages.xml +
<?xml version="1.0" encoding='UTF-8'?> +<!DOCTYPE MessageFile SYSTEM "../org.eclipse.rse.ui/messageFile.dtd"> +<!-- This is an exammple of a message file used by SystemMessage and SystemMessageDialog --> +<MessageFile Version="1.0"> + <Component Name="Samples Plugin" Abbr="SPP"> + <Subcomponent Name="Dialogs" Abbr="D"> + <!-- Component 'D' for dialog sample messages --> + <MessageList> + <Message ID="1003" Indicator="E"> + <LevelOne>%1 is not a valid year</LevelOne> + <LevelTwo>The birth year specified is not within the valid range of %2 to %3.</LevelTwo> + </Message> + <!-- repeat Message elements as needed --> + </MessageList> + </Subcomponent> + </Component> +</MessageFile> ++ +
import org.eclipse.rse.ui.messages.*; // for message file classes +import org.eclipse.rse.core.*; // for SystemBasePlugin +... +private static SystemMessageFile messageFile = null; +... +messageFile = SystemBasePlugin.loadMessageFile(descriptor, "sampleMessages.xml"); // in constructor +... + +/** + * Retrieve a message from this plugin's message file + * @param msgId - the ID of the message to retrieve. This is the concatenation of the + * message's component abbreviation, subcomponent abbreviation, and message ID as declared + * in the message xml file. + */ +public static SystemMessage getPluginMessage(String msgId) +{ + return SystemBasePlugin.getMessage(messageFile, msgId); +}+ +
SystemMessage errorMessage = SamplesPlugin.getPluginMessage("SPPD1003");
+errorMessage.makeSubstitution(input, "1900", "2003");
+
+setErrorMessage(errorMessage);+ +
SystemMessageDialog msgDlg = new SystemMessageDialog(shell, errorMessage);msgDlg.open(); // to open with details not showing +//msgDlg.openWithDetails(); // to open with details already showing+ +
+
The front door to accessing the elements of the RSE model is the -SystemRegistry, which is a -singleton object accessible via SystemPlugin.getTheSystemRegistry(). -
-The system registry will get you access to profiles, connections and subsystem factories. -From a subsystem factory you can access subsystems, filter pools, -user actions and compile commands. -From subsystems you can access remote resources, as well -as filter pools referenced by the subsystem. -
- - + + + + + + + +The front door to accessing the elements of the RSE model is the +SystemRegistry, which is a +singleton object accessible via SystemStartHere.getSystemRegistry(). +
+The system registry will get you access to profiles, connections and subsystem factories. +From a subsystem configuration you can access subsystems, filter pools, +user actions and compile commands. +From ISubSystem you can access remote resources, as well +as filter pools referenced by the subsystem. +
+ + diff --git a/rse/doc/org.eclipse.rse.doc.isv/guide/api/plugin/uiPluginAPI.html b/rse/doc/org.eclipse.rse.doc.isv/guide/api/plugin/uiPluginAPI.html index 235ebc5f783..8b90c60b337 100755 --- a/rse/doc/org.eclipse.rse.doc.isv/guide/api/plugin/uiPluginAPI.html +++ b/rse/doc/org.eclipse.rse.doc.isv/guide/api/plugin/uiPluginAPI.html @@ -1,80 +1,80 @@ - - - - - - - -You may find it of value to base your own plugin class on the RSE-supplied base plugin class. -If so, there are some methods you are encouraged to create or override in your class. The benefits -of using this as your base class is the inherited methods you can access. -
-To use the RSE base plugin class -com.ibm.etools.systems.core.SystemBasePlugin, -you subclass it for your own plugin class, and supply some key static methods of your own: -
-You may also override some RSE-supplied instance methods: -
Of course, there are the usual eclipse-supplied instance methods to override too: -
The methods you get access to by using the RSE-supplied base plugin class include:
-You may find it of value to base your own plugin class on the RSE-supplied base plugin class. +If so, there are some methods you are encouraged to create or override in your class. The benefits +of using this as your base class is the inherited methods you can access. +
+To use the RSE base plugin class +org.eclipse.rse.core.SystemBasePlugin, +you subclass it for your own plugin class, and supply some key static methods of your own: +
+You may also override some RSE-supplied instance methods: +
Of course, there are the usual eclipse-supplied instance methods to override too: +
The methods you get access to by using the RSE-supplied base plugin class include:
+All Remote System Explorer preference pages are rooted within the -preferences category com.ibm.etools.systems.core.ui.preferences.RemoteSystemsPreferencePage, -as shown here:
-
There is no RSE-supplied base class for preference pages, but we recommend -you extend FieldEditorPreferencePage in package org.eclipse.jface.preference. -This JFace class allows you to create a preferences page as a sequence of "field -editors" which know how to initialize, load and store their values from their preferences store. -
-We also suggest the following when designing your preference pages: -
Should you need to query, or update, any RSE preferences you can do so via -the getters and setters in com.ibm.etools.systems.core.SystemPreferencesManager. -
-The RSE supplies a few field editors, complementing what JFace supplies -in org.eclipse.jface.preference. The RSE-supplied field editors, and the -RSE-supplied preferences pages, are all found in package com.ibm.etools.systems.core.ui.propertypages: -
-
All Remote System Explorer preference pages are rooted within the +preferences category org.eclipse.rse.ui.preferences.RemoteSystemsPreferencePage, +as shown here:
+
There is no RSE-supplied base class for preference pages, but we recommend +you extend FieldEditorPreferencePage in package org.eclipse.jface.preference. +This JFace class allows you to create a preferences page as a sequence of "field +editors" which know how to initialize, load and store their values from their preferences store. +
+We also suggest the following when designing your preference pages: +
Should you need to query, or update, any RSE preferences you can do so via +the getters and setters in org.eclipse.rse.core.SystemPreferencesManager. +
+The RSE supplies a few field editors, complementing what JFace supplies +in org.eclipse.jface.preference. The RSE-supplied field editors, and the +RSE-supplied preferences pages, are all found in package org.eclipse.rse.ui.propertypages: +
+
You can supply your own property pages to any node in the Remote Systems tree or table views. -As you author your property page classes, you may find the RSE-supplied base class for property pages -of value. - -
The RSE supplies a base class for property pages, -com.ibm.etools.systems.core.ui.propertypages.SystemBasePropertyPage, -that extends the base eclipse property page org.eclipse.ui.dialogs.PropertyPage. The advantages -of using this RSE-supplied class are: -
-You can simply use the eclipse-supplied extension point org.eclipse.ui.propertyPages to -contribute property pages to any of the non-remote artifacts from the RSE model. To use this extension -point, you need to know the class or, preferably, interface that the objects implement, which we describe here: -
- -| RSE Resource | -Implements Interface | -
|---|---|
| Profile | -com.ibm.etools.systems.model.SystemProfile | -
| Connection | -com.ibm.etools.systems.model.SystemConnection | -
| Subsystem | -com.ibm.etools.systems.subsystems.SubSystem | -
| Filter pool reference | -com.ibm.etools.systems.filters.SystemFilterPoolReference | -
| Filter reference | -com.ibm.etools.systems.filters.SystemFilterReference | -
Remote resources have no underlying eclipse resource, and typically all are instances of the same class, -meaning insufficient fidelity in scoping property pages to a remote resource of a particular type. Because of this, -the RSE supplies its propertyPages extension point, for remote resources, which allows for -very explicit scoping of the property page to very specific types of remote resources. -
- - - -You can supply your own property pages to any node in the Remote Systems tree or table views. +As you author your property page classes, you may find the RSE-supplied base class for property pages +of value. + +
The RSE supplies a base class for property pages, +org.eclipse.rse.ui.propertypages.SystemBasePropertyPage, +that extends the base eclipse property page org.eclipse.ui.dialogs.PropertyPage. The advantages +of using this RSE-supplied class are: +
+You can simply use the eclipse-supplied extension point org.eclipse.ui.propertyPages to +contribute property pages to any of the non-remote artifacts from the RSE model. To use this extension +point, you need to know the class or, preferably, interface that the objects implement, which we describe here: +
+ +| RSE Resource | +Implements Interface | +
|---|---|
| Profile | +org.eclipse.rse.model.ISystemProfile | +
| Host | +org.eclipse.rse.model.IHost | +
| Subsystem | +org.eclipse.rse.core.subsystems.ISubSystem | +
| Filter pool reference | +org.eclipse.rse.filters.ISystemFilterPoolReference | +
| Filter reference | +org.eclipse.rse.filters.ISystemFilterReference | +
Remote resources have no underlying eclipse resource, and typically all are instances of the same class, +meaning insufficient fidelity in scoping property pages to a remote resource of a particular type. Because of this, +the RSE supplies its propertyPages extension point, for remote resources, which allows for +very explicit scoping of the property page to very specific types of remote resources. +
+ + + +IBM supplies subsystems for accessing the file system and for executing commands, for -all system types ("universally"). -
--To programmatically access the files in a remote system -identified by a particular system connection, use the -system registry to get to the -file subsystem -for that connection. This file subsystem offers methods for accessing the remote files. -
--Similarly, to programmatically run commands in a remote system -identified by a particular system connection, use the -system registry to get to the -command subsystem -for that connection. This command subsystem offers methods for running remote commands, -either in a new command shell or an existing command shell. You can also set environment variables -using this subsytem object. -
- - + + + + + + + +RSE supplies subsystems for accessing the file system and for executing commands, for +all system types ("universally"). +
++To programmatically access the files in a remote system +identified by a particular system connection, use the +system registry to get to the +file subsystem +for that connection, by passing in the file category as a String. This file subsystem offers methods for accessing the remote files. +
++Similarly, to programmatically run commands in a remote system +identified by a particular system connection, use the +system registry to get to the +command subsystem +for that connection, by passing in the command category as a String. This command subsystem offers methods for running remote commands, +either in a new command shell or an existing command shell. You can also set environment variables +using this subsytem object. +
+ + diff --git a/rse/doc/org.eclipse.rse.doc.isv/guide/api/uiAPI.html b/rse/doc/org.eclipse.rse.doc.isv/guide/api/uiAPI.html index 44590b632b4..58a28ca9443 100755 --- a/rse/doc/org.eclipse.rse.doc.isv/guide/api/uiAPI.html +++ b/rse/doc/org.eclipse.rse.doc.isv/guide/api/uiAPI.html @@ -1,125 +1,125 @@ - - - - - - - -The RSE provides a number of classes that can help with programming productivity when authoring -user interface artifacts, such as actions, dialogs, wizards, property pages and preferences pages. -Further, a common requirement in all of these artifacts is the need to display translated messages -to the user. The RSE supplies a framework for defining and displaying rich messages that have second -level help, severity and ID attributes. -
--In the following sections we introduce the support offered by the RSE for these UI constructs. -
The RSE supplies a base plugin class SystemBasePlugin that offers -some advantages over the base eclipse AbstractUIPlugin class: -
To use the base plugin class effectively, you must subclass it and supply some critical -methods of your own. -
- -The Remote System Explorer comes with special support for logging information to a log file, -for the purpose of problem determination for servicing your plugin. The log file support allows -you to either log your messages to the common RSE log file in the .metadata\plugins\com.ibm.etools.systems.core -folder, or to define your own log file in your plugin metadata folder, if desired. -
- -The Java property file for messages is not very rich, as it offers only the ability to define a -single message string. Throughout the RSE perspective you will notice that the messages are richer -than this. They contain second level help, severity, and ID and more. Further, there is a unique -error message dialog for displaying messages, with their second level help, and specialized support -in the RSE dialog, wizard and property page classes for displaying messages on a message line. These -messages can be selected by the user, to bring up the specialized message dialog displaying the -additional properties of the message. Further, there is support for logging severe errors to a log -file, enabling better service support. -
--Your own plugins can enjoy this rich message support too, even independently of using the rest of -the RSE for remote resource access. This support involves defining an xml -message file, which defines -the messages, and using a set of -supplied classes to work with the messages. -
-Before defining your own messages, you may wish to peruse the list of IBM-supplied messages already defined -by the RSE. The key benefit to using an existing message is translation, as these are already -translated into many languages. -
- -When defining your own preferences pages, -you may want to place your preference pages within the Remote Systems preference page category. -As you author your preference page classes, you may find some of the RSE-supplied classes for -preference pages to be useful. -
- -Property pages can appear in the Properties dialog of any object in eclipse. This dialog is available by selecting -"Properties" from the pop-up menu for the object. The RSE supports defining your own -property pages for the resources in its model, although there is a -distinction between local and remote resources. -
- -Validating user-entered text is a common and tedious task in any GUI programming. Using validators to encapsulate -the error checking for a particular type of data is a highly recommended practice. The -RSE validator support is very -helpful for this, offering both a common interface for all manner of validators and a large list of pre-supplied -validators. -
- -While validating user-entered text is common, so is affecting user-entered text prior to saving it. For example, folding it -to upper or lower case. The RSE massager support encapsulates this concept, and -supplies a few re-usable massagers for you. -
- -Populating preference pages, property pages, dialogs and wizards requires use of SWT widget programming. The RSE -widget support can help, with helper methods and classes, and re-usable widgets you may -find useful. -
- -The RSE supplies rich support for dialogs, including a powerful base class -and, re-usable pre-built dialogs. -
- -Wizards are a common building block of an eclipse GUI. Typically, a wizard is used to prompt for information to create -something new, while a dialog is used to prompt for information for other purposes. -The RSE wizard support includes base classes that can simplify the task of creating wizards. -
- -Populating popup and pulldown menu items requires the creation of actions. These actions typically popup dialogs or wizards, -and need to be able to pass selections and inputs from the action to the dialog or wizard, and get outputs back. The RSE -action support can significantly help with this programming task, especially when used -together with the RSE dialog and wizard support. -
- -Often we want to refresh the contents of the Remote Systems view or Table view from within our actions, to visualize -changes to the selected resources. To do this, use the -method. -To get the system registry, use the -method. - - - + + +
+ + + + +The RSE provides a number of classes that can help with programming productivity when authoring +user interface artifacts, such as actions, dialogs, wizards, property pages and preferences pages. +Further, a common requirement in all of these artifacts is the need to display translated messages +to the user. The RSE supplies a framework for defining and displaying rich messages that have second +level help, severity and ID attributes. +
++In the following sections we introduce the support offered by the RSE for these UI constructs. +
The RSE supplies a base plugin class SystemBasePlugin that offers +some advantages over the base eclipse AbstractUIPlugin class: +
To use the base plugin class effectively, you must subclass it and supply some critical +methods of your own. +
+ +The Remote System Explorer comes with special support for logging information to a log file, +for the purpose of problem determination for servicing your plugin. The log file support allows +you to either log your messages to the common RSE log file in the .metadata\plugins\org.eclipse.rse.core +folder, or to define your own log file in your plugin metadata folder, if desired. +
+ +The Java property file for messages is not very rich, as it offers only the ability to define a +single message string. Throughout the RSE perspective you will notice that the messages are richer +than this. They contain second level help, severity, and ID and more. Further, there is a unique +error message dialog for displaying messages, with their second level help, and specialized support +in the RSE dialog, wizard and property page classes for displaying messages on a message line. These +messages can be selected by the user, to bring up the specialized message dialog displaying the +additional properties of the message. Further, there is support for logging severe errors to a log +file, enabling better service support. +
++Your own plugins can enjoy this rich message support too, even independently of using the rest of +the RSE for remote resource access. This support involves defining an xml +message file, which defines +the messages, and using a set of +supplied classes to work with the messages. +
+Before defining your own messages, you may wish to peruse the list of RSE-supplied messages that are +already defined. The key benefit to using an existing message is translation, as these are already +translated into many languages. +
+ +When defining your own preferences pages, +you may want to place your preference pages within the Remote Systems preference page category. +As you author your preference page classes, you may find some of the RSE-supplied classes for +preference pages to be useful. +
+ +Property pages can appear in the Properties dialog of any object in eclipse. This dialog is available by selecting +"Properties" from the pop-up menu for the object. The RSE supports defining your own +property pages for the resources in its model, although there is a +distinction between local and remote resources. +
+ +Validating user-entered text is a common and tedious task in any GUI programming. Using validators to encapsulate +the error checking for a particular type of data is a highly recommended practice. The +RSE validator support is very +helpful for this, offering both a common interface for all manner of validators and a large list of pre-supplied +validators. +
+ +While validating user-entered text is common, so is affecting user-entered text prior to saving it. For example, folding it +to upper or lower case. The RSE massager support encapsulates this concept, and +supplies a few re-usable massagers for you. +
+ +Populating preference pages, property pages, dialogs and wizards requires use of SWT widget programming. The RSE +widget support can help, with helper methods and classes, and re-usable widgets you may +find useful. +
+ +The RSE supplies rich support for dialogs, including a powerful base class +and, re-usable pre-built dialogs. +
+ +Wizards are a common building block of an eclipse GUI. Typically, a wizard is used to prompt for information to create +something new, while a dialog is used to prompt for information for other purposes. +The RSE wizard support includes base classes that can simplify the task of creating wizards. +
+ +Populating popup and pulldown menu items requires the creation of actions. These actions typically popup dialogs or wizards, +and need to be able to pass selections and inputs from the action to the dialog or wizard, and get outputs back. The RSE +action support can significantly help with this programming task, especially when used +together with the RSE dialog and wizard support. +
+ +Often we want to refresh the contents of the Remote Systems view or Table view from within our actions, to visualize +changes to the selected resources. To do this, use the +method. +To get the system registry, use the +method. + + + diff --git a/rse/doc/org.eclipse.rse.doc.isv/guide/api/validators/uiValidatorsAPI.html b/rse/doc/org.eclipse.rse.doc.isv/guide/api/validators/uiValidatorsAPI.html index 623af3ee37a..95787fbcfa6 100755 --- a/rse/doc/org.eclipse.rse.doc.isv/guide/api/validators/uiValidatorsAPI.html +++ b/rse/doc/org.eclipse.rse.doc.isv/guide/api/validators/uiValidatorsAPI.html @@ -1,226 +1,226 @@ - - -
- - - - -Throughout an eclipse UI there are times when we need to validate what the user has typed in. Validators -offer a way to encapsulate the error checking for a particular domain, so it can be re-used whereever the user -is prompted for this. This includes dialogs, property pages, preference pages, wizard pages and viewer -cells. Eclipse's JFace offers two interfaces for this, one for viewer cells and one for the rest. In RSE, -there is a single interface combining the requirements of both, so you can author a single validator that is -re-usable anywhere. Further, the RSE validator interface and sub-interfaces force additional information to be -supplied to enhance re-use, such as the maximum length, which can be used to set the text limit for a text field. -
- -All RSE validator interfaces and classes are in package com.ibm.etools.systems.core.ui.validators. - -
The primary validator interface is ISystemValidator, which is extends org.eclipse.jface.dialogs.IInputValidator -and org.eclipse.jface.viewers.ICellEditorValidator. Both parent interfaces define an isValid method, -but the former takes a String while the latter takes an Object. They both return a String which is the error message if an -error was detected, or null if no error detected. The ISystemValidator interface adds the following additional methods: -
- -| Method | -Description | -
|---|---|
| public int getMaximumNameLength() | -Returns the maximum length allowed for this text. Can be used to set text limit of text widgets. | -
| public SystemMessage getSystemMessage() | -If isValid returns false, this returns a SystemMessage object that offers richer message support than just a string. - Return null if you don't support SystemMessages. - Callers don't need to use this if they use validate(String) instead of isValid(String). | -
| public SystemMessage validate(String text) | -An alternative to isValid if your validator does support SystemMessage objects versus simple strings for error messages. | -
Often our validation requires checking that the given text is unique, in some given list of existing things, like names say. To facilitate -this, there is an interface ISystemValidatorUniqueString, which extends ISystemValidator and adds some additional -methods required for uniqueness validation: -
- -| Method | -Description | -
|---|---|
| public void setCaseSensitive(boolean caseSensitive) | -Specifies whether the test for an existing string should consider case or not. | -
| public void setExistingNamesList(String[] existingList) | -Sets the existing list to test against, as an array. | -
| public void setExistingNamesList(Vector existingList) | -Sets the existing list to test against, as a vector of Strings. | -
| public String[] getExistingNamesList() | -Returns the existing list that is used to test against. | -
If you desire to create a unique string validator, you probably will start by subclassing ValidatorUniqueString. -
- -The third validator interface is IValidatorRemoteSelection, which is specifically intended to be used -in the remote resource selection dialogs supplied by the RSE. It allows you to decide when to enable the OK button, based on what -is selected. It contains only the following method:
-public SystemMessage isValid(SystemConnection selectedConnection, Object[] selectedObjects, ISystemRemoteElementAdapter[] remoteAdaptersForSelectedObject); -You typically won't implement this interface directly, but rather sublcass ValidatorRemoteSelection.
- -You may be able to avoid creating a new validator if you find that RSE has already supplied one you need. Or, you may find it -appropriate to simply subclass one of these RSE-supplied validators. All of them are designed to be either used as-is, or configured -via setter calls, or subclassed, whichever is most convenient.
-All of these validators support rich SystemMessage objects, versus just simple strings for the error message. When used with the -RSE dialog, property page or wizard page classes, you should call -validate(String) and call -setErrorMessage with the result. When used -in other places you should use isValid(String) as it returns just the first-level text of the system message.
-| Validator Class | -Description | -
|---|---|
| ValidatorCompileCommandLabel | -Validates the label for a compile command in the RSE. | -
| ValidatorConnectionName | -Validates the name of a connection in the RSE. | -
| ValidatorFileName | -Validates the name of a file in eclipse. | -
| ValidatorFilterName | -Validates the name of a filter in the RSE. | -
| ValidatorFilterPoolName | -Validates the name of a filter pool in the RSE. | -
| ValidatorFilterString | -Validates the contents of a filter string in the RSE. | -
| ValidatorFolderName | -Validates the name of a folder in eclipse. | -
| ValidatorIntegerInput | -Validates the given string is a valid integer. | -
| ValidatorIntegerRangeInput | -Validates the given string is a valid integer within a given range. | -
| ValidatorLongInput | -Validates the given string is a valid long integer. | -
| ValidatorLongRangeInput | -Validates the given string is a valid long integer within a given range. | -
| ValidatorPathName | -Validates the given string is a valid folder path in eclipse. | -
| ValidatorPortInput | -Validates the given string is a valid TCP/IP port number. | -
| ValidatorProfileName | -Validates the name of a system profile in the RSE. | -
| ValidatorRemoteSelection | -This is a very special case abstract base class, for validators that decide the enablement of the OK button - in the RSE-supplied remote resource selection dialogs. | -
| ValidatorSourceType | -A validator for source types, such as a file type or "*.java". It is intended to be subclassed. | -
| ValidatorSpecialChar | -A base class for validators that need to ensure the given string doesn't contain certain characters. | -
| ValidatorSystemName | -A name validator, to be used when the name being prompted for must follow Java identifier rules. | -
| ValidatorUniqueString | -A base class, or configurable class, to be used for any validation that requires the string to be unique within a given list. | -
| ValidatorUserActionCommand | -Validates the command of a user defined action in the RSE. | -
| ValidatorUserActionComment | -Validates the comment of a user defined action in the RSE. | -
| ValidatorUserActionName | -Validates the name of a user defined action in the RSE. | -
| ValidatorUserId | -Validates a user ID. Does only basic checking, intended to be subclassed. | -
| ValidatorUserTypeName | -Validates the name of a named type in the RSE. | -
| ValidatorUserTypeTypes | -Validates the type list of a named type in the RSE. | -
Throughout an eclipse UI there are times when we need to validate what the user has typed in. Validators +offer a way to encapsulate the error checking for a particular domain, so it can be re-used wherever the user +is prompted for this. This includes dialogs, property pages, preference pages, wizard pages and viewer +cells. Eclipse's JFace offers two interfaces for this, one for viewer cells and one for the rest. In RSE, +there is a single interface combining the requirements of both, so you can author a single validator that is +re-usable anywhere. Further, the RSE validator interface and sub-interfaces force additional information to be +supplied to enhance re-use, such as the maximum length, which can be used to set the text limit for a text field. +
+ +All RSE validator interfaces and classes are in package org.eclipse.rse.ui.validators. + +
The primary validator interface is ISystemValidator, which is extends org.eclipse.jface.dialogs.IInputValidator +and org.eclipse.jface.viewers.ICellEditorValidator. Both parent interfaces define an isValid method, +but the former takes a String while the latter takes an Object. They both return a String which is the error message if an +error was detected, or null if no error detected. The ISystemValidator interface adds the following additional methods: +
+ +| Method | +Description | +
|---|---|
| public int getMaximumNameLength() | +Returns the maximum length allowed for this text. Can be used to set text limit of text widgets. | +
| public SystemMessage getSystemMessage() | +If isValid returns false, this returns a SystemMessage object that offers richer message support than just a string. + Return null if you don't support SystemMessages. + Callers don't need to use this if they use validate(String) instead of isValid(String). | +
| public SystemMessage validate(String text) | +An alternative to isValid if your validator does support SystemMessage objects versus simple strings for error messages. | +
Often our validation requires checking that the given text is unique, in some given list of existing things, like names say. To facilitate +this, there is an interface ISystemValidatorUniqueString, which extends ISystemValidator and adds some additional +methods required for uniqueness validation: +
+ +| Method | +Description | +
|---|---|
| public void setCaseSensitive(boolean caseSensitive) | +Specifies whether the test for an existing string should consider case or not. | +
| public void setExistingNamesList(String[] existingList) | +Sets the existing list to test against, as an array. | +
| public void setExistingNamesList(Vector existingList) | +Sets the existing list to test against, as a vector of Strings. | +
| public String[] getExistingNamesList() | +Returns the existing list that is used to test against. | +
If you desire to create a unique string validator, you probably will start by subclassing ValidatorUniqueString. +
+ +The third validator interface is IValidatorRemoteSelection, which is specifically intended to be used +in the remote resource selection dialogs supplied by the RSE. It allows you to decide when to enable the OK button, based on what +is selected. It contains only the following method:
+public SystemMessage isValid(SystemConnection selectedConnection, Object[] selectedObjects, ISystemRemoteElementAdapter[] remoteAdaptersForSelectedObject); +You typically won't implement this interface directly, but rather sublcass ValidatorRemoteSelection.
+ +You may be able to avoid creating a new validator if you find that RSE has already supplied one you need. Or, you may find it +appropriate to simply subclass one of these RSE-supplied validators. All of them are designed to be either used as-is, or configured +via setter calls, or subclassed, whichever is most convenient.
+All of these validators support rich SystemMessage objects, versus just simple strings for the error message. When used with the +RSE dialog, property page or wizard page classes, you should call +validate(String) and call +setErrorMessage with the result. When used +in other places you should use isValid(String) as it returns just the first-level text of the system message.
+| Validator Class | +Description | +
|---|---|
| ValidatorCompileCommandLabel | +Validates the label for a compile command in the RSE. | +
| ValidatorConnectionName | +Validates the name of a connection in the RSE. | +
| ValidatorFileName | +Validates the name of a file in eclipse. | +
| ValidatorFilterName | +Validates the name of a filter in the RSE. | +
| ValidatorFilterPoolName | +Validates the name of a filter pool in the RSE. | +
| ValidatorFilterString | +Validates the contents of a filter string in the RSE. | +
| ValidatorFolderName | +Validates the name of a folder in eclipse. | +
| ValidatorIntegerInput | +Validates the given string is a valid integer. | +
| ValidatorIntegerRangeInput | +Validates the given string is a valid integer within a given range. | +
| ValidatorLongInput | +Validates the given string is a valid long integer. | +
| ValidatorLongRangeInput | +Validates the given string is a valid long integer within a given range. | +
| ValidatorPathName | +Validates the given string is a valid folder path in eclipse. | +
| ValidatorPortInput | +Validates the given string is a valid TCP/IP port number. | +
| ValidatorProfileName | +Validates the name of a system profile in the RSE. | +
| ValidatorRemoteSelection | +This is a very special case abstract base class, for validators that decide the enablement of the OK button + in the RSE-supplied remote resource selection dialogs. | +
| ValidatorSourceType | +A validator for source types, such as a file type or "*.java". It is intended to be subclassed. | +
| ValidatorSpecialChar | +A base class for validators that need to ensure the given string doesn't contain certain characters. | +
| ValidatorSystemName | +A name validator, to be used when the name being prompted for must follow Java identifier rules. | +
| ValidatorUniqueString | +A base class, or configurable class, to be used for any validation that requires the string to be unique within a given list. | +
| ValidatorUserActionCommand | +Validates the command of a user defined action in the RSE. | +
| ValidatorUserActionComment | +Validates the comment of a user defined action in the RSE. | +
| ValidatorUserActionName | +Validates the name of a user defined action in the RSE. | +
| ValidatorUserId | +Validates a user ID. Does only basic checking, intended to be subclassed. | +
| ValidatorUserTypeName | +Validates the name of a named type in the RSE. | +
| ValidatorUserTypeTypes | +Validates the type list of a named type in the RSE. | +
This is an example of a validator written from scratch, that just validates a customer name field is not empty. -Note that while that is all is does today, the power of encapsulation is that we can easily add additional error -checking in the future, and all dialogs or wizards that use the validator will pick up that change. -
-
-package com.ibm.etools.systems.samples.ui.frameworks.dialogs;
-import com.ibm.etools.systems.samples.*;
-import com.ibm.etools.systems.core.ui.messages.SystemMessage;
-import com.ibm.etools.systems.core.ui.validators.ISystemValidator;
-
-/**
- * A validator for a customer name. We simply ensure it is not empty, but this could easily be expanded.
- */
-public class SampleNameValidator implements ISystemValidator
-{
- private SystemMessage currentMsg;
- private SystemMessage emptyMsg;
-
- /**
- * Constructor for SampleNameValidator.
- */
- public SampleNameValidator()
- {
- super();
- emptyMsg = SamplesPlugin.getPluginMessage("SPPD1000");
- }
-
- /**
- * Required ISystemValidator interface method.
- * Return the maximum length for customer names. We return 100.
- */
- public int getMaximumNameLength()
- {
- return 100;
- }
-
- /**
- * Required ISystemValidator interface method.
- * @see com.ibm.etools.systems.core.ui.validators.ISystemValidator#getSystemMessage()
- */
- public SystemMessage getSystemMessage()
- {
- return currentMsg;
- }
-
- /**
- * Required ISystemValidator interface method.
- * @see com.ibm.etools.systems.core.ui.validators.ISystemValidator#validate(String)
- */
- public SystemMessage validate(String text)
- {
- isValid(text);
- return currentMsg;
- }
- /**
- * @see org.eclipse.jface.dialogs.IInputValidator#isValid(String)
- */
- public String isValid(String newText)
- {
- if ((newText==null) || (newText.length()==0))
- currentMsg = emptyMsg;
- // todo: more error checking
-
- if (currentMsg != null)
- return currentMsg.getLevelOneText();
- else
- return null;
- }
- /**
- * @see org.eclipse.jface.viewers.ICellEditorValidator#isValid(Object)
- */
- public String isValid(Object value)
- {
- if (value instanceof String)
- return isValid((String)value);
- return null;
- }
-}
-
-
-This is an example of a validator written from scratch, that just validates a customer name field is not empty. +Note that while that is all is does today, the power of encapsulation is that we can easily add additional error +checking in the future, and all dialogs or wizards that use the validator will pick up that change. +
+
+package org.eclipse.rse.samples.ui.frameworks.dialogs;
+import org.eclipse.rse.samples.*;
+import org.eclipse.rse.ui.messages.SystemMessage;
+import org.eclipse.rse.ui.validators.ISystemValidator;
+
+/**
+ * A validator for a customer name. We simply ensure it is not empty, but this could easily be expanded.
+ */
+public class SampleNameValidator implements ISystemValidator
+{
+ private SystemMessage currentMsg;
+ private SystemMessage emptyMsg;
+
+ /**
+ * Constructor for SampleNameValidator.
+ */
+ public SampleNameValidator()
+ {
+ super();
+ emptyMsg = SamplesPlugin.getPluginMessage("SPPD1000");
+ }
+
+ /**
+ * Required ISystemValidator interface method.
+ * Return the maximum length for customer names. We return 100.
+ */
+ public int getMaximumNameLength()
+ {
+ return 100;
+ }
+
+ /**
+ * Required ISystemValidator interface method.
+ * @see org.eclipse.rse.ui.validators.ISystemValidator#getSystemMessage()
+ */
+ public SystemMessage getSystemMessage()
+ {
+ return currentMsg;
+ }
+
+ /**
+ * Required ISystemValidator interface method.
+ * @see org.eclipse.rse.ui.validators.ISystemValidator#validate(String)
+ */
+ public SystemMessage validate(String text)
+ {
+ isValid(text);
+ return currentMsg;
+ }
+ /**
+ * @see org.eclipse.jface.dialogs.IInputValidator#isValid(String)
+ */
+ public String isValid(String newText)
+ {
+ if ((newText==null) || (newText.length()==0))
+ currentMsg = emptyMsg;
+ // todo: more error checking
+
+ if (currentMsg != null)
+ return currentMsg.getLevelOneText();
+ else
+ return null;
+ }
+ /**
+ * @see org.eclipse.jface.viewers.ICellEditorValidator#isValid(Object)
+ */
+ public String isValid(Object value)
+ {
+ if (value instanceof String)
+ return isValid((String)value);
+ return null;
+ }
+}
+
+
+This is an example of a validator written by extending an existing RSE-supplied validator, and -simply supplying unique messages. -
-
-package com.ibm.etools.systems.samples.ui.frameworks.dialogs;
-import com.ibm.etools.systems.core.ui.validators.ValidatorIntegerRangeInput;
-import com.ibm.etools.systems.samples.*;
-
-/**
- * An example of a customized validator, that prompts for a birth year.
- */
-public class SampleBirthYearValidator extends ValidatorIntegerRangeInput
-{
- /**
- * Constructor. Specifies the valid range, and unique error messages.
- */
- public SampleBirthYearValidator()
- {
- super(1900, 2003);
- super.setErrorMessages(SamplesPlugin.getPluginMessage("SPPD1001"), // empty
- SamplesPlugin.getPluginMessage("SPPD1002"), // non-numeric
- SamplesPlugin.getPluginMessage("SPPD1003")); // out of range
- }
-
-}
-
-This is an example of a validator written by extending an existing RSE-supplied validator, and +simply supplying unique messages. +
+
+package org.eclipse.rse.samples.ui.frameworks.dialogs;
+import org.eclipse.rse.ui.validators.ValidatorIntegerRangeInput;
+import org.eclipse.rse.samples.*;
+
+/**
+ * An example of a customized validator, that prompts for a birth year.
+ */
+public class SampleBirthYearValidator extends ValidatorIntegerRangeInput
+{
+ /**
+ * Constructor. Specifies the valid range, and unique error messages.
+ */
+ public SampleBirthYearValidator()
+ {
+ super(1900, 2003);
+ super.setErrorMessages(SamplesPlugin.getPluginMessage("SPPD1001"), // empty
+ SamplesPlugin.getPluginMessage("SPPD1002"), // non-numeric
+ SamplesPlugin.getPluginMessage("SPPD1003")); // out of range
+ }
+
+}
+
+This is an example of a validator written by extending an existing RSE-supplied validator, and -simply supplying unique messages. -
-package com.ibm.etools.systems.samples.ui.frameworks.dialogs;
-import com.ibm.etools.systems.core.ui.validators.ValidatorIntegerRangeInput;
-import com.ibm.etools.systems.samples.*;
-
-/**
- * An example of a customized validator, that prompts for a birth month.
- */
-public class SampleBirthMonthValidator extends ValidatorIntegerRangeInput
-{
- /**
- * Constructor. Specifies the valid range, and unique error messages.
- */
- public SampleBirthMonthValidator()
- {
- super(1, 12);
- super.setErrorMessages(SamplesPlugin.getPluginMessage("SPPD1004"), // empty
- SamplesPlugin.getPluginMessage("SPPD1005"), // non-numeric
- SamplesPlugin.getPluginMessage("SPPD1006")); // out of range
- }
-
-}
-
-This is an example of a validator written by extending an existing RSE-supplied validator, and +simply supplying unique messages. +
+package org.eclipse.rse.samples.ui.frameworks.dialogs;
+import org.eclipse.rse.ui.validators.ValidatorIntegerRangeInput;
+import org.eclipse.rse.samples.*;
+
+/**
+ * An example of a customized validator, that prompts for a birth month.
+ */
+public class SampleBirthMonthValidator extends ValidatorIntegerRangeInput
+{
+ /**
+ * Constructor. Specifies the valid range, and unique error messages.
+ */
+ public SampleBirthMonthValidator()
+ {
+ super(1, 12);
+ super.setErrorMessages(SamplesPlugin.getPluginMessage("SPPD1004"), // empty
+ SamplesPlugin.getPluginMessage("SPPD1005"), // non-numeric
+ SamplesPlugin.getPluginMessage("SPPD1006")); // out of range
+ }
+
+}
+
+This is an example of a validator written by extending an existing RSE-supplied validator, and -simply supplying unique messages. -
-package com.ibm.etools.systems.samples.ui.frameworks.dialogs;
-import com.ibm.etools.systems.core.ui.validators.ValidatorIntegerRangeInput;
-import com.ibm.etools.systems.samples.*;
-
-/**
- * An example of a customized validator, that prompts for a birth day.
- */
-public class SampleBirthDayValidator extends ValidatorIntegerRangeInput
-{
- /**
- * Constructor. Specifies the valid range, and unique error messages.
- */
- public SampleBirthDayValidator()
- {
- super(1, 31);
- super.setErrorMessages(SamplesPlugin.getPluginMessage("SPPD1007"), // empty
- SamplesPlugin.getPluginMessage("SPPD1008"), // non-numeric
- SamplesPlugin.getPluginMessage("SPPD1009")); // out of range
- }
-
-}
-
-This is an example of a validator written by extending an existing RSE-supplied validator, and +simply supplying unique messages. +
+package org.eclipse.rse.samples.ui.frameworks.dialogs;
+import org.eclipse.rse.core.ui.validators.ValidatorIntegerRangeInput;
+import org.eclipse.rse.samples.*;
+
+/**
+ * An example of a customized validator, that prompts for a birth day.
+ */
+public class SampleBirthDayValidator extends ValidatorIntegerRangeInput
+{
+ /**
+ * Constructor. Specifies the valid range, and unique error messages.
+ */
+ public SampleBirthDayValidator()
+ {
+ super(1, 31);
+ super.setErrorMessages(SamplesPlugin.getPluginMessage("SPPD1007"), // empty
+ SamplesPlugin.getPluginMessage("SPPD1008"), // non-numeric
+ SamplesPlugin.getPluginMessage("SPPD1009")); // out of range
+ }
+
+}
+
+Whether coding dialogs, property pages, preference pages or wizard pages we need to write the code to display -and process the widgets in the client area. The RSE offers some help in this area in two ways: -
-The SystemWidgetHelpers -class in com.ibm.etools.systems.core.ui -is chock full of static methods to simplify the work in populating a GridLayout composite with widgets. The GridLayout composite is the most -flexible and useful of the layouts, yet the most work to code to. These methods will help with that. The methods include: -
-The com.ibm.etools.systems.core.ui.widgets -package contains some specialized widgets you may find a use for: -
-| Widget Class | -Description | -
|---|---|
| SystemHistoryCombo | -A entry field that remembers its previous values and shows them in a dropdown so the user can easily re-select a previously typed value. The history is maintained for you, and is indexed by a key. This allows the combos to share history across numerous dialogs, property pages or wizard pages. The history can be bounded and pre-filled, and the user can clear the history at any time. This handy widget is used extensively within the RSE. | -
| InheritableEntryField | -An entry field with an left-right arrow beside it. When toggled left, the entry field is not editable and displays a supplied value. When toggled right, the entry field is editable. Useful in cases where the user can choose between an inherited or default value, or enter their own value. | -
| SystemPortPrompt | -Uses the InheritableEntryField to prompt for a TCP/IP port, where toggling to the left means port 0, or let the "first available port". | -
| SystemConnectionCombo | -This is a combo box that displays the currently defined RSE system connections. The list can be subset by system type or types. Further, you can optionally display a New button beside the combo that allows the user to create a new connection. | -
There are also many useful widgets related to the selection of remote files or folders, in package -com.ibm.etools.systems.files.ui.widgets - -
Whether coding dialogs, property pages, preference pages or wizard pages we need to write the code to display +and process the widgets in the client area. The RSE offers some help in this area in two ways: +
+The SystemWidgetHelpers +class in org.eclipse.rse.ui +is chock full of static methods to simplify the work in populating a GridLayout composite with widgets. The GridLayout composite is the most +flexible and useful of the layouts, yet the most work to code to. These methods will help with that. The methods include: +
+The org.eclipse.rse.ui.widgets +package contains some specialized widgets you may find a use for: +
+| Widget Class | +Description | +
|---|---|
| SystemHistoryCombo | +A entry field that remembers its previous values and shows them in a dropdown so the user can easily re-select a previously typed value. The history is maintained for you, and is indexed by a key. This allows the combos to share history across numerous dialogs, property pages or wizard pages. The history can be bounded and pre-filled, and the user can clear the history at any time. This handy widget is used extensively within the RSE. | +
| InheritableEntryField | +An entry field with an left-right arrow beside it. When toggled left, the entry field is not editable and displays a supplied value. When toggled right, the entry field is editable. Useful in cases where the user can choose between an inherited or default value, or enter their own value. | +
| SystemPortPrompt | +Uses the InheritableEntryField to prompt for a TCP/IP port, where toggling to the left means port 0, or let the "first available port". | +
| SystemConnectionCombo | +This is a combo box that displays the currently defined RSE system connections. The list can be subset by system type or types. Further, you can optionally display a New button beside the combo that allows the user to create a new connection. | +
There are also many useful widgets related to the selection of remote files or folders, in package +org.eclipse.rse.files.ui.widgets + +
Typically in eclipse GUI design we use a wizard to create new things, and a dialog -to prompt for secondary information, or update existing things. The Remote System Explorer -can offer help in creating wizards, just as it does in creating dialogs. -
- -The RSE offers the following classes, in package -com.ibm.etools.systems.core.ui.wizards to simplify the creation of wizards.
- -The AbstractSystemWizardPage abstract base class extends the -JFace WizardPage class to offer the following benefits to subclasses:
-The AbstractSystemWizard abstract base class extends the JFace Wizard -class to offer the following benefits to subclasses:
-Typically in eclipse GUI design we use a wizard to create new things, and a dialog +to prompt for secondary information, or update existing things. The Remote System Explorer +can offer help in creating wizards, just as it does in creating dialogs. +
+ +The RSE offers the following classes, in package +org.eclipse.rse.ui.wizards to simplify the creation of wizards.
+ +The AbstractSystemWizardPage abstract base class extends the +JFace WizardPage class to offer the following benefits to subclasses:
+The AbstractSystemWizard abstract base class extends the JFace Wizard +class to offer the following benefits to subclasses:
+There are some Eclipse extension points that are relevant as-is to the Remote System Explorer, -which we list here. We do not describe how to use these extension points here, except to document -the information needed to enable them to in Remote System Explorer. -
- -| Extension Point | -Description | -
|---|---|
| org.eclipse.ui.viewActions | -For adding actions to the pulldown menu in any view's local toolbar, or to the toolbar itself.
- To use this you need to know the ID of the RSE views, for the targetID attribute: There are:
-
|
-
| org.eclipse.ui.propertyPages | -For adding property pages for non-remote objects within the
- Remote System Explorer. To use this you need to know the class type
- of these objects for the objectClass attribute of the <page> element:
-
- |
-
| org.eclipse.ui.popupMenus | -For adding pop-up menu actions for non-remote objects within the Remote System Explorer.
- To use this you need to know the class type of these objects for the objectClass attribute
- of the <objectContribution> element:
-
- |
-
For the org.eclipse.ui.propertyPages and org.eclipse.ui.popupMenus extension points, it is
-possible to scope your property pages and actions to only filters in a particular subsystem, or connections of a
-particular system type, say. These extension points support the <filter> element, which
-allows you to specify a property name, and a property value, such that the page or action will only show if
-that property's value is the one given:
-
- <filter name="name" value="value"/>
-testAttribute(Object target,String name,String value) method. This method is implemented for the adapters for every object shown in the
-Remote Systems view, and what follows is a list of the tests it will do on the given value,
-for the given name:
-For system filter objects of type com.ibm.etools.systems.filters.SystemFilterReference, -the following names are also supported: -
For the org.eclipse.ui.popupMenus extension point, you can also use the above names -in the <visibility> and <enablement> elements, for extreme flexibility in when -the action is shown, and when it is enabled or disabled. These map to the objectState -attribute. For example: -
- <enablement>
- <objectState name="hasChildren" value="true"/>
- </enablement>
-Be aware the <visibility> element is available at the -<objectContribution> level, while the <enablement> -element is available at the <Action> level. - - + + + +
+ + + + +There are some Eclipse extension points that are relevant as-is to the Remote System Explorer, +which we list here. We do not describe how to use these extension points here, except to document +the information needed to enable them to in Remote System Explorer. +
+ +| Extension Point | +Description | +
|---|---|
| org.eclipse.ui.viewActions | +For adding actions to the pulldown menu in any view's local toolbar, or to the toolbar itself.
+ To use this you need to know the ID of the RSE views, for the targetID attribute: There are:
+
|
+
| org.eclipse.ui.propertyPages | +For adding property pages for non-remote objects within the
+ Remote System Explorer. To use this you need to know the class type
+ of these objects for the objectClass attribute of the <page> element:
+
+ |
+
| org.eclipse.ui.popupMenus | +For adding pop-up menu actions for non-remote objects within the Remote System Explorer.
+ To use this you need to know the class type of these objects for the objectClass attribute
+ of the <objectContribution> element:
+
+ |
+
For the org.eclipse.ui.propertyPages and org.eclipse.ui.popupMenus extension points, it is
+possible to scope your property pages and actions to only filters in a particular subsystem, or connections of a
+particular system type, say. These extension points support the <filter> element, which
+allows you to specify a property name, and a property value, such that the page or action will only show if
+that property's value is the one given:
+
+ <filter name="name" value="value"/>
+testAttribute(Object target,String name,String value) method. This method is implemented for the adapters for every object shown in the
+Remote Systems view, and what follows is a list of the tests it will do on the given value,
+for the given name:
+For system filter objects of type org.eclipse.rse.filters.ISystemFilterReference, +the following names are also supported: +
For the org.eclipse.ui.popupMenus extension point, you can also use the above names +in the <visibility> and <enablement> elements, for extreme flexibility in when +the action is shown, and when it is enabled or disabled. These map to the objectState +attribute. For example: +
+ <enablement>
+ <objectState name="hasChildren" value="true"/>
+ </enablement>
+Be aware the <visibility> element is available at the +<objectContribution> level, while the <enablement> +element is available at the <Action> level. + + diff --git a/rse/doc/org.eclipse.rse.doc.isv/guide/plugin/popup.html b/rse/doc/org.eclipse.rse.doc.isv/guide/plugin/popup.html index b25482d514c..cb27ee92d6b 100755 --- a/rse/doc/org.eclipse.rse.doc.isv/guide/plugin/popup.html +++ b/rse/doc/org.eclipse.rse.doc.isv/guide/plugin/popup.html @@ -1,156 +1,156 @@ - - - -
- - - - -The com.ibm.etools.systems.core.popupMenus extension point is defined in the -plugin com.ibm.etools.systems.core, and it is patterned -after Eclipse's org.eclipse.ui.popupMenus extension point. However, it is -both simplified and extended specifically for remote objects. -
-The primary element in the markup for this extension point is the <objectContribution> element, -which scopes the remote objects to which the child elements apply: -
-Within each <objectContribution> element are zero or more <menu> elements for -optionally defining cascading submenus, and <action> elements for the actual actions. -To have the actions show up in a cascading menu, use the <menu> element with these -attributes: -
-Within each <menu> element are one or more <separator> elements that partition the cascading -menu into groups. Groups are simply named physical areas of the menu. The order in which they are defined is the order they -appear in the menu. Actions always go into groups. Groups avoid the need to specify relative information to identify where -within a pop-up menu to place actions. There is only one attribute for this element: -
-Finally, within <objectContribution> elements are one or more <action> elements identifying the -actual actions, each of which only show up if the scoping criteria is met for that parent <objectContribution> -element. The attributes for <action> elements are: -
--The path attribute for the <menu> element, and the menubarPath attribute for the <action> -element, are the most difficult to master. The rules are reasonably simple though: -
-To use this extension point you will create a class that extends the -SystemAbstractPopupMenuExtensionAction class in the -package com.ibm.etools.systems.core.ui.actions. This is your action class, -and when the user selects your action, the run() -method in your action class will be called. You will rarely extend the SystemAbstractPopupMenuExtensionAction base class -directly, though. Instead there are subclasses of it that offer additional functionality for specific types of remote objects, -as shown here: -
- - -| Base Class | -Description | -
|---|---|
| SystemAbstractPopupMenuExtensionAction in - com.ibm.etools.systems.core plugin | -Base class offering generic support for any remote object pop-up menu action, for any system type. | -
| SystemAbstractRemoteFilePopupMenuExtensionAction - in com.ibm.etools.systems.core plugin | -Specialized base class offering specific support for any remote file object pop-up menu action, for any system type. | -
| ISeriesAbstractIFSPopupMenuExtensionAction - in com.ibm.etools.iseries.core plugin | -Specialized base class offering specific support for iSeries IFS file or folder pop-up menu actions. | -
| ISeriesAbstractQSYSPopupMenuExtensionAction - in com.ibm.etools.iseries.core plugin | -Specialized base class offering specific support for pop-up menu actions for iSeries objects in the QSYS file system. | -
See the pop-up menu action tutorial for a step-by-step example.
- - + + + + + + + + +The org.eclipse.rse.ui.popupMenus extension point is defined in the +plugin org.eclipse.rse.ui, and it is patterned +after Eclipse's org.eclipse.ui.popupMenus extension point. However, it is +both simplified and extended specifically for remote objects. +
+The primary element in the markup for this extension point is the <objectContribution> element, +which scopes the remote objects to which the child elements apply: +
+Within each <objectContribution> element are zero or more <menu> elements for +optionally defining cascading submenus, and <action> elements for the actual actions. +To have the actions show up in a cascading menu, use the <menu> element with these +attributes: +
+Within each <menu> element are one or more <separator> elements that partition the cascading +menu into groups. Groups are simply named physical areas of the menu. The order in which they are defined is the order they +appear in the menu. Actions always go into groups. Groups avoid the need to specify relative information to identify where +within a pop-up menu to place actions. There is only one attribute for this element: +
+Finally, within <objectContribution> elements are one or more <action> elements identifying the +actual actions, each of which only show up if the scoping criteria is met for that parent <objectContribution> +element. The attributes for <action> elements are: +
++The path attribute for the <menu> element, and the menubarPath attribute for the <action> +element, are the most difficult to master. The rules are reasonably simple though: +
+To use this extension point you will create a class that extends the +SystemAbstractPopupMenuExtensionAction class in the +package org.eclipse.rse.ui.actions. This is your action class, +and when the user selects your action, the run() +method in your action class will be called. You will rarely extend the SystemAbstractPopupMenuExtensionAction base class +directly, though. Instead there are subclasses of it that offer additional functionality for specific types of remote objects, +as shown here: +
+ + +| Base Class | +Description | +
|---|---|
| SystemAbstractPopupMenuExtensionAction in + org.eclipse.rse.ui plugin | +Base class offering generic support for any remote object pop-up menu action, for any system type. | +
| SystemAbstractRemoteFilePopupMenuExtensionAction + in org.eclipse.rse.files.ui plugin | +Specialized base class offering specific support for any remote file object pop-up menu action, for any system type. | +
| ISeriesAbstractIFSPopupMenuExtensionAction + in com.ibm.etools.iseries.core plugin | +Specialized base class offering specific support for iSeries IFS file or folder pop-up menu actions. | +
| ISeriesAbstractQSYSPopupMenuExtensionAction + in com.ibm.etools.iseries.core plugin | +Specialized base class offering specific support for pop-up menu actions for iSeries objects in the QSYS file system. | +
See the pop-up menu action tutorial for a step-by-step example.
+ + diff --git a/rse/doc/org.eclipse.rse.doc.isv/guide/plugin/propertypage.html b/rse/doc/org.eclipse.rse.doc.isv/guide/plugin/propertypage.html index bd33d7bb476..5fa0b647b28 100755 --- a/rse/doc/org.eclipse.rse.doc.isv/guide/plugin/propertypage.html +++ b/rse/doc/org.eclipse.rse.doc.isv/guide/plugin/propertypage.html @@ -1,87 +1,87 @@ - - - - - - - - -The com.ibm.etools.systems.core.propertyPages extension point is defined in the
-plugin com.ibm.etools.systems.core, and it is patterned after Eclipse's org.Eclipse.ui.propertyPages extension point, but both
-simplified and extended specifically for remote objects.
-What is a property page?
-It is a page that shows up in the Eclipse Properties dialog that users
-get to by right-clicking on an object within any tree or table view, and selecting
-the Properties action.
Extenders supply one or more <page> elements within the beginning and ending <extension> element for this. -The attributes of this <page> element are:
-To use this extension point your class will typically extend one of the supplied base classes to -make it easier to create these property pages for remote objects. The only method you must implement in these -classes is createContents(Composite), which populates the details page on the right side when the node is -selected on the left side. The supplied classes are listed here: -
- -| Base Class | -Description | -
|---|---|
| SystemAbstractPropertyPageExtensionAction - in com.ibm.etools.systems.core plugin. | -Base class offering generic support for any remote object property page. | -
| SystemAbstractRemoteFilePropertyPageExtensionAction - in com.ibm.etools.systems.core plugin. | -Specialized base class offering specific support for any remote file object property page. | -
| ISeriesAbstractIFSPropertyPageExtensionAction - in com.ibm.etools.iseries.core plugin. | -Specialized base class offering specific support for iSeries IFS file or folder property pages. | -
| ISeriesAbstractQSYSPropertyPageExtensionAction - in com.ibm.etools.iseries.core plugin. | -Specialized base class offering specific support for property pages for iSeries objects in the QSYS file system. | -
-
- -See the property page tutorial for a step-by-step example.
- - + + + + + + + + +The org.eclipse.rse.ui.propertyPages extension point is defined in the
+plugin org.eclipse.rse.ui, and it is patterned after Eclipse's org.eclipse.ui.propertyPages extension point, but both
+simplified and extended specifically for remote objects.
+What is a property page?
+It is a page that shows up in the Eclipse Properties dialog that users
+get to by right-clicking on an object within any tree or table view, and selecting
+the Properties action.
Extenders supply one or more <page> elements within the beginning and ending <extension> element for this. +The attributes of this <page> element are:
+To use this extension point your class will typically extend one of the supplied base classes to +make it easier to create these property pages for remote objects. The only method you must implement in these +classes is createContents(Composite), which populates the details page on the right side when the node is +selected on the left side. The supplied classes are listed here: +
+ +| Base Class | +Description | +
|---|---|
| SystemAbstractPropertyPageExtensionAction + in org.eclipse.rse.ui plugin. | +Base class offering generic support for any remote object property page. | +
| SystemAbstractRemoteFilePropertyPageExtensionAction + in org.eclipse.rse.files.ui plugin. | +Specialized base class offering specific support for any remote file object property page. | +
| ISeriesAbstractIFSPropertyPageExtensionAction + in com.ibm.etools.iseries.core plugin. | +Specialized base class offering specific support for iSeries IFS file or folder property pages. | +
| ISeriesAbstractQSYSPropertyPageExtensionAction + in com.ibm.etools.iseries.core plugin. | +Specialized base class offering specific support for property pages for iSeries objects in the QSYS file system. | +
+
+ +See the property page tutorial for a step-by-step example.
+ + diff --git a/rse/doc/org.eclipse.rse.doc.isv/guide/plugin/subsystem.html b/rse/doc/org.eclipse.rse.doc.isv/guide/plugin/subsystem.html index 3d5f2e5236b..4e057a8d2aa 100755 --- a/rse/doc/org.eclipse.rse.doc.isv/guide/plugin/subsystem.html +++ b/rse/doc/org.eclipse.rse.doc.isv/guide/plugin/subsystem.html @@ -1,243 +1,243 @@ - - - - - - - - -The com.ibm.etools.systems.core.subsystemfactory -extension point is defined in the plugin com.ibm.etools.systems.core. -This is the most complex extension point to use, but also the most powerful. It enables -tool providers to register a class that creates subsystem objects, which appear under -a connection when a connection is expanded in the Remote Systems view. -For example, here is an iSeries connection with four subsystems, -each created by a subsystem factory registered with this extension point. -
-The extension markup is quite simple for this extension point, -as it has only one element, <factory>, with only a few simple attributes to supply: -
-It is important to remember what the purpose of a subsystem is, and how it fits in the overall RSE model, so as to understand the programming details for supporting
-subsystems via this subsystem factory extension point. Minimumly speaking, this extension point requires a class that implements the interface
-SubSystemFactory.
-Ultimately, the intent of a subsystem factory is to provide individual
-subsystem instances to each connection, and the intent of a subsystem instance is to present remote resources for display or manipulation purposes. Thus, you must also create a class implementing the interface SubSystem.
-
-The intent of each subsystem is to show remote resources from the remote system
-identified by the parent connection, for the user. (Subsystems can in fact be hidden, which means their their role is to return remote resources for programmatic purposes only.) When the first request is made for remote objects, the subsystem is asked to connect to the remote system if it is not already.
-This job is deferred to a system object whose role it is to manage connecting and disconnecting
-to the remote physical system. By use of a system manager,
-one system can manage the live connections of multiple subsystems in the same system connection, should they happen to share the same communication pipe.
-If filters are supported
-(the default), the first connection is made, and the remote resources are subsequently shown, when filters within the subsystem
-are expanded, which results in a call to
-resolveFilterString
-in the subsystem object.
-Furthermore, you will want to supply your own
-new-filter and
-change-filter actions.
-If filters are not supported, then these remote resources are shown immediately when the subsystem itself is expanded, via a call to
-getChildren.
-Either way the resulting resources are displayed to the user. To facilitate the displaying of these objects in the RSE views, the objects
-themselves must implement the Eclipse IAdaptable interface (to enable the property sheet viewer) and there must be a specific RSE
-view
-adapter
-and an RSE remote-information
-adapter
-registered for the remote objects, which the RSE views consult to get the labels, images, actions,
-and property sheet values for the remote objects.
-Typically, you will supply actions by leveraging the user interface elements supplied by the RSE, such as base classes for messages, actions, dialogs, wizards, property pages and preference page editors. You will probably also supply a
- property page for your subsystem objects, via the Eclipse propertyPages extension point, and for your remote resource objects, via the RSE propertyPages extension point.
For many of the interfaces you must implement, there are base classes supplied that you can extend to make the development effort easier.
-The -following summarizes the minimum set of classes you will be creating in order to realize your own subsystem support, including the RSE-supplied base classes to extend:
- -| Class(es) | -Base Class | -Description | -
|---|---|---|
| subsystem factory | -DefaultSubSystemFactoryImpl | -The factory class responsible for creating instances of subsystem class | -
| subsystem | -DefaultSubSystemImpl | -The subsystem class. There will be one instance created for each connection. In addition to storing - your unique attributes, this must return the remote resource objects when a filter is expanded within the - subsystem. How that communication with the remote system is done is left up to you. | -
| system | -AbstractSystem | -Represents and manages a live connection to the remote system, doing the connecting and disconnecting. | -
| system manager | -AbstractSystemManager | -Manages a single system instance that is shared among multiple subsystems in a single connection. Even if you only have a single subsystem factory, it is useful to use this in - case you later add additional factories, and their subsystems share the same communication pipe. To enable this, all your subsystem classes need to implement a unique interface of your own creation. | -
| remote resource | -AbstractResource | -Can be used as a base class for the objects representing remote resources. | -
| new-filter wizard | -SystemNewFilterAction and - SystemFilterStringEditPane | -Displays a wizard prompting for a new filter. Filters contain filter strings, which are up to each subsystem to design and interpret. The New Filter wizard - prompts for a single filter string (more can be added in change mode). Typically you subclass SystemFilterStringEditPane to create your own - prompt for the filter string information, and then subclass SystemNewFilterAction so as to configure the default New Filter wizard to use - your edit pane in the first page. | -
| change-filter dialog | -SystemChangeFilterAction and - SystemFilterStringEditPane | -Displays a dialog prompting to change an existing filter. The default dialog allows the user to create and edit filter strings. Typically, you - override the SystemChangeFilterAction class, and configure the dialog to use the same edit pane used in the New Filter wizard. - | -
| remote element adapter | -AbstractSystemViewAdapter and - ISystemRemoteElementAdapter - | -The view adapter is an amalgamation of all the required information needed to populate the RSE views. You will define one class per unique remote object interface or class, and in it you will override methods to return the remote object's label, image, popup-menu actions, property sheet properties and children (if expandable). You can also decide whether to enable common RSE popup menu actions like rename, delete and refresh. Your view adapter will usually also implement the remote adapter interface, enabling the many common RSE capabilities to work, such as the copy, paste, drag and drop, and more. |
-
Implementing a subsystem involves the following steps, in the following order:
-See the subsystem tutorial for a step-by-step example.
- - + + + + + + + + +The org.eclipse.rse.ui.subsystemConfiguration +extension point is defined in the plugin org.eclipse.rse.ui. +This is the most complex extension point to use, but also the most powerful. It enables +tool providers to register a class that creates subsystem objects, which appear under +a connection when a connection is expanded in the Remote Systems view. +For example, here is an iSeries connection with four subsystems, +each created by a subsystem configuration registered with this extension point. +
+The extension markup is quite simple for this extension point, +as it has only one element, <configuration>, with only a few simple attributes to supply: +
+It is important to remember what the purpose of a subsystem is, and how it fits in the overall RSE model, so as to understand the programming details for supporting
+subsystems via this subsystem configuration extension point. Minimally speaking, this extension point requires a class that implements the interface
+ISubSystemFactory.
+Ultimately, the intent of a subsystem configuration is to provide individual
+subsystem instances to each connection, and the intent of a subsystem instance is to present remote resources for display or manipulation purposes. Thus, you must also create a class implementing the interface ISubSystem.
+
+The intent of each subsystem is to show remote resources from the remote system
+identified by the parent connection, for the user. (Subsystems can in fact be hidden, which means their their role is to return remote resources for programmatic purposes only.) When the first request is made for remote objects, the subsystem is asked to connect to the remote system if it is not already.
+This job is deferred to a IConnectorService object whose role it is to manage connecting and disconnecting
+to the remote physical system. By use of a connector service manager,
+one system can manage the live connections of multiple subsystems in the same system connection, should they happen to share the same communication pipe.
+If filters are supported
+(the default), the first connection is made, and the remote resources are subsequently shown, when filters within the subsystem
+are expanded, which results in a call to
+resolveFilterString
+in the subsystem object.
+Furthermore, you will want to supply your own
+new-filter and
+change-filter actions.
+If filters are not supported, then these remote resources are shown immediately when the subsystem itself is expanded, via a call to
+getChildren.
+Either way the resulting resources are displayed to the user. To facilitate the displaying of these objects in the RSE views, the objects
+themselves must implement the Eclipse IAdaptable interface (to enable the property sheet viewer) and there must be a specific RSE
+view
+adapter
+and an RSE remote-information
+adapter
+registered for the remote objects, which the RSE views consult to get the labels, images, actions,
+and property sheet values for the remote objects.
+Typically, you will supply actions by leveraging the user interface elements supplied by the RSE, such as base classes for messages, actions, dialogs, wizards, property pages and preference page editors. You will probably also supply a
+ property page for your subsystem objects, via the Eclipse propertyPages extension point, and for your remote resource objects, via the RSE propertyPages extension point.
For many of the interfaces you must implement, there are base classes supplied that you can extend to make the development effort easier.
+The +following summarizes the minimum set of classes you will be creating in order to realize your own subsystem support, including the RSE-supplied base classes to extend:
+ +| Class(es) | +Base Class | +Description | +
|---|---|---|
| subsystem configuration | +SubSystemConfiguration | +The factory class responsible for creating instances of subsystem class | +
| subsystem | +SubSystem | +The subsystem class. There will be one instance created for each connection. In addition to storing + your unique attributes, this must return the remote resource objects when a filter is expanded within the + subsystem. How that communication with the remote system is done is left up to you. | +
| system | +AbstractConnectorService | +Represents and manages a live connection to the remote system, doing the connecting and disconnecting. | +
| system manager | +AbstractConnectorServiceManager | +Manages a single system instance that is shared among multiple subsystems in a single connection. Even if you only have a single subsystem configuration it is useful to use this in + case you later add additional factories, and their subsystems share the same communication pipe. To enable this, all your subsystem classes need to implement a unique interface of your own creation. | +
| remote resource | +AbstractResource | +Can be used as a base class for the objects representing remote resources. | +
| new-filter wizard | +SystemNewFilterAction and + SystemFilterStringEditPane | +Displays a wizard prompting for a new filter. Filters contain filter strings, which are up to each subsystem to design and interpret. The New Filter wizard + prompts for a single filter string (more can be added in change mode). Typically you subclass SystemFilterStringEditPane to create your own + prompt for the filter string information, and then subclass SystemNewFilterAction so as to configure the default New Filter wizard to use + your edit pane in the first page. | +
| change-filter dialog | +SystemChangeFilterAction and + SystemFilterStringEditPane | +Displays a dialog prompting to change an existing filter. The default dialog allows the user to create and edit filter strings. Typically, you + override the SystemChangeFilterAction class, and configure the dialog to use the same edit pane used in the New Filter wizard. + | +
| remote element adapter | +AbstractSystemViewAdapter and + ISystemRemoteElementAdapter + | +The view adapter is an amalgamation of all the required information needed to populate the RSE views. You will define one class per unique remote object interface or class, and in it you will override methods to return the remote object's label, image, popup-menu actions, property sheet properties and children (if expandable). You can also decide whether to enable common RSE popup menu actions like rename, delete and refresh. Your view adapter will usually also implement the remote adapter interface, enabling the many common RSE capabilities to work, such as the copy, paste, drag and drop, and more. |
+
Implementing a subsystem involves the following steps, in the following order:
+See the subsystem tutorial for a step-by-step example.
+ + diff --git a/rse/doc/org.eclipse.rse.doc.isv/guide/plugin/systemtype.html b/rse/doc/org.eclipse.rse.doc.isv/guide/plugin/systemtype.html index dd8ba4e1a9a..e0c1f26d77d 100755 --- a/rse/doc/org.eclipse.rse.doc.isv/guide/plugin/systemtype.html +++ b/rse/doc/org.eclipse.rse.doc.isv/guide/plugin/systemtype.html @@ -1,37 +1,37 @@ - - - - - - - - -The com.ibm.etools.systems.core.systemtype extension point is defined in the -plugin com.ibm.etools.systems.core. It enables new system types to be -defined in the Remote System Explorer's New -Connection wizard, such that users can define connections to systems of that type. For example, -you might define a new system type of "Solaris" or "RedHat" or some other specific type -of operating system. The reason to define a system type is to enable tools to be created, -via the subsystem extension point, that are scoped so as to -only appear for connections to systems of that type. -
--Defining a new system type is easy. You merely need to supply the name of the system -type, and two icons - one icon for connections to that systems of that type, and another -adorned icon that is used when there is a live connection to that particular system. -
--When youcreates a new connection, the Remote System Explorer framework will consult -each registered subsystem extension point to see if it supports -that connection's system type, and if so the extension point's subsystem factory class -will be used to create a new subsystem within the new connection. Thus, when the user -expands a connection in the Remote Systems view, only subsystems supported for that -connection's system type are available. -
- - + + + + + + + + +The org.eclipse.rse.ui.systemType extension point is defined in the +plugin org.eclipse.rse.ui. It enables new system types to be +defined in the Remote System Explorer's New +Connection wizard, such that users can define connections to systems of that type. For example, +you might define a new system type of "Solaris" or "RedHat" or some other specific type +of operating system. The reason to define a system type is to enable tools to be created, +via the subsystem extension point, that are scoped so as to +only appear for connections to systems of that type. +
++Defining a new system type is easy. You merely need to supply the name of the system +type, and two icons - one icon for connections to that systems of that type, and another +adorned icon that is used when there is a live connection to that particular system. +
++When you create a new connection, the Remote System Explorer framework will consult +each registered subsystem extension point to see if it supports +that connection's system type, and if so the extension point's subsystem factory class +will be used to create a new subsystem within the new connection. Thus, when the user +expands a connection in the Remote Systems view, only subsystems supported for that +connection's system type are available. +
+ + diff --git a/rse/doc/org.eclipse.rse.doc.user/concepts/cfilters.html b/rse/doc/org.eclipse.rse.doc.user/concepts/cfilters.html index 1e3bb99f31c..d9ef6ed69b1 100755 --- a/rse/doc/org.eclipse.rse.doc.user/concepts/cfilters.html +++ b/rse/doc/org.eclipse.rse.doc.user/concepts/cfilters.html @@ -1,116 +1,116 @@ - - - - - - - -The Remote System Explorer is a set of local client tools you use to
-organize
-how you want to work with the resources such as folders and files on
-your
-remote server. The following graphic serves as an introduction to
-some of the main components of the Remote System Explorer:
-
-
The Remote System Explorer perspective is designed to allow you to -manipulate the resources directly on the remote system. The -actions that are available depend on the type of system you are -connecting to and the way the resource is recognized. For -example, your selections can define -a filter string to find all files that match *.c in a partcular -directory.
-If -you have been using the Remote System Explorer for some -time, your workspace might contain too many filters to navigate easily. -Or, -you might just want to keep groups of filters separate if, for example, -you -need to represent two distinct environments in the Remote System -Explorer, -regardless of how many filters you have. In either case, you can group -filters -into filter pools.
-For example, one filter pool could contain filters for an accounts -receivable -program while another contains filters for a payroll program. Or, if -you -have two different environments on your server: a production -environment and a test environment, you can define a distinct -environment and set of filters for each.
-Without -filter pools, all of your filters appear together -in all connections. When you create filter pools, however, any filter -you -create within that filter pool is distinct to that connection, and will -not -appear in any other connections. (See the related links for more -information -about filter pools.)
-You -can share filter pools among many connections through -the use of a filter pool reference. A filter pool reference is -a mechanism -that displays a filter pool from one connection in any other -connection, so -that when you make a change to the original filter pool, your change is -reflected -your filter pool reference.
-All connections, filters, filter pools, and so on, belong to a
-Remote System Explorer profile, that you define during your
-first connection
-to a server. You might wonder what happens to your filters or filter
-pools if you delete a connection, especially if you have filters shared
-among
-two or more connections. Rest assured that the filters are not deleted,
-since
-filters actually belong to profiles, and not connections.
-
Keep in mind that if you need to have an entirely new configuration -of filter pools, filters and connection in the Remote System Explorer, -you can always create a new profile. See -the related links for more information.
-Related concepts
-User actions (user options)
-Compiling
-
Related Tasks
-Configuring filter pools
-Changing
-filters
-Deleting filters
-Creating a second
-profile
-
The Remote System Explorer is a set of local client tools you use to
+organize
+how you want to work with the resources such as folders and files on
+your
+remote server. The following graphic serves as an introduction to
+some of the main components of the Remote System Explorer:
+
+
The Remote System Explorer perspective is designed to allow you to +manipulate the resources directly on the remote system. The +actions that are available depend on the type of system you are +connecting to and the way the resource is recognized. For +example, your selections can define +a filter string to find all files that match *.c in a particular +directory.
+If +you have been using the Remote System Explorer for some +time, your workspace might contain too many filters to navigate easily. +Or, +you might just want to keep groups of filters separate if, for example, +you +need to represent two distinct environments in the Remote System +Explorer, +regardless of how many filters you have. In either case, you can group +filters +into filter pools.
+For example, one filter pool could contain filters for an accounts +receivable +program while another contains filters for a payroll program. Or, if +you +have two different environments on your server: a production +environment and a test environment, you can define a distinct +environment and set of filters for each.
+Without +filter pools, all of your filters appear together +in all connections. When you create filter pools, however, any filter +you +create within that filter pool is distinct to that connection, and will +not +appear in any other connections. (See the related links for more +information +about filter pools.)
+You +can share filter pools among many connections through +the use of a filter pool reference. A filter pool reference is +a mechanism +that displays a filter pool from one connection in any other +connection, so +that when you make a change to the original filter pool, your change is +reflected +your filter pool reference.
+All connections, filters, filter pools, and so on, belong to a
+Remote System Explorer profile, that you define during your
+first connection
+to a server. You might wonder what happens to your filters or filter
+pools if you delete a connection, especially if you have filters shared
+among
+two or more connections. Rest assured that the filters are not deleted,
+since
+filters actually belong to profiles, and not connections.
+
Keep in mind that if you need to have an entirely new configuration +of filter pools, filters and connection in the Remote System Explorer, +you can always create a new profile. See +the related links for more information.
+Related concepts
+User actions (user options)
+Compiling
+
Related Tasks
+Configuring filter pools
+Changing
+filters
+Deleting filters
+Creating a second
+profile
+
