Frequently Asked Questions about AdironORB

Questions:

• What is AdironORB?
• What is new in AdironORB?
• What features in OpenORB has been changed in AdironORB?
• How do I download AdironORB?
• How do I build AdironORB?
• How do I install AdironORB?
• How do I use AdironORB in my applications?
• How do I switch from OpenORB 1.2 and 1.3 to AdironORB?
• How do I switch from OpenORB 1.4 to AdironORB?
• How do I run OpenORB services using AdironORB?
• How do I check the version of AdironORB?
• Why does AacheORB not support the Extensible Transport Framework (ETF)?

What is AdironORB?

AdironORB is a complete redesign of the Community OpenORB that makes the internals of the ORB more modular and has reorganized the internals and packaging to fit more with the Apache way of doing things.

AdironORB is a compliant implementation of the OMG CORBA/IIOP 2.6(*) specification.

(*) Bidirectional GIOP is supported in interfaces, but it has not been implemented for security reasons. Optional features such as Asynchronous Method Invocations, Real-Time CORBA, and Fault Tolerant CORBA and Common Secure Interoperability (CSIv2) are not yet implemented.

What is new in AdironORB?

• Better separation of internal ORB components.
• Plugable transport and inter-ORB protocols.
• Clean ORB initialization and configuration using the Apache Avalon framework.
• Interception of local invocations without marshalling.
• Flexible thread management at the server side. Many thread models are provided.
• No request polling overhead on the server side (except for the Windows platform).
• About a 20%-30% speed up over OpenORB 1.3.0 (measured with small size requests).
• CORBA 2.6 compliant(*).

More information about the new features of AdironORB is available in the WHATSNEW file.

What features in OpenORB has been changed in AdironORB?

The major differences between AdironORB and the Community OpenORB are the following:

• XML-based ORB configuration is not implemented. The default ORB configuration is based only on the standard arguments and properties, although one may still implement the XML-based approach under the flexible initialization mechanism of AdironORB.
• The OpenORB specific CorbalocService has been removed.
• AdironORB does not support the non-standard fallback mechanism in resolving initial references, which uses the local file system.
• Bidirectional GIOP is supported in interfaces, but it has not been implemented for security reasons. It shall be implemented according to the new Firewall specification.

More information about the features changed in AdironORB is available in the WHATSNEW file.

How do I download AdironORB?

You may download the source distribution of AdironORB from Adiron LLC. The downloaded file contains all of the packages needed for building AdironORB, namely "Tools" and "AdironORB".

How do I build AdironORB?

You need Java 2 SDK, Standard Edition, Version 1.4 (or higher) to build and run AdironORB. You need at least version 1.4.0_03 or 1.4.1_01 to build AdironORB correctly. If you encounter a problem in building the documentation, use the version 1.4.2 instead of previous versions.

After you unpack the downloaded source distribution, you will find two packages in two subdirectories, namely "tools" and "AdironORB". You may build AdironORB by executing either one of the following commands (depending on your platform) at the top-level directory:

    ./build.sh        (on UNIX or Windows with Cygwin)
or
    build             (on Windows)

If you prefer to build each individual package manually, you may change to the subdirectory of each package and execute the above commands.

Optionally you may build the documentation of AdironORB using either one of the following commands:

    ./build.sh doc    (on UNIX or Windows with Cygwin)
or
    build doc         (on Windows)

When the above commands succeed, the AdironORB/doc subdirectory shall contain the documentation of AdironORB. You may find a programming manual in both PDF and HTML formats, as well as the API documentation.

Note: The default build process assumes that the Java Runtime Libraries are located in ${java.home}/lib/rt.jar. If your JDK doesn't use this default path (e.g., OS/X), then you must specify the jdk-runtime-library property in the tools/global.properties file.

How do I install AdironORB?

Before you install AdironORB, modify the install.path property in the tools/global.properties file to point to the directory in which you want to install AdironORB, e.g., /opt/AdironORB-1.0 on UNIX or C:\\opt\\AdironORB-1.0 on Windows. You have to escape the '\' character in a properties file.

You may install AdironORB by executing either one of the following commands (depending on your platform) at the top-level directory:

    ./build.sh install      (on UNIX or Windows with Cygwin)
or
    build install           (on Windows)

The above commands install files from both the "Tools" and "AdironORB" packages. After the installation, you will find the following JAR files in the lib and lib/endorsed subdirectories inside the install path.

• adironorb-omg-X.Y.Z.jar: the CORBA classes defined by OMG.
• adironorb-orb-X.Y.Z.jar: the ORB implementation.
• adironorb-compiler-X.Y.Z.jar: the IDL compiler.
• adironorb-tools-X.Y.Z.jar: the runtime tools used for the ORB and IDL compiler.
• avalon-framework.jar: the Apache Avalon framework.
• logkit.jar: the Apache LogKit library.

The X.Y.Z in the above filenames refers to the version number of AdironORB. You have to add the above JAR files to your class path for using AdironORB.

You may optionally put the adironorb-omg-X.Y.Z.jar file in the lib/endorsed directory of your Java runtime to override the CORBA classes provided by your Java runtime. See the "Endorsed Standard Override Mechanism" for details.

How do I use AdironORB in my applications?

To use AdironORB in your application programs, you have to set the following two properties:

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

You may pass the above properties to the ORB.init method, set they as system properties, or put them in a file named orb.properties in your home directory or the lib subdirectory of your Java runtime. The java.home system property in a Java runtime identifies the Java runtime's installation directory.

You may find more information about using and configuring AdironORB in the AdironORB Manual, which can be found in the AdironORB installation if you choose to build the documentation before you install AdironORB.

How do I switch from OpenORB 1.2 and 1.3 to AdironORB?

Many package names and JAR files were renamed since the OpenORB 1.2 and 1.3 releases. Here is a summary of the renaming using OpenORB 1.3 as an example. OpenORB 1.2 also has a similar mapping.

How do I switch from OpenORB 1.4 to AdironORB?

Many package names and JAR files were renamed from OpenORB 1.4. Here is a summary of the renaming.

How do I run OpenORB services using AdironORB?

You may use AdironORB to run OpenORB 1.4 services as long as these services do not reference to OpenORB specific classes. For example, you may run the Event Service, Concurrent Control Service, Time Service, and the Transient Naming Service using AdironORB.

For other services that use OpenORB specific classes, we need some modification. Typically, these services retrieve their configuration information using the ORBLoader interface. In other words, they call orb.getLoader() and query properties from the ORBLoader. We can restrict the use of ORBLoader use the following approach.

1. We let the Service class of each service convert the properties in the ORBLoader into an Avalon Parameters object and pass this Parameters object to service implementation to replace the ORBLoader used in the service implementation.
2. If a service uses Portable Interceptor ORB Initializers, we make the ORB Initializer do the same thing.

Using the above approach, the classes that implement a common object service will not rely on the ORBLoader interface, but the Avalon interfaces. The only places that are OpenORB specific are the Service class and the ORB Initializer, which can be replaced easily for AdironORB.

One issue of using the above approach is that the property names used in the ORBLoader interface are not case sensitive, but the Parameters interface uses case sensitive names. This issue shall be taken care of when you specify the XML configuration of OpenORB services.

The Persistent State Service (PSS) is a service that is difficult to modify. It uses the following methods that are OpenORB specific. Using Java reflection may help.

    org.openorb.orb.core.typecode.TypeCodeBase._base_type()
    org.openorb.orb.core.ORBSingleton.oa.get_listener()

Besides, PSS also uses the following classes that are OpenORB specific. In order to fix a memory leak, PSS was modified such that it retrieves the StorageBuffer from the ORB. This change makes PSS unable to run on other ORB. In summary, PSS also uses the following classes from the OpenORB module. Further investigation is needed.

    org.openorb.orb.iiop.CDROutputStream
    org.openorb.orb.io.StorageBuffer

How do I check the version of AdironORB?

You may check the version and release information of AdironORB using the following command.

    java -jar <path>/lib/adironorb-orb-X.Y.Z.jar

Why does AacheORB not support the Extensible Transport Framework (ETF)?

The major goal of the ETF specification is to separate the message layer and the transport layer of an ORB such that various transport protocols may be plugged into the ORB in a easy way. While the ETF specification focuses on the needs of real-time and efficiency, its design has many disadvantages from our point of view.

First of all, the ETF specification is GIOP specific. It assumes the message layer is GIOP. Although all ORBs use GIOP, but the message layer can be modeled as generic as a request based client/server model which other protocols such as RMI and SOAP can fit in.

Secondly, the functionality of some interfaces in the ETF specification is overloaded. For example, the Connection interface deals with both connection handling and data reading/writing. Similarly, the Listener interface handles both listening and connection management.

Thirdly, the ETF specification assumes a simplistic message layer. Issues like location forward, rebind, reconnect, client policy, policy change, etc. are not mentioned. It is unclear whether the proposed transport model can support a complex message layer or not.

In contrast, the AdironORB model provides a better way for defining the pluggable transport layer. In our design, the transport layer deals with connection handling, listening, data reading/writing, and IOR Profiles creation. The message layer uses the abstraction of channels as the basic communication units over the transport layer. Channels can live over reconnecting in the transport layer. We use channel managers to handle connection management. The issues of location forward, rebind, and client policy are handled in the Delegate/Binding layer.

In general, the design of the message layer and transport layer in AdironORB clean and elegant, comparing to the ETF specification. It is easy to implementing ETF as a GIOP specific message transport on top of our framework.