AdironORB Manual

This document provides information required to use AdironORB. It describes how to install, configure and use AdironORB. It also explains how to use the IDL compiler.

For any comments or questions about this documentation and AdironORB, please send email to the SL3 Users mailing list <sl3-users@adiron.com>. You may subscribe to this list at http://greene.case.syr.edu/mailman/listinfo/sl3-users.

This document is the first version of the AdironORB User Guide. It has grown out of the original OpenORB documentation. Also, much of the information regarding the history of OpenORB was originally on the Community OpenORB website. It will be completed step by step. Contributions would be greatly appreciated.

AdironORB is a CORBA Object Request Broker (ORB) developed in Java. It complies with the CORBA/IIOP 2.6^[1] specification and provides many features and flexible ways for extensions.

AdironORB has been designed to provide a reliable foundation for distributed applications. It combines all CORBA features with implementation specific extensions, with the aim of being the most powerful and complete CORBA implementation in Java.

CORBA technology is becoming increasingly complex, and its feature set is growing. Many users don't require all features to be present in every ORB deployment. AdironORB is the most complete CORBA implementation but not the biggest! Why? Because AdironORB can be configured to fit only the user's requirements. AdironORB is not monolithic middleware, it is a truly modular ORB.

That means that users can define what mechanisms are needed by their applications, so that AdironORB will be loaded with only those mechanisms. AdironORB contains a kernel that has the ability to load only required parts during bootstrap time.

Thus, AdironORB is the best way to have the best implementation, the most complete solution and the most flexible platform!

The current implementation of AdironORB has the following features:

The AdironORB has evolved from the work of several people. The original code was developed under the JavaORB project by Jerome Daniel. The JavaORB project was started in October 1998. The version 1.0 release was in March 1999, the same month in which Jerome founded the Distributed Object Group (DOG). DOG was a collaboration of Jerome Daniels, Xavier Blanc, Nicolas Charpentier, and Vincent Vallee. For more information of the history of the Distributed Object Group, including a more detailed account of members and contributions, go to their web site at http://dog.team.free.fr.

In June 2000, the DOG became part of the Exolab Group (supported by Intalio, Inc.) and it was around this time that Chris Wood joined the developer team. About a month later Marina Daniel also joined the team. While under the guidance of the Exolab Group, several months of in-house development led to the next release. This new release was now under the name OpenORB. More information about the work on OpenORB done by the Exolab Group (as well as the full list of contributors) can be found at http://www.openorb.org.

By the 4th quarter of 2001, with the end of the dotcom era, Intalio was forced to reconsider thier involvement in the OpenORB project. At this time, a movement was started by several of the community members. The idea was to get Intalio to turn the OpenORB project into a real, community driven, open-source project after the example of many Apache projects. Unfortunately, no agreement was reached with Intalio for doing this. As a result on January 8th 2002, the OpenORB project was forked and established at SourceForge as the Community OpenORB. The new project was founded by Stephen McConnell, Michael Rumpf, Shawn Boyce, Jesper Pedersen, J. Scott Evans, and Viacheslav Tararin.

On June 8th, 2002, Intalio announced that they were ending thier support of the OpenORB project in an official capacity. They would still support the developers that forked The Community OpenORB, but could not host the project on Exolab.

The Community OpenORB project has substantially advanced the source base since thier initial inception and in September 2002 released verion 1.3.0 to the community. The Community OpenORB is still a very active project and there is sure to be substantially more information about the current status of the project at http://openorb.sf.net.

In March of 2002, Polar Humenn (of Syracuse University) was looking for an open-source ORB to use as a base for a project. It was decided that OpenORB was the best choice for the needs of the project, but it would be quite difficult to change the transport mechanism that the ORB used. Getting in touch with the Community OpenORB people, Polar found out that Michael Rumpf was working on redesigning the internals of the ORB for the 2.0 release. Among the goals of both Michael and Polar were: separation of the messaging layer from the transport layer, separation of both messaging and transport from the socket/network layer, and restructuring the internal ORB code to use the Apache Avalon Framework.

This release of the Community OpenORB has been renamed AdironORB, as it in the process of transitioning itself as one of the many fine projects at Adiron LLC. AdironORB, version 1.0, represents the work done at Syracuse University by Polar Humenn, Joncheng Kuo, and David Grandinetti over the past year. We would like to thank the entire group of developers from the Community OpenORB for their support and help during this time, as well as everyone who has helped get the project to where it is now.

One of the approaches in achieving a more modular ORB is to provide a layered architecture. The block diagram shown in this section illustrates the major layers of the AdironORB. The client-side of the ORB sits at the left half of the diagram; the server-side sits at the right half. We will brief the layers in this diagram from top to bottom, left to right.

At the top, the configuration layer is in charge of ORB configuration and initialization. We use the Apache Avalon Framework to configure and initialize ORB instances.

The ORB core layer provides the essential functionality of an ORB. It implements the ORB, ORB singleton, object stub, type code, DII, DSI, and Dynamic Any.

The binding layer is used for the client-side ORB only. It implements CORBA Delegate and provides associations between Delegates and client channels. These associations are called object reference bindings.

The adapter layer is used for the server-side ORB only. It handles the registration and look up of object adapters. AdironORB implements the Portable Object Adapter (POA) as the default object adapter.

The interceptor layer handles the interception of object requests and IOR creation. This layer protrudes into other layers such as the binding layer, adapter layer, message layer, and transport layer to provide request and IOR interception. For example, when object requests are created, if request interceptors are used, object requests will be wrapped with intercept requests that handles the interaction with interceptor managers.

The client management layer manages client channels and active client requests.

The message layer deals with the protocols used for inter-ORB communications. It uses the abstraction of channels and requests. A channel represents a communication link between a client ORB and a server ORB. A channel is called a client channel at the client side and a server channel at the server side. Requests are the atomic communication units over channels. Requests are used to carry CORBA requests for inter-ORB protocol communications. The message layer is pluggable in the sense that all inter-ORB protocols have to be registered to the ORB. Users may register their own protocols. The default inter-ORB protocol supported by AdironORB is Internet Inter-ORB Protocol (IIOP), which uses the GIOP protocol engine and TCP/IP transport.

The server management layer manages the resources and activities on a server-side ORB, including managing server channels and dispatching requests. The server management layer also provides management for threads and protocol acceptors.

The transport layer handles network communications, including making/accepting connections and sending/receiving data, using the abstraction of sockets provided by the Java API. The transport layer is pluggable in the sense that you can plug in a module for a specific transport protocol when an inter-ORB protocol is plugged in.

AdironORB uses the Apache Avalon Framework for ORB initialization and configuration. The ORB class implements the Avalon lifecycle interfaces. You may instantiate a new ORB and configure the ORB using these lifecycle interfaces. Or you may use the standard ORB.init operation to create a new ORB. When you use the ORB.init operation to create a new ORB, AdironORB internally uses an ORB Loader, which configures and initializes the new ORB instance using the Avalon lifecycle interfaces.

One of the pluggable parts of the AdironORB architecture is exemplified by the pluggable threading models on the server side of the ORB. When a server enabled ORB is started, there is a thread manager object declared in the parameters. This thread manager object must implement the com.adiron.orb.srvmgt.ThreadManager interface. There are five Thread Manager objects provided with the AdironORB distribution. It would be easy to implement another and use it at runtime.

Here are the five available thread manager classes: (with prefix "com.adiron.orb.srvmgt.thread." omitted)

You must have Java 2 SDK, Standard Edition, Version 1.4 (or higher) to build AdironORB. After you install your JDK on your system, you have to set the JAVA_HOME environment variable to your JDK installation (e.g., /usr/local/j2sdk1.4.1 on Unix or C:\j2sdk1.4.1 on Windows.

The AdironORB project has many packages, including the Tools package, the AdironORB package, and Common Object Services packages. Each package is provided in two formats: a gzipped tar file or a zip file. You may download these packages from the AdironORB web site.

For building the AdironORB, you have to download the source distribution of both the Tools and AdironORB packages. For example, if you choose to download the gzipped tar files, you need the following two files: Tools-src-X.Y.Z.tgz and AdironORB-src-X.Y.Z.tgz where X.Y.Z is the AdironORB version number.

After you download these packages, you have to unpack them to the same directory. Each package will be in its own subdirectory.

In some cases, you may download a big tar file that contains all of the AdironORB packages. This file is named like AdironORB-all-src-X.Y.Z.tgz.

The source distribution of each package has a build script that uses the Apache Ant build tool. This tool is included in the source distribution of the Tools package. Thus, you do not have to install Ant. If you use OS/X, you have to edit the global.properties file in the Tools package to set your Java runtime.

To build a package, you have to invoke the build script corresponding to your operating system in each package: build.sh for Unix or build.bat for Windows. If you have Cygwin installed on Windows, you may follow the instructions for Unix.

Although building the AdironORB package requires building the Tools package first, for your convenience, when you invoke the build script of the AdironORB package without specifying a target, the build script will first build the Tools package by default. Thus, you are not required to invoke the build script of the Tools package manually.

For example, if you are on a Unix machine or a Windows machine with Cygwin installed, you may execute the following commands to build AdironORB:

    cd AdironORB
    ./build.sh

If you are on a Windows machine without CygWin, you may use the following commands instead:

    cd AdironORB
    build

If you download the AdironORB as a big tar file that contains all of the AdironORB packages, you may run ./build.sh (on Unix) or build.bat (on Windows) from the top level directory to build every package.

    ./build.sh        (on Unix/Cygwin)
or
    build             (on Windows)

After building the AdironORB, you will find the generated jar files in the lib subdirectory of a package. The name of these jar files are prefixed with "adironorb" and postfixed with the version number of AdironORB.

You may also invoke the build script with a target specified. The build script provides many targets such as jar-all, test, doc, install, etc. You may invoke the build script with the help argument to see a list of supported targets.

    ./build.sh doc        (on Unix/Cygwin)
or
    build doc             (on Windows)

Before you can install AdironORB, you have to edit the global.properties file in the Tools package to set the install.path property. The value of this property must specify the directory you would like AdironORB to be installed in. For example, you may set

    install.path=/opt/AdironORB-1.0.0         on Unix
or
    install.path=C:\\opt\\AdironORB-1.0.0     on Windows.

Note that you need a double backslash '\\' for each single backslash '\' on Windows.

After modifying the global.properties file, you may invoke the build script again with the install target for installing AdironORB.

    ./build.sh install    (on Unix/Cygwin)
or
    build install         (on Windows)

The build script will install all of the necessary files to the directory specified by the install.path property. These files include:

Here is a simple summary of each jar file produced from compiling the AdironORB source code. This may be helpful to those who want to deploy and AdironORB application without distributing the full AdironORB distribution. The AdironORB jar files consist of:

The first three jar files, adironorb-omg-X.Y.Z.jar, adironorb-orb-X.Y.Z.jar, and adironorb-tools-X.Y.Z.jar, must be placed in your class path for running CORBA applications. The first and second jar files contain the core of AdironORB and CORBA runtime, including all the client and server side code. The third jar file conatains small utility classes that almost all AdironORB modules take advantage of.

The last jar file, adironorb-compiler-X-X-X.jar, must be installed for building CORBA applications. It is dependent on the adironorb-tools-X.Y.Z.jar file, which must be installed in the same class path as the compiler jar file.

In addition to the above AdironORB jar files, there are several support jar files that must be in the classpath as well. These jar files are included in the AdironORB installation as well.

For information on how to add jar files to the class path, please see your JDK documentation.

You may use AdironORB in two ways: The first way is to use AdironORB in a standard CORBA application; the second way is to use AdironORB as an Avalon component. When you run a standard CORBA application, the ORB.init operation will be used to create a new ORB. You have to configure certain properties such that the AdironORB's ORB implementation will be used. If you use the AdironORB as an Avalon component, you may instantiate a new ORB instance and configure the ORB using the Avalon lifecycle interfaces.

    org.omg.CORBA.ORBClass=com.adiron.orb.core.ORB
    org.omg.CORBA.ORBSingletonClass=com.adiron.orb.core.ORBSingleton

    java -Dorg.omg.CORBA.ORBClass=com.adiron.orb.core.ORB \
    -Dorg.omg.CORBA.ORBSingletonClass=com.adiron.orb.core.ORBSingleton \
    -jar MyApplication.jar

    java.util.Properties properties = new java.util.Properties();

    properties.setProperty( "org.omg.CORBA.ORBClass", 
        "com.adiron.orb.core.ORB" );
    properties.setProperty( "org.omg.CORBA.ORBSingletonClass", 
        "com.adiron.orb.core.ORBSingleton" );
     
    org.omg.CORBA.ORB orb =
        org.omg.CORBA.ORB.init( args, properties );

    // Create an ORB instance. At this point the ORB is not functional.
    com.adiron.orb.core.ORB orb = new com.adiron.orb.core.ORB();

    // Create a logger using the Trace class
    org.apache.avalon.framework.logger.Logger logger =
        com.adiron.orb.util.Trace.createLogger(
            org.apache.log.Priority.ERROR, "server-orb" );

    // Enable the ORB logging
    orb.enableLogging( logger );

    // Create a parent context for the ORB.
    org.apache.avalon.framework.context.DefaultContext context =
        new org.apache.avalon.framework.context.DefaultContext();
    context.makeReadOnly();

    // Contextualize the ORB
    orb.contextualize( context );

    // Create parameters for the ORB
    org.apache.avalon.framework.parameters.Parameters params =
        new org.apache.avalon.framework.parameters.Parameters();

    // Enable this ORB as a server only
    params.setParameter( "com.adiron.orb.client.enable", "false" );
    params.setParameter( "iiop.port", "8080" );
    params.makeReadOnly();

    // Parameterize the ORB
    orb.parameterize( params );

    // Initialize the ORB
    orb.initialize();

    // The ORB is functional now.

AdironORB provides many ways of configuring the ORB. AdironORB delegates the work of loading, configuring, and initializing the ORB to various objects such as the ORB Loader, ORB Configurator, and ORB Initializer. Each of these objects can be replaced by users' customized object.

AdironORB uses the Avalon parameters to describe the configuration of the ORB. In a CORBA application, these parameters are generated from a list of external sources such as the orb.properties files and the arguments and properties supplied to the ORB.init operation.

Before we cover what the specific parameters are, and how they affect the operation of the ORB, it is important to understand the different ways to specify parameters to the ORB. The default ORB Configurator, PropertiesBasedORBConfigurator allows two ways to specify parameters. The first way is to specify parameters as properties in the orb.properties file either in the user's home directory or in the lib subdirectory of the Java runtime. The second way is to pass arguments or properties to the ORB.init operation.

For example, to set the property port in the 'iiop' module to the value '1234' for all orbs on a particular machine, the following line would be added to its orb.properties file:

    iiop.port=1234

To ensure that the server is never initialized in a particular application the orb could be initialized as follows:

    public static void main( String [] args )
    {
        java.util.Properties props = new java.util.Properties();
        props.setProperty( "com.adiron.orb.server.enable", "false" );
        org.omg.CORBA.ORB orb = org.omg.CORBA.ORB( args, props );
        // ...
    }

To add a third party portable interceptor, distributed with the ORB Initializer named org.example.corba.Initializer, an application can set up properties to the ORB.init operation as follows:

    public static void main( String [] args )
    {
        java.util.Properties props = new java.util.Properties();
        props.setProperty( "org.omg.PortableInterceptor.ORBInitializerClass.org.example.Initializer", "" );
        org.omg.CORBA.ORB orb = org.omg.CORBA.ORB( args, props );
        // ...
    }

An alternative way for users to insert a portable interceptor at runtime is to pass the system properties to the ORB.init operation as follows:

    public static void main( String [] args )
    {
        org.omg.CORBA.ORB orb =
            org.omg.CORBA.ORB( args, System.getProperties() );
        // ...
    }

In this way, users wanting to use the above portable interceptor can start the application using the -D java argument to define a system property:

    java -Dorg.omg.PortableInterceptor.ORBInitializerClass.org.example.Initializer \
         app-name

Here is a list of the parameters that the default ORB Initializer and various parts of the ORB understand:

AdironORB provides two ways to access some of the internals of the ORB. Firstly, the application code may use the proprietary operations added to the implementation classes of the standard interfaces. Secondly, Portable Interceptor ORB Initializers may use the Avalon Contextualizable and Parameterizable interfaces to access more of the ORB internals.

public class MyORBInitializer
    extends    org.omg.CORBA.LocalObject
    implements org.omg.PortableInterceptor.ORBInitializer,
               org.apache.avalon.framework.context.Contextualizable
{
    public void contextualize(
        org.apache.avalon.framework.context.Context context
    )
        throws org.apache.avalon.framework.context.ContextException
    {
        // The ORB reference is always available
        com.adiron.orb.core.ORB orb =
            ( com.adiron.orb.core.ORB )
                context.get( "ORB" );

        // Try to get the Server Manager of the ORB
        com.adiron.orb.server.ServerManager serverManager = null;
        try
        {
            serverManager =
                ( com.adiron.orb.server.ServerManager )
                    context.get( "ServerManager" );
        }
        catch( org.apache.avalon.framework.context.ContextException ex )
        {
            // fall through
        }

        if ( serverManager == null )
        {
            // The server-side of the ORB is disabled.
        }
    }
    // ...
}

The CORBA framework provides a location-transparent way for applications, but it is sometimes necessary to have the knowledge about the underlying network and transport that are used to carry out object invocations. For example, in the needs of security, it is desireable to have the underlying knowledge of the transport such as the IP, port number, authenticated X.509 certificate chain, etc. AdironORB provides two way to retrieve this information: one is for the client side and the other is for the server side.

    org.omg.CORBA.portable.ObjectImpl objImpl =
        ( org.omg.CORBA.portable.ObjectImpl ) obj;

    com.adiron.orb.request.Delegate objDelegate =
        ( com.adiron.orb.request.Delegate )
            objImpl._get_delegate();

    com.adiron.orb.request.ObjRefBinding binding =
        objDelegate.getSelectedBinding();

    // If the binding is null, this object reference is probably
    // not connected to the target.
    if ( binding == null )
    {
        // Try to make an invocation.
        obj._non_existent();
        binding = objDelegate.getSelectedBinding();
        if ( binding == null )
        {
            throw new RuntimeException( "Delegate does not have a binding" );
        }
    }

    com.adiron.orb.client.ClientChannelInfo channelInfo =
        binding.getClientChannelInfo();

    // If channelInfo is null, it is a local binding.
    if ( channelInfo != null )
    {
        com.adiron.orb.transport.TransportInfo transportInfo =
            channelInfo.getTransportInfo();

        // If transportInfo is null, it is closed or not connected.
        if ( transportInfo != null )
        {
            System.out.println( transportInfo.describe() );
        }
    }

    com.adiron.orb.core.ORB apacheORB = ( com.adiron.orb.core.ORB ) orb;

    com.adiron.orb.server.ServerChannelCurrent serverChannelCurrent =
        ( com.adiron.orb.server.ServerChannelCurrent )
            apacheORB.getPublicContextObject( "ServerChannelCurrent" );

    com.adiron.orb.server.ServerChannelInfo channelInfo =
        serverChannelCurrent.getServerChannelInfo();

    // If channelInfo is null, it is a local call.
    if (channelInfo != null)
    {
        com.adiron.orb.transport.TransportInfo transportInfo =
            channelInfo.getTransportInfo();
        System.out.println( transportInfo.describe() );
    }

The CORBA specification does not provide a standard way for application code to communicate with Portable Interceptors. AdironORB provides an extension to its Delegate implementation to associate information objects with a Delegate. These information objects are added to a Delegate in the per-thread bases. That is, objects added by a thread can be retrieved or removed only by the same thread.

The com.adiron.orb.request.Delegate class defines three methods for this purpose:

There are two policies specific to the AdironORB that will affect the runtime behavior of the ORB.

The interaction between the two policies is quite simple. The ForceMarshal policy will always override the InterceptLocal policy.