JBoss.orgCommunity Documentation

Chapter 2. ORB Portability API

2.1. Using the ORB and OA
2.1.1. ORB and OA Initialisation
2.1.2. ORB and OA shutdown
2.1.3. Specifying the ORB to use
2.1.4. Initialisation code
2.1.5. Locating Objects and Services
2.1.6. ORB location mechanisms

2.1. Using the ORB and OA

The ORB class shown below provides a uniform way of using the ORB. There are methods for obtaining a reference to the ORB, and for placing the application into a mode where it listens for incoming connections. There are also methods for registering application specific classes to be invoked before or after ORB initialisation. Note, some of the methods are not supported on all ORBs, and in this situation, a suitable exception will be thrown. The ORB class is a factory class which has no public constructor. To create an instance of an ORB you must call the getInstance method passing a unique name as a parameter. If this unique name has not been passed in a previous call to getInstance you will be returned a new ORB instance. Two invocations of getInstance made with the same unique name, within the same JVM, will return the same ORB instance.

Example 2.1.  ORB.java 

 public class ORB {

    public static ORB getInstance(String uniqueId);


    public synchronized void initORB()

            throws SystemException;


    public synchronized void initORB(Applet a, Properties p)

            throws SystemException;


    public synchronized void initORB(String[] s,

            Properties p) throws SystemException;


    public synchronized org.omg.CORBA.ORB orb();


    public synchronized boolean setOrb(

            org.omg.CORBA.ORB theORB);


    public synchronized void shutdown();


    public synchronized boolean addAttribute(Attribute p);


    public synchronized void addPreShutdown(PreShutdown c);


    public synchronized void addPostShutdown(PostShutdown c);


    public synchronized void destroy()

            throws SystemException;


    public void run();


    public void run(String name);

} 

We shall now describe the various methods of the ORB class.

  • initORB : given the various parameters, this method initialises the ORB and retains a reference to it within the ORB class. This method should be used in preference to the raw ORB interface since the JBoss Transaction Service requires a reference to the ORB. If this method is not used, setOrb must be called prior to using JBoss Transaction Service .

  • orb : this method returns a reference to the ORB. After shutdown is called this reference may be null.

  • shutdown : where supported, this method cleanly shuts down the ORB. Any pre- and post- ORB shutdown classes which have been registered will also be called. See the section titled ORB and OA Initialisation. This method must be called prior to application termination. It is the application programmer’s responsibility to ensure that no objects or threads continue to exist which require access to the ORB. It is ORB implementation dependant as to whether or not outstanding references to the ORB remain useable after this call.

  • addAttribute : this method allows the application to register classes with JBoss Transaction Service which will be called either before, or after the ORB has been initialised. See the section titled ORB and OA Initialisation. If the ORB has already been initialised then the attribute object will not be added, and false will be returned.

  • run : these methods place the ORB into a listening mode, where it waits for incoming invocations.

The OA classes shown below provide a uniform way of using Object Adapters (OA). There are methods for obtaining a reference to the OA. There are also methods for registering application specific classes to be invoked before or after OA initialisation. Note, some of the methods are not supported on all ORBs, and in this situation, a suitable exception will be thrown. The OA class is an abstract class and provides the basic interface to an Object Adapter. It has two sub-classes RootOA and ChildOA, these classes expose the interfaces specific to the root Object Adapter and a child Object Adapter respectively. From the RootOA you can obtain a reference to the RootOA for a given ORB by using the static method getRootOA. To create a ChildOA instance use the createPOA method on the RootOA.

Example 2.2.  OA.java 

 public abstract class OA {

    public synchronized static RootOA getRootOA(

            ORB associatedORB);


    public synchronized void initPOA()

            throws SystemException;


    public synchronized void initPOA(String[] args)

            throws SystemException;


    public synchronized void initOA()

            throws SystemException;


    public synchronized void initOA(String[] args)

            throws SystemException;


    public synchronized ChildOA createPOA(

            String adapterName, PolicyList policies)

            throws AdapterAlreadyExists, InvalidPolicy;


    public synchronized org.omg.PortableServer.POA rootPoa();


    public synchronized boolean setPoa(

            org.omg.PortableServer.POA thePOA);


    public synchronized org.omg.PortableServer.POA poa(

            String adapterName);


    public synchronized boolean setPoa(String adapterName,

            org.omg.PortableServer.POA thePOA);


    public synchronized boolean addAttribute(OAAttribute p);


    public synchronized void addPreShutdown(OAPreShutdown c);


    public synchronized void addPostShutdown(

            OAPostShutdown c);

}


public class RootOA extends OA {

    public synchronized void destroy()

            throws SystemException;


    public org.omg.CORBA.Object corbaReference(Servant obj);


    public boolean objectIsReady(Servant obj, byte[] id);


    public boolean objectIsReady(Servant obj);


    public boolean shutdownObject(org.omg.CORBA.Object obj);


    public boolean shutdownObject(Servant obj);

}


public class ChildOA extends OA {

    public synchronized boolean setRootPoa(POA thePOA);


    public synchronized void destroy()

            throws SystemException;


    public org.omg.CORBA.Object corbaReference(Servant obj);


    public boolean objectIsReady(Servant obj, byte[] id)

            throws SystemException;


    public boolean objectIsReady(Servant obj)

            throws SystemException;


    public boolean shutdownObject(org.omg.CORBA.Object obj);


    public boolean shutdownObject(Servant obj);

} 

We shall now describe the various methods of the OA class.

  • initPOA : this method activates the POA, if this method is called on the RootPOA the POA with the name RootPOA will be activated.

  • createPOA : if a child POA with the specified name for the current POA has not already been created then this method will create and activate one, otherwise AdapterAlreadyExists will be thrown. This method returns a ChildOA object.

  • initOA : this method calls the initPOA method and has been retained for backwards compatibility.

  • rootPoa : this method returns a reference to the root POA. After destroy is called on the root POA this reference may be null.

  • poa : this method returns a reference to the POA. After destroy is called this reference may be null.

  • destroy : this method destroys the current POA, if this method is called on a RootPOA instance then the root POA will be destroyed along with its children.

  • shutdown : this method shuts down the POA.

  • addAttribute : this method allows the application to register classes with JBoss Transaction Service which will be called either before or after the OA has been initialised. See below. If the OA has already been initialised then the attribute object will not be added, and false will be returned.

It is possible to register application specific code with the ORB portability library which can be executed either before or after the ORB or OA are initialised. Application programs can inherit from either com.arjuna.orbportability.orb.Attribute or com.arjuna.orbportability.oa.Attribute and pass these instances to the addAttribute method of the ORB/OA classes respectively:

Example 2.3.  Attribute.java 

 package com.arjuna.orbportability.orb;

public abstract class Attribute {

    public abstract void initialise(String[] params);


    public boolean postORBInit();

};


package com.arjuna.orbportability.oa;

public abstract class OAAttribute {

    public abstract void initialise(String[] params);


    public boolean postOAInit();

}; 

By default, the postORBInit/postOAInit methods return true, which means that any instances of derived classes will be invoked after either the ORB or OA have been initialised. By redefining this to return false, a particular instance will be invoked before either the ORB or OA have been initialised.

When invoked, each registered instance will be provided with the exact String parameters passed to the initialise method for the ORB/OA.

It is possible to register application specific code (via the addPreShutdown/addPostShutdown methods) with the ORB portability library which will be executed prior to, or after, shutting down the ORB. The pre/post interfaces which are to be registered have a single work method, taking no parameters and returning no results. When the ORB and OA are being shut down (using shutdown/destroy ), each registered class will have its work method invoked.

Example 2.4.  Shutdown.java 

 public abstract class PreShutdown {

    public abstract void work();

}


public abstract class PostShutdown {

    public abstract void work();

} 

JDK releases from 1.2.2 onwards include a minimum ORB implementation from Sun. If using such a JDK in conjunction with another ORB it is necessary to tell the JVM which ORB to use. This happens by specifying the org.omg.CORBA.ORBClass and org.omg.CORBA.ORBSingletonClass properties. The ORB Portability classes will ensure that these properties are automatically set when required, i.e., during ORB initialisation. Of course it is still possible to specify these values explicitly (and necessary if not using the ORB initialisation methods). Note: if you do not use the ORB Portability classes for ORB initialisation then it will still be necessary to set these properties. The ORB portability library attempts to detect which ORB is in use, it does this by looking for the ORB implementation class for each ORB it supports. This means that if there are classes for more than one ORB in the classpath the wrong ORB can be detected. Therefore it is best to only have one ORB in your classpath. If it is necessary to have multiple ORBs in the classpath then the property OrbPortabilityEnvironmentBean.orbImplementation must be set to the value specified in the table below.

ORBProperty Value

JacORB v2

com.arjuna.orbportability.internal.orbspecific.jacorb.orb.implementations.jacorb_2_0

JDK miniORB

com.arjuna.orbportability.internal.orbspecific.javaidl.orb.implementations.javaidl_1_4

The JBoss Transaction Service requires specialised code to be instantiated before and after the ORB and the OA are initialised. This code can be provided at runtime through the use of OrbPortabilityEnvironmentBean.orbInitializationProperties This mechanism is also available to programmers who can register arbitrary code which the ORB Portability will guarantee to be instantiated either before or after ORB/OA initialisation. For each application (and each execution of the same application) the programmer can simultaneously provide multiple Java classes which are instantiated before and after the ORB and or OA is initialised. There are few restrictions on the types and numbers of classes which can be passed to an application at execution time. All classes which are to be instantiated must have a public default constructor, i.e., a constructor which takes no parameters. The classes can have any name. The property names used must follow the format specified below:

Pre and post initialisation can be arbitrarily combined, for example:

java –DorbPortabilityEnvironmentBean.orbInitializationProperties=”com..orbportability.orb.PreInit=org.foo.AllORBPreInit com..orbportability.orb.MyORB.PostInit=org.foo.MyOrbPostInit com..orbportability.oa.PostInit=orb.foo.AllOAPostInit” org.foo.MyMainClass

Locating and binding to distributed objects within CORBA can be ORB specific. For example, many ORBs provide implementations of the naming service, whereas some others may rely upon proprietary mechanisms. Having to deal with the many possible ways of binding to objects can be a difficult task, especially if portable applications are to be constructed. ORB Portability provides the Services class in order to provide a more manageable, and portable binding mechanism. The implementation of this class takes care of any ORB specific locations mechanisms, and provides a single interface to a range of different object location implementations.

Example 2.5.  Services.java 

 public class Services {

    /**

     * The various means used to locate a service.

     */


    public static final int RESOLVE_INITIAL_REFERENCES = 0;

    public static final int NAME_SERVICE = 1;

    public static final int CONFIGURATION_FILE = 2;

    public static final int FILE = 3;

    public static final int NAMED_CONNECT = 4;

    public static final int BIND_CONNECT = 5;


    public static org.omg.CORBA.Object getService(

            String serviceName, Object[] params,

            int mechanism) throws InvalidName,

            CannotProceed, NotFound, IOException;


    public static org.omg.CORBA.Object getService(

            String serviceName, Object[] params)

            throws InvalidName, CannotProceed, NotFound,

            IOException;


    public static void registerService(

            org.omg.CORBA.Object objRef,

            String serviceName, Object[] params,

            int mechanism) throws InvalidName, IOException,

            CannotProceed, NotFound;


    public static void registerService(

            org.omg.CORBA.Object objRef,

            String serviceName, Object[] params)

            throws InvalidName, IOException, CannotProceed,

            NotFound;

} 

There are currently several different object location and binding mechanisms supported by Services (not all of which are supported by all ORBs, in which case a suitable exception will be thrown):

  1. RESOLVE_INITIAL_REFERENCES : if the ORB supported resolve_initial_references, then Services will attempt to use this to locate the object.

  2. NAME_SERVICE : Services will contact the name service for the object. The name service will be located using resolve_initial_references .

  3. CONFIGURATION_FILE : as described in the Using the OTS Manual, the JBoss Transaction Service supports an initial reference file where references for specific services and objects can be stored and used at runtime. The file, CosServices.cfg, consists of two columns: the service name (in the case of the OTS server TransactionService) and the IOR, separated by a single space. CosServices.cfg is located at runtime by the OrbPortabilityEnvironmentBean properties initialReferencesRoot (a directory, defaulting to the current working directory) and initialReferencesFile (a name relative to the directory,'CosServices.cfg' by default).

  4. FILE : object IORs can be read from, and written to, application specific files. The service name is used as the file name.

  5. NAMED_CONNECT : some ORBs support proprietary location and binding mechanisms.

  6. BIND_CONNECT : some ORBs support the bind operation for locating services.

We shall now describe the various methods supported by the Services class:

  • getService : given the name of the object or service to be located (serviceName), and the type of mechanism to be used (mechanism), the programmer must also supply location mechanism specific parameters in the form of params. If the name service is being used, then params[0] should be the String kind field.

  • getService : the second form of this method does not require a location mechanism to be supplied, and will use an ORB specific default. The default for each ORB is shown in Table 2.

  • registerService : given the object to be registered, the name it should be registered with, and the mechanism to use to register it, the application programmer must specify location mechanism specific parameters in the form of params. If the name service is being used, then params[0] should be the String kind field.

The following table summarises the different location mechanisms that ORB Portability supports for each ORB via the Services class:

Location MechanismORB

CONFIGURATION_FILE

All available ORBs

FILE

All available ORBs

BIND_CONNECT

None

If a location mechanism isn’t specified then the default is the configuration file.