![[Previous]](../pics/prev.gif){kind=small}
![[Contents]](../pics/toc.gif){kind=small}
![[Next]](../pics/next.gif){kind=small}
![[IONA Technologies]](../pics/iona.gif){kind=small}
The primary activation modes are shared, unshared, and per-method. In shared mode, all1 of the objects with the same server name on a given machine are managed by one process on that machine. In unshared mode, individual objects are registered with the Implementation Repository, and a process is launched for each such object. In per-method mode, individual operations are registered with the Implementation Repository, and each invocation on an operation results in a separate process. If a server is registered in shared mode, then it can be launched manually prior to any invocation on its objects. Such servers are referred to as persistent servers in the CORBA specification.
impl_is_ready(), behave in a similar way to shared activation mode servers. If a server is registered as unshared or per-method, then, in line with the CORBA specification, impl_is_ready() will fail if the server is launched manually (see the API description for IE.Iona.Orbix2.CORBA.BOA.impl_is_ready() in Part II of this guide).
putit command is:
putit <switches> <server name> <command line>where
<command line> is usually an absolute pathname specifying an executable file that implements the server. It could also be a shell command or a shell script.OrbixWeb servers are implemented as Java classes and should be registered using the
putit -java switch. This switch allows a class name (and an optional class path) to be specified as follows:
putit <switches> <server name> -java <class name> <class arguments>This command specifies that the OrbixWeb daemon, when required to launch the server, should invoke the Java interpreter on the specified bytecode. Any command line parameters to be given to the target class are appended after the class name in the
putit command. These parameters are given to the server every time it is run by OrbixWeb (however, they must be given explicitly if the server is launched manually).If the arguments to the class to be interpreted include a hyphen (`
-') character, then this character must be protected from being interpreted as a switch to putit. This can be done by, for example, putting the class name and its arguments in a string delineated by double-quotes:
putit BankSrv -java "BankerClass -b"
Orbix.cfg, supports the specification of a default class path which will be used by the OrbixWeb daemon when launching all Java servers. As described in Chapter 3, "OrbixWeb Configuration", the configuration variable IT_DEFAULT_CLASSPATH stores the default class path value.putit <switches> <server name> -java -classpath <full class path> <class name> <class arguments>For example:
putit BankSrv -java -classpath /vol/jdk/classes:/orbixweb/classes BankerClassAs an alternative, OrbixWeb also allows a partial class path to be specified during server registration. This partial class path will be appended to the value of
IT_DEFAULT_CLASSPATH if the OrbixWeb daemon attempts to launch the specified server. The -addpath switch is used to specify a partial class path:
putit <switches> <server name> -java -addpath <partial class path> <class name> <class arguments>The functionality of the
-classpath example given above could be achieved by setting IT_DEFAULT_CLASSPATH to the value /vol/jdk/classes and registering the server BankSrv as follows:
putit BankSrv -java -addpath /orbixweb/classes BankerClass
IT_JAVA_INTERPRETER in the file Orbix.cfg, as described in Chapter 3, "OrbixWeb Configuration".
Passing Parameters to the Java Interpreter
Conceptually, the class path details, class name and class arguments specified during the registration of an OrbixWeb server will be passed directly to the Java interpreter when the server is launched. If specific arguments should also be passed to the Java interpreter, then these can be added to the putit command as follows:
putit <switches> <server name> -java "<interpreter switches> <class name> <class arguments>"The string contained in double-quotes will be passed to the Java interpreter instead of the standard class name and class arguments.
Although registering a full Java interpreter command as an executable file for an OrbixWeb server would appear to achieve similar functionality, this is not an acceptable alternative. The
-java switch significantly alters the internal server launch strategy of the OrbixWeb daemon and an OrbixWeb server should not be registered without this switch (unless the jrunit intermediate command is used as described in section 1.2.6).
1.2.1 Switches to putit
The syntax of the putit command is:
putit [-v] [-h <host>]
[-per-client | -per-client-pid]
[-shared |-unshared] [-marker <marker>] ]
| [ -per-method [-method <method>]]
[-port <iiop port>]
[-n <number of servers>]
<server name>
{<executable command line> | {-java
[-classpath <class path>] <class name>
[<class arguments>]}
| -persistent}
The switches are as follows: In the shared mode:
In the shared and unshared modes:
-marker <marker>
|
Specifies a marker value to identify a specific object, or set of objects, to which the putit applies. Note that marker names specified using putit cannot contain white space. See Chapter 7, "Publishing Object References in Servers", of the for details of how marker names may be assigned to an object.
|
In the per-method mode:
-method <method>
|
Specifies a method name to identify a specific method, or set of methods, to which the putit applies.
|
Executing
putit without any arguments outputs a summary of its switches.
putit FirstTrust -java
-classpath /home/chris/classes:/usr/classes BankClass
FirstTrust" on the local host, with the specified full class path and class name. Activation (launching) occurs when any of the objects managed by the FirstTrust server is invoked; there will be at most one server process associated with this server. All end users share the same server process.
putit -h alpha FirstTrust -java BankClass arg1
FirstTrust" on the host "alpha", with the specified class name and command line argument. Activation will occur as in (1).
putit -marker College_Green NationalBank -java BankClass
NationalBank" on the local host, with the specified class name. However activation will only occur for the object whose marker matches "College_Green". There will be at most one server process resulting from this registration request; although other -marker registrations can be issued for server NationalBank. All end users share the same server process.
putit -shared -marker St_Stephens_Green BankTrust -java BankClass
putit -unshared -marker College_Green FirstNational -java BankClass
putit -marker St_Stephens_Green FirstNational -java BankClass
FirstNational" on the local host with the specified class name and the second adds an activation order (marker and launch command) for the "St_Stephens_Green" marker. However activation will only occur for objects whose marker name is "College_Green" or "St_Stephens_Green" and each activation for a specific object will go to a unique server process for that particular object. All end users of a specific object share the same server process.
putit -per-client -unshared -marker College_Green \
NationalTrust -java BankClass
putit -marker St_Stephens_Green \
NationalTrust -java BankClass
NationalTrust" on the local host with the specified class name and the second adds an activation order for the marker "St_Stephens_Green". However activation will only occur for objects whose marker name is "College_Green" or "St_Stephens_Green", and each activation for that object will go to a unique server process for that particular object. Furthermore, each end-user will be bound to a separate server process, if two or more end-users bind to the same marker. Note that per-client activation mode results in a separate process for each end-user (principal); different clients owned by the same end-user will bind to the same process. The following examples of calls to _bind() illustrate this:
chris
_BankRef b1Ref = Bank._bind("College_Green:NationalTrust");
joan
_BankRef b2Ref = Bank._bind("College_Green:NationalTrust");
chris
_BankRef b3Ref = Bank._bind("College_Green:NationalTrust");
joe
_BankRef b4Ref = Bank._bind("College_Green:NationalTrust");
putit FirstTrust -persistent
FirstTrust" on the local host. This server is to be launched persistently; it will not be activated automatically when an object managed by the FirstTrust server is invoked. No launch command is specified to putit, since the server will be manually launched.
putit -per-client-pid FirstTrust -java BankClass
FirstTrust" on the local host, with the specified class name. Activation (launching) occurs when any of the objects managed by the FirstTrust server is invoked; there will be a separate server process for each different client process associated with this server.
putit -per-client-pid -unshared -marker \
College_Green FirstNational -java BankClass
FirstNational" on the local host with the specified class name. However activation will only occur for objects whose marker name is "College_Green" and each activation for a specific object and specific client process will go to a unique server process for that particular object and client process.
putit -per-method -method makeWithdrawal \
NationalTrust -java BankClass
NationalTrust" on the local host with the specified class name. The activation is to occur only if the operation makeWithdrawal() is being called.
putit -method makeDeposit NationalTrust -java BankClass
-method switch is specified, the server is assumed to be a per-method server.
-marker switch, or a set of methods for the -method switch. The use of pattern matching allows a group of server processes to share a workload between them, whereby each server process is responsible for a range of object marker values. The pattern matching is based on regular expressions, as follows:A SET, as presented above, is composed of characters and ranges. A range is specified using a hyphen character `
-'.Finally, since each of the characters
*?!^-[]\ is special, in the sense that it is interpreted by the pattern matching algorithm; each of them can be preceded by a `\' character to suppress its interpretation.Examples of patterns are:
putit commands that make use of pattern matching are:
putit -marker '*Green' NationalBank -java BankClass
NationalBank" on the local host, with the specified class name. However activation will only occur for objects whose marker names match "*Green", for example, College_Green, and all matching activations will go to the same server process. All matching activations from different end-users share the same process.
putit -shared -marker '*Green' NationalBank -java BankClass
putit -unshared -marker '*Green' FirstNational -java BankClass
FirstNational" on the local host with the specified class name. However activation will only occur for objects whose marker names match "*Green", and each matching activation for a specific object will go to a unique server process for that particular object. Multiple server processes can result from this registration–one per object with a marker matching the pattern. All matching activations from different end-users share the same process.
putit -per-client -unshared -marker '*Green' \
NationalTrust -java BankClass
NationalTrust" on the local host with the specified class name. However activation will only occur for objects whose marker names match "*Green", and each matching activation for a specific object will go to a separate server process for that particular object. Furthermore, each end-user will be bound to a separate server process, even if two or more end-users bind to the same marker. Contrast this to (3) above. The following examples of calls to _bind() illustrate this:
chris
_BankRef b1Ref = Bank._bind("College_Green:NationalTrust");
joan
_BankRef b2Ref = Bank._bind("College_Green:NationalTrust");
chris
_BankRef b3Ref = Bank._bind("College_Green:NationalTrust");
joe
_BankRef b4Ref = Bank._bind("College_Green:NationalTrust");
putit -per-method FirstTrust -method 'make*' -java BankClass
FirstTrust" on the local host with the specified class name. The activation is to occur only if an operation matching the pattern "make*" is being called, for example makeDeposit() or makeWithdrawal(). A separate process is activated for each method call.
putit FirstTrust -method 'make*' -java BankClass
-method switch is specified, the server is assumed to be a per-method server.
putit mean that the command:
putit <server name> -java <class name>
putit -shared <server name> -java <class name>
putit -shared -marker '*' <server name> -java <class name>
putit -marker '*' <server name> -java <class name>
putit -marker 'Green*' NationalBank -java BankClass
putit -marker 'Blue*' NationalBank -java BankClass
NationalBank can have up to two active processes; one launched for markers beginning with "Green" and the other for markers beginning with "Blue". Such registrations can be used as a means of sharing work between server processes (in this case, between two processes).
putit commands adds a new activation order to the Implementation Repository entry for the server NationalBank:
putit -marker College_Green NationalBank -java BankClassA
putit -marker St_Stephens_Green NationalBank -java BankClassB
putit -marker '*Green' NationalBank -java BankClassB
putit -marker '*' NationalBank -java BankClassC
putit command.However, this functionality can be imitated using an intermediate executable file which the daemon can launch and which can, in turn, invoke the Java interpreter. Each OrbixWeb installation includes a program which can be used for this purpose; this program is called
jrunit and is installed by default in the OrbixWeb bin directory.To register an OrbixWeb server in the Orbix Implementation Repository, the Orbix
putit command (which currently doesn't support the -java switch) should be used as follows:
putit <server name> "jrunit -classpath <class path> <class name> <class arguments>"The following Orbix
putit command:
putit BankSrv "jrunit -classpath /usr:/users/chris/banker idl_demo.BankServer"is equivalent to the OrbixWeb
putit command:
putit BankSrv -java -classpath /usr:/users/chris/banker idl_demo.BankServerNote that, if the
jrunit command specified in the server launch command is not prefixed by a full path name, then the location of jrunit should be in the environment path setting, as passed to the Orbix daemon at start-up.
putit. The full syntax of all utility commands is given in section 1.3.7.
1.3.1 lsit, catit, rmit
The following commands are commonly used to manage Implementation Repository entries created by putit:
Register a server called AIB: % putit AIB -java BankClass Register a server called Berliner. "Berlin 9801" are parameters to the Java class used by it. % putit Berliner -java BankClass \ Berlin 9801 % putit BBL -addpath /opt/classes:/classes \ Brussels % putit printer -java laser % catit Berliner name: Berliner Comms: xdr/tcp Activation: shared Owner: smith Launch: ;jones;developers;friends; Invoke: ;all; Per-client: false Marker Launch_Command * ###ORBIXWEB### Berlin 98-00-00 % lsit AIB BBL Berliner printer % rmit printer % lsit AIB BBL BerlinerThe
rmit command takes the following arguments:
rmit [-v] [-h <hostname>] <server> [-marker <marker> | -method <method>]The
-v switch outputs the program version information; it is available on all of the utility commands. All of the utility commands also output a summary of their switches if executed without any parameters.The
-marker and -method switches can be used to remove an activation order for an individual object (in the shared or unshared activation modes) or for an individual method (in the per-method call activation mode). A command of the form:
rmit <server>removes all activation orders for that server.
mkdirit makes a new registration directory,
banking–and make a registration within it:
mkdirit banking putit banking/Berliner -java BankClassThus
banking/Berliner is a valid (hierarchical) server name. It can be used in bind calls such as:
_BankRef bRef = Bank._bind( "College_Green:banking/Berliner");Hierarchical names are extremely useful in structuring the name space of servers in Implementation Repositories.
rmdirit removes a registration directory.
-R switch to recursively delete a directory and the Implementation Repository entries and sub-directories within it. The rmdirit command returns an error if it is called without the -R switch on a non-empty registration directory. For example:
% lsit AIB BBL Berliner banking printer % rmdirit banking directory not empty % rmdirit -R banking % lsit AIB BBL Berliner printer
psit command outputs a list of server processes known to an OrbixWeb daemon. It takes the following arguments:
psit [-v] [-h hostname]One line is output for each server process. Each line has the format:
Name Marker Code Comms Port Status Per-Client? OS-pid
Name gives the server name.
Marker gives the marker name.
Code is the data encoder used, for example, xdr.
Comms is the communications protocol used, for example, tcp.
Port is the port number used by the communications system.
Status is one of "automatic", "manual" or "inactive".
Per-Client? indicates whether the server is a per-client server.
OS-pid is the operating system process identifier of the process.
killit command kills a server process. On UNIX, it uses the SIGTERM signal. It takes the following arguments:
killit [-v] [-h hostname] [-m marker] servernameWhere there is more than one server process, the marker parameter to
killit is used to select between different processes. The marker parameter is required when killing a process in the unshared mode.The
pingit command tries to contact an OrbixWeb daemon, outputting a success or failure message. It takes the following arguments:
pingit [-v] [-h hostname]
chownit command. The
chownit command takes the following arguments:
Thechownit [-v] [-h hostname]{ -s servername new_owner |-d directory { +, - } {user, group} }
-s switch allows the user to change the ownership of an Implementation Repository entry. Only the current owner of an Implementation Repository entry has the right to change its ownership. An example is:
mcnamara:
chownit -s AIB mcnamaraAn Implementation Repository directory may have more than one owner. An ownership access control list (ACL) is associated with each directory in the Implementation Repository, and this ACL can be modified to give certain users or groups ownership rights on a directory. The
-d switch modifies the ACL on a directory allowing the user to add or remove a user or group from the list of owners of a directory. Only a user on an ownership ACL has the right to modify the ACL. Some examples are:
iona to the ownership ACL on Implementation Repository directory banks/investmentBanks:
chownit -d banks/investmentBanks + iona
mcnamara from the same ACL:
chownit -d banks/investmentBanks - mcnamaraNote that spaces are significant in this grammar. You cannot type:
chownit -dbanks/investmentBanks + iona chownit -d banks/investmentBanks -mcnamaraOrbixWeb supports the fictitious group
all which, when added to an ACL, grants access to all callers. The following command grants all users the ownership rights on directory banks/commercialBanks:
chownit -d banks/commercialBanks + all
chmodit command. Only the current owner of an Implementation Repository entry has the right to change its access controls. The syntax is:
chmodit [-v] [-h hostname]
{ server | -a directory }
{ i{+,-}{user, group}|
l{+,-}{user, group} }
By specifying the l switch, a user or group can be added or removed from the launch ACL. For example, to allow chris to launch the server AIB:
chmodit AIB l+chrisThe
-a switch specifies that a user or group is to be added to an ACL for a directory of servers. For example, the following command grants chris rights to launch any server in the directory banks/investmentBanks:
chmodit -a banks/investmentBanks l+chrisBy specifying the
i switch, a user or group can be added or removed from the invoke ACL. For example, the following command revokes joe's right to invoke all servers in the Implementation Repository directory banks/commercialBanks:
chmodit -a banks/commercialBanks i-joeThe group
all which, when added to an ACL, grants access to all callers. The following command grants all users the right to invoke the server banks/commercialBanks/AIB:
chmodit banks/commercialBanks/AIB i+all
catit [-v] [-h hostname] server_name
chmodit [-v] [-h hostname]
{ server | -a directory }
[i{+,-}{user, group}|
l{+,-}{user, group}]
chownit [-v] [-h hostname]
{ -s servername new_owner |
-d directory { +, - } {user, group} }
killit [-v] [-h hostname] [-m marker] servername
lsit [-v] [-R] [-h hostname] directory
mkdirit [-v] [-h hostname] dir_name
pingit [-v] [-h hostname]
psit [-v] [-h hostname]
putit [-v] [-h <host>]
[-per-client | -per-client-pid]
[-shared |-unshared] [-marker <marker>] ]
| [ -per-method [-method <method>]]
<serverName> { <commandLine> | -persistent }
rmdirit [-v] [-R] [-h hostname] dir_name
rmit [-v] [-h hostname]
[-marker marker | -method method] server_name
The common switches have the following meanings:Each utility command outputs a summary of its switches if executed without any parameters.