The Community OpenORB

OpenORB is a CORBA Object Request Broker fully developed in Java. It fully complies with the CORBA 2.4.2 specification and provides many features, services and extensions.

OpenORB 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.

OpenORB is the successor of JavaORB which is already widely used all over the world: in Europe, America, China, Australia, and other places. A large number of deployed applications, research projects, and study projects are using JavaORB. Building on their experience with JavaORB, the OpenORB team has defined a complete new architecture to ensure that OpenORB is the best solution for applications needing high scalability and high performance.

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. OpenORB is the most complete CORBA implementation but not the biggest! Why? Because OpenORB can be configured to fit only the user's requirements. OpenORB 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 OpenORB will be loaded with only those mechanisms. OpenORB contains a kernel that has the ability to load only required parts during bootstrap time.

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

The current implementation of OpenORB has the following features:

To develop OpenORB, we user feedback into account. From the user's point of view, CORBA is usually too complex to configure, and the applications developed with CORBA are too complex to deploy and to maintain. From the project manager's point of view, CORBA provides too heavy a platform for the real needs; does not include a way to plug in specific IT requirements; and is usually too expensive.

The OpenORB kernel is responsible for starting the ORB and applying the current configuration. That means:

The kernel is itself divided into 2 parts:

The following picture provides an overview of the kernel architecture:

The Kernel API can be used by the other parts OpenORB. It gives access to all the other parts of the ORB (through a repository of loaded parts) and gives access to the configuration file.

The OpenORB jar files contain a configuration file. This configuration file, named OpenORB.xml provides all default features to use OpenORB. If you browse the content of the OpenORB jar file, you will find OpenORB.xml in the org/openorb/config subdirectory.

This configuration file imports another configuration file named default.xml. This file contains descriptions and reasonable default for all properties used to manage the OpenORB behavior.

When an OpenORB user develops an application or deploys on a certain site, it may be necessary to customize OpenORB.xml in order to specify some property values. After customization, the configuration file can be included in the OpenORB jar file. This allows simplified deployment for the CORBA applications.

A following chapter explains more in depth how to use and to customize the OpenORB behavior through the configuration files. The OpenORB.xml file gives several examples for configuration.

The default.xml file is also available in the org/openorb/config subdirectory. This file is the definitive reference on which items can be configured. It describes all available configuration items and sets sensible defaults for them. This file should be used as documentation for the configurable items.

If you are using OpenORB for the first time, we advise you to stop your reading at this point. Try out OpenORB by starting examples and developing some test applications. Come back to this point to continue your reading and to understand more in details about OpenORB configuration.

This chapter describes the configuration mechanism of OpenORB, it explains how configuration works, not what is configured.

OpenORB is configured through a set of XML documents. These documents have their form described in a DTD, which is contained in the OpenORB jar file in the location org/openorb/config/OpenORB.dtd.

The configuration file loaded first by OpenORB is known as the master configuration file. This master file may reference other configuration files, which may in turn reference other configuration files. This feature allows fast installation of extensions to OpenORB, and the ability to centrally define an OpenORB configuration across an organization. The master configuration file can be stored in a range of locations. The configuration file used is the first one found in the following list:

The last of these locations deserves further explanation. The usual setting of the OpenORB property openorb.home is within the OpenORB jar file. As this property is usually left as the default, the file named org/openorb/config/OpenORB.xml acts as a default master configuration file for OpenORB. So if you don't copy the OpenORB.xml file to the user.dir, user.home or java.home directories, OpenORB will use the embedded configuration file.

This system is very powerful because OpenORB is able to directly embed its own configuration. If you need to customize OpenORB, you have to edit the OpenORB.xml file to apply your changes and place it in one of the locations mentioned above. The OpenORB.xml file is available in the src/config directory of the OpenORB source code and in the config directory for the prebuilt OpenORB versions.

After customization of the OpenORB.xml file, it's possible to replace the embedded OpenORB.xml file with the new one. It means that your configuration will be directly in the OpenORB jar file. This is very convenient and useful if you need to deploy an application that uses OpenORB, since all specific requirements for the OpenORB configuration will be located in the OpenORB jar. So, you will not waste time configuring OpenORB on each machine where your application is deployed.

To replace the embedded configuration by the new one, use the following procedure:

The embedded configuration file distributed with OpenORB references the default.xml file found in the config subdirectory of openorb.home for most of its settings, so OpenORB uses the default configuration when it is first installed.

The OpenORB root element. Setting the doctype for an OpenORB configuration file is optional, however some users may prefer to add it when developing a configuration, as it allows validation of the document. When the doctype is used it can be set as follows:

<!DOCTYPE OpenORB
PUBLIC "-//openorb.sf.net//OpenORB Config//EN"
"http://openorb.sf.net/config/OpenORB.dtd">

The non-public identifier will never be used by the OpenORB configuration mechanism, so can be set to any URL that the user has installed the DTD for their own validation. The URL shown above will also be valid.

The OpenORB XML file's root element is named 'OpenORB'. The root element should contain two namespace definitions which are used in the OpenORB configuration file:

<OpenORB xmlns="http://openorb.sf.net/config"
xmlns:xlink="http://www.w3.org/1999/xlink" >

The root OpenORB element may contain an optional default profile attribute. This declares which profile is used by default if the file is selected as the master configuration file. Profiles are explained in detail below.

The OpenORB element may also define a base URL for resolving relative URLs used in import statements which are also defined below.

Each individual subsystem of OpenORB, for example the IIOP subsystem or the POA, is controlled by a module defined in a configuration file as an immediate child element of the 'OpenORB' root element. Modules are usually defined only in configuration files which are contained in a jar file. All of the modules affecting the OpenORB core are defined in the default.xml file.

Modules have the following responsibilities:

A property is a name, value pair used in configuring the orb. In the config file the values of properties are always simple strings, however each property usually has an accepted range of legal values which is documented in the module which defines it. When a module defines a property it also defines a default value for it, which is used in the absence of any overrides. Here is a typical property definition:

<module name="one" >
<property name="name" value="value"/>
</module>

Each module defines a namespace for its property definitions, so if a property is defined in two differently named modules with the same name, then these are distinct properties. Each defined property has an expanded name, which is found by concatenating its defining module, a '.', and the property name. For example the above module would define a property with expanded name one.name. If two modules contained in different files are given the same name then the expanded names of their properties may collide. For this reason it's important to ensure module names are unique. Module and property names are not case sensitive.

A module may also declare property sets, which are sets of related properties. All the properties in a property set have names which are prefixed with the same value. Here is a typical property set definition, with a few properties defined in it:

<propertyset prefix="pfx" />
<property name="pfx.a" value="value1"/>
<property name="pfx.b" value="value2"/>

Note that the propertyset element is a sibling of the property definitions, and not a parent, so there is no </propertyset> tag. Some very commonly used properties are given a special alias which can be used on the command line as a shortcut. These are defined in the module as follows:

<propalias name="prop" value="Alias"/>

For details of command line setting of properties, see the section below.

A module may define an initializer, this names a class which is loaded by the orb runtime when the orb is created and is used to initialize the module's subsystem. The initializer class must implement one or both of the portable interceptor ORB initializer interface, org.omg.PortableInterceptor.ORBInitializer, and the OpenORB feature initializer interface, org.openorb.PI.FeatureInitializer. An example of a module with an initializer is the POA module:

<module name="POA" initializer="org.openorb.adapter.poa.POAInitializer" />

Here is a typical module definition for a module which defines some properties and an initializer:

<module name="foo" initializer="org.myorg.foo.FooInitializer">
<property name="size" value="5"/>
<property name="length" value="10"/>
<propertyset prefix="color" />
<property name="color.white" value="1"/>
</module>

Some subsystems require other subsystems be loaded in order that they can be used. This is a dependency. Modules declare their dependencies by using import statements, which are described in the following section.

It is common for a subsystem to require another subsystem be loaded and modified in some way. This is achieved by using import elements. Import elements are defined as children of the module which defines them. They declare the target module for the dependency, and optionally a set of overrides for the module's properties. Here is an example import statement which could be used in a different module defined in the same configuration file as the foo module defined above. It loads the foo module defined and overrides the setting of some of the properties:

<import module="foo" >
<property name="length" value="11"/>
<property name="color.white" value="0"/>
<property name="color.black" value="1"/>
</import>

Each module is only ever visited once during configuration. This allows a module to be imported as a dependency of multiple other modules without the property overrides being reset to their default values: If the above import statement were to be run, and then another import of foo occurred in a different location which overrode different properties, then the properties overridden in the above import would remain overridden. However, if the later import overrode some of the same properties as the above import, these properties would be changed.

Imports may also target modules in external files. Typically this is done with modules which are defined in well known, permanent locations, for example the modules defined in the default.xml file. This file is in a well known location: the config subdirectory of the openorb.home directory. The import attribute used to declare imports from an external file is the xlink:href attribute.

The following statement imports the module named 'mod' from the config file obtained from the given URL.

<import xlink:href="http://www.example.com/orb/cfg.xml#mod" />

The target of an href attribute does not have to be an absolute URL, it may be defined relative to the document's base URL. The base URL for the document will either be a href to the document itself, or whatever is set by the xml:base attribute of the root 'OpenORB' element. For example:

<import xlink:href="#mod" />
<import xlink:href="../cfg.xml#mod" />

In addition to the URL protocols normally defined by Java, OpenORB defines an extra URL protocol, the resource protocol. The resource protocol attempts to load its target by using the Java getSystemResource function, allowing things to be loaded off the classpath. For example the following URL would import the 'mod' module from the default config file contained in the openorb jar:

<import xlink:href="resource:/org/openorb/config/default.xml#iiop"/>

An alternative version of the resource protocol uses the getResource function on the Class object named org.openorb.ReleaseInfo to generate the URL for the target. This uses the Class's class loader to load the resource. The following two resource URLs point to the same file as the above URL: (note: these lines have been split to allow them to be typeset, this should not occur in the XML file)

<import xlink:href="resource://org.openorb.ReleaseInfo/config/default.xml#mod" />
<import xlink:href="resource://org.openorb.ReleaseInfo//org/openorb/config/default.xml#mod" />

The references used in import statements are subject to property expansion, any part of the reference enclosed in ${...} is attempted to be expanded. The expanded names of properties from modules which have been defined previously to the import statement will be used first for this property expansion, and if this fails then the expansion will be attempted from Java system properties. In the following example the ${user.name} part of the reference is expanded using the Java system property, which is equal to the name of the current user:

<import xlink:href="http://www.example.org/openorb/${user.name}.xml" />

If the property expansion appears at the beginning of the URL and it expands to a property which can be parsed as a URL, then the property's URL is used as a base URL for resolving the argument. If this fails, but the property can be parsed as a file then the file is converted to a URL and again used as the base URL. For example, in the following import statement ${openorb.home} gets expanded into the URL property setting of openorb.home, which is generally "resource:/org/openorb/", and the remainder of the href is resolved relative to it:

<import xlink:href="${openorb.home}config/default.xml#boa" />

The final method of importing properties is from a Java properties file. Property file imports have two forms, the first defines the module that the properties in the file override in the URL's fragment. For example, the following import statement would set the properties defined in InitRef.properties in the user's home directory:

<import xlink:href="${user.home}InitRef.properties#InitRef" />

The second form of property import does not use fragment identifiers, but assumes that the properties defined in the file use expanded property names. This style of import cannot define property overrides as sub elements, as there is no module to define the properties within. For example:

<import xlink:href="${user.home}extra.properties" />

Profiles are a useful way of grouping related modules together. Whenever an ORB application is loaded a profile is used to collect the required orb subsystems.

Profiles are very useful to define several ORB configurations and to select the configuration to use when starting an application. For example, if you download OpenORB services or extensions, a profile is very useful to collect specific OpenORB services configuration parameters. For example, you could define a transactional profile when using applications with transactions, or a database profile for use with the persistent state service.

Profiles act like modules that contain only import statements; They may override properties defined in modules that they import, but they do not define a namespace for properties, and so do not have 'property', 'propertyset', or 'propalias' child elements. Profiles also cannot define initalizers as they don't correspond to an orb subsystem.

Here is an example profile:

<profile name="large">
<import module="chips"/>
<import module="sauce">
<property name="flavor" value="tabasco"/>
</import>
</profile>

Profiles may be imported both from other profiles and from modules in a similar way to which modules are imported. However when importing a profile it is not possible to set property overrides since the profile does not define a namespace for properties. For example:

<import profile="large"/>

Each OpenORB config file specifies a special default profile. To import this profile the import statement does not define a fragment in the URL, for example:

<import xlink:href="${openorb.home}config/OpenORB.xml" />

The profile used as the default profile is the first one found by the following algorithm:

The associations section is used to associate users with profiles. This section optionally appears as the first child of the OpenORB root element.

The following example config file would select "joes-profile" if the user was joe, "flintstones" if the user was fred, barney or pebbles, or or "unknown-user" otherwise:

<OpenORB profile="unknown-user" xmlns="http://openorb.sf.net/config" xmlns:xlink="http://www.w3.org/1999/xlink" >
<associations>
<association user="joe" profile="joes-profile" />
<association user="fred barney pebbles" profile="flintstones" />
</associations>

When OpenORB is first initialized it first sets three special OpenORB properties, config, profile and home from the 'openorb' module. These properties are used when locating the master config file, and the master profile within it. The following locations are searched for the value of these properties, the first location containing a value is used:

The openorb.home property should generally not be changed from its default setting. It is normally set to the URL resource:/org/openorb/ which is a location within the OpenORB jar files. This directory acts as a base directory for locating openorb resources. Sub directories include the config directory, which contains configuration files for the OpenORB core and extensions, and the idl directory, which contains all the system IDL includes. Note that this property, as with all other OpenORB location properties, is set as a URL rather than as a file. This allows this property to be set to any location reachable over a network.

The openorb.config property is used to set the location of the master config file. The OpenORB setup program can be used to set this property in the orb.properties file. This may be useful when installing OpenORB with a centrally managed configuration. An example command line for setting a new value for openorb config is:

If openorb.config is not set to any value, the master config file location is determined by searching in the following locations, the first of which to get a match is used:

After finding the master configuration file, the profile to use within it is determined by the setting of the openorb.profile property. This property can be set to the name of any of the profiles within the master config file. If this property is not set, the profile is selected as it would be if it were by an import without a fragment, as described above.

The properties set in the configuration file may not be appropriate in all situations. Certain applications may require that certain modules be loaded, and it may be desirable to modify some properties from the command line. It is possible to use command line options to set or override any configuration item which could be set through the configuration file, including adding initializers, setting properties and importing modules and profiles.

OpenORB properties may be overridden by setting Java properties in one of three locations, with locations later in this list overriding earlier locations:

The property name used in these locations is the expanded name of the property, that is the module name concatenated with a '.' and the property name. Extra module imports may be added by setting properties prefixed with 'ImportModule'.

It is possible to add extra initializers by setting properties prefixed with org.omg.PortableInterceptor.ORBInitializerClass or org.openorb.PI.FeatureInitializerClass. All extensions and services created by the openorb project will be distributed with modules, however third party extensions may use the portable interceptor specification.

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

iiop.hostname=example.com

To ensure that the BOA is always used 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("ImportModule.BOA",
                   "${openorb.home}config/default.xml#boa");
 org.omg.CORBA.ORB orb = org.omg.CORBA.ORB(args, props);

 // ...
}

To use a third party portable interceptor, distributed with the ORB initializer named org.example.corba.Initializer, an application which uses OpenORB could be started using the -D java argument to define a system property:

As well as overriding properties via Java properties, they may also be set in the command line arguments passed to the ORB when it is initialized. Properties set in this way override all other property settings, so setting properties on the command line is useful when the configuration may change between each execution of the application.

The recommended way to set OpenORB properties on the command line is to use the module name immediately following -ORB, followed by an argument setting the property to the correct value. For example to the port property in the iiop module to the value '5566' the following command line could be used:

The other available ways of specifying the same property are:

and:

Some commonly overridden properties have special aliases set to allow easy command line modification. These are specified in the module defining the property as detailed in the module section above. An example property which is aliased is the port property in the 'iiop' module. This allows another alternative to the three above examples:

It is possible to add extra module imports, in this case it is often important to quote the command line argument to avoid the shell expanding it:

Portable interceptor initializers can also be specified on the command line. To use a third party portable interceptor, distributed with the ORB initializer named org.example.corba.Initializer, an application which uses OpenORB could be started using:

This document is divided into three parts. The first part describes the OpenORB profile format, then the second part describes how to use such a profile from Java. Then, to finish, the third part enumerates all current sections for a profile.

Each OpenORB profile is described with XML and stored into the OpenORB.xml file.

<OpenORB version="1.2.2">
Here are the OpenORB profiles.
</OpenORB>

Each profile has the following format:

<profile name="xxxxx">
The profile content
</profile>

A profile can extend another profile. To extend a profile, you have to add the attribute 'extends'.

<profile name="xxxxx" extends="yyyyy">
The profile content
</profile>

When a user starts a CORBA application with OpenORB, he has to set the profile name to use with -ORBProfile

If a user does not supply a profile name, a default profile is used except if the user is registered in the profile associations list. The profile associations list is also available in the OpenORB XML file. It enumerates users and associates a profile name with each registered user.

<association>
The associations...
</association>

To define an association, you have to use the following tag: user

<association>
<user name="xxxxx">yyyyy</user>
</association>

A module is a set of section ( see the next paragraph ). To define a module, the rule is:

<module name="xxxxx">
The module content...
</module>

To import a module, a profile must contain the following entry:

<import>xxxx</import>

The profile and module contents are a set of sections. Each section can be simple or complex. More precisely, a section contains a simple value (simple section) or a value list (complex section). A simple section has the following format:

<xxxx>value</xxxx>

For example:

<color>blue</color>

A complex section has the following format:

<xxxx>
<yyyy>
<entry1>value</entry1>
....
</yyyy>
<property 1>value</property 1>
...
</xxxx>

Some values can be set from the command line. Each section name which starts with "ORB" can be overwritten from the command line. There is a way to distinguish simple section from complex section:

For example, if the profile contains the following section:

<ORBInitRef>
<NameService>corbaloc://1.2@myhost:2001/NameService</NameService>
<SecurityService>corbaloc://1.2@myhost:2005/SecurityManager</SecurityService>
</ORBInitRef>

It is possible to overwrite an entry from the command line:

You can also begins a new section from the command line:

And to finish, a simple section:

This section is used by the IIOP protocol to get parameters that are involved in the protocol behaviour.

To be used, the portable interceptor feature must be activated into the OpenORB XML configuration file. The following entry must be added:

<org>
<omg>
<PortableInterceptor>
<CodecFactory>true</CodecFactory>
<PolicyFactory>true</PolicyFactory>
<ClientRequestInterceptor>true</ClientRequestInterceptor>
<ServerRequestInterceptor>true</ServerRequestInterceptor>
<IORInterceptor>true<IORInterceptor>
</PortableInterceptor>
</omg>
</org>

It is possible to provide a list of ORBInitializers from the OpenORB XML configuration file:

<org>
<omg>
<PortableInterceptor>
<ORBInitializerClass>
<myInitializer>com.acme.factory</myInitializer>
<anotherExample>org.free.welldown</anotherExample>
</ORBInitializerClass>
</PortableInterceptor>
</omg>
</org>

Client request interceptors are managed by the Client Interceptor Manager. This entity is only available if "ClientRequestInterceptor" was set to true. To get it, you have resolve the initial reference "ClientInterceptorManager".

org.openorb.PI.ClientInterceptorManager =   (
org.openorb.PI.ClientInterceptorManager )
orb.resolve_initial_references("ClientInterceptorManager");

This manager provides the same operation as a client request interceptor. Each of these operation takes 2 parameters:

The ClientRequestCallback is used by the manager to report some changes for the request state. The change must be immediately taken into account, it means that the state change must be applied to the ClientRequestInfo.

The same method is used for Server request interceptors. A manager is accessible via "ServerInterceptorManager".

The IOR interceptor manager is accessible via the "IORInterceptorManager" key word. It provides the same operation as the IORInterceptors "establish_components".

OpenORB provides an IDL compiler that can be reused by user applications ( see next section ). This IDL compiler is named org.openorb.compiler.IdlCompiler

Execute the compiler without any parameters to get an overview of the valid parameters.

By default, the IDL compiler generates skeletons for the POA, it generates tie/stub classes, it generates all files into a directory named generated and it uses prefix as package names.

The IDL reflection is a powerful and simple mechanism that provides CORBA developers with the ability to reuse the OpenORB IDL compiler. Actually, it means that an IDL description is still compiled by the OpenORB compiler, but there is no code generation. The developers reuse the compilation graph thanks to the reflection API which gives them the ability, for example, to generate some special code artifacts from an IDL description.

The IDL reflection mechanism is divided into two parts:

Now, we are going to describe more precisely the two previous steps.

The first step is very simple. To run the IDL parser, you need to use the org.openorb.compiler.idl.parser.idlParser class. This class provides the following operations:

This class contains a constructor that takes as arguments an array of strings. This array is the equivalent of the command line arguments for the IDL compiler. You can specify into this array the same parameters like on the command line ( -I, -D, ... ) and the IDL files to compile.

The following lines show how to use the IDL parser:

String [] arguments = new String[ 1 ];
arguments[ 0 ] = "example.idl";
org.openorb.compiler.idl.parser.idlParser parser =
     new org.openorb.compiler.idl.parser.idlParser(arguments);
int nb_error = parser.compile( System.out );
if ( nb_error != 0 )
{
    System.out.println("There are: " + nb_error +
                       " compilation errors !");
    System.exit( 0 );
}
java.util.Enumeration content = parser.content( );

The reflection API provides a large set of classes to browse the compilation graph. The graph is organized like an IDL description, there are the containers and the contents. Each graph node is a sub type of org.openorb.compiler.idl.reflect.idlObject. The following classes are available:

idlArray, idlAttribute, idlConst, idlEnum, idlException, idlFactory, idlInterface, idlModule, idlNative, idlOperation, idlParameter, idlSequence, idlState, idlString, idlStruct, idlStructMember, idlTypeDef, idlUnion, idlUnionMember, idlValue, idlValueBox, idlWString, idlIdentifier, idlPrimivite and idlType

Please consult the HTML API documentation to get information about all operations provided by these classes.

The idlObject class provides a lot of useful operations, for example to find specific objects or to find out an object type.

The following example shows how to browse the compilation graph:

java.util.Enumeration content = parser.content();
while ( content.hasMoreElements() )
{
     org.openorb.compiler.idl.reflect.idlObject obj =
          ( org.openorb.compiler.idl.reflect.idlObject )
     content.nextElement();
     switch ( obj.idlType() )
     {
     case org.openorb.compiler.idl.reflect.idlType.MODULE:
         // The current object is a module
        System.out.println("Module name: " + obj.idlName() );
        // ...
        break;
     // ...
     }
}

To manipulate IDL generation to Java, a useful class is also available org.openorb.compiler.idl.util.tools. This class provides several operations ( consult the HTML API documentation ) as for example:

The core OpenORB distribution provides a simple, transient name service which locally implements the java SortedMap interface and can be used directly as a map within applications, as well as as a standalone naming service with all the normal name service features.

To start a standalone naming service, the org.openorb.util.MapNamingContext class is run.

If the -default argument is used, then the name service will register itself as a corbaloc resolvable address, the object reference corbaloc::1.2@localhost/NameService can be used to find a reference to the naming service. If this behavior is not desired use the -print option to print an IOR format address to stderr.

To start the naming service on a specific port number, use the orb argument -ORBPort. If the nameservice was started with -ORBPort=5566 then the corbaloc URL corbaloc::1.2@localhost:5566/NameService could be used to resolve it.

Another standalone server option is available, -shutdown. Using this option allows the destroy operation on the root naming context to shutdown the server, otherwise attempting this will result in a NO_PERMISSION standard system exception to be thrown.

The SortedMap interface on the MapNamingContext allows for simple manipulation of the namespace at the server side. Acquiring the synchronization lock on the MapNamingContext will stop any incoming request being processed, this is useful when map's contents must be manipulating atomically.

The keys of the map are stored as stringified names, the values must be CORBA object references. The Map.put operation will implicitly create any required subcontexts when inserting an object reference. To create a new empty reference, use a stringified name which ends with a '/' and a null value. The contexts created in the Map.put operation are known as virtual contexts.

Virtual contexts have certain usage limitations. Attempting to use the Map.remove operation on a virtual context can result in undefined behavior, use the removeContext operation instead. Attempting to use any nameservice operations which would result in virtual context being unbound will result in a CannotProceed exception being thrown. Virtual contexts can be created using the bind_new_context nameservice operation.

Non-virtual contexts can be created by using the new_context operation. Any context created by the new_context operation has its lifetime constrained by the nonvirtual parent contexts of the context which created it; successfully calling destroy on the nonvirtual parent of the creator context will also result in any context created with the new_context operation being destroyed. Other than this constraint, no checks are performed to ensure the context is not orphaned.

Helper classes generated by the OpenORB IDL compiler insert and extract by reference all complex types: structs, unions, and exceptions. This is useful as it avoids excess copying of data and increases performance. Whenever a helper class is used to insert a value into an Any the Any stores a reference to the inserted value. Whenever the extract operation is used on an Any containing a non-reference representation of its contents, the contents will be replaced with a reference to the returned value.

The helper classes will always have this exact behaviour when used with the OpenORB runtime. If a non-OpenORB ORB is used the extract operation may only extract by value. More effort is made by the helper classes to extract by reference if the -portableref argument is used to the compiler, this will work on any ORB which defines the extract_Streamable operation on its Any class, however the extract operation will be slower.

To insert a complex type into an Any by value use the following code:

any.type(SHelper.type());
SHelper.write(s, any.create_output_stream());

To extract a copy of the contained complex type use:

if(!any.type().equals(SHelper.type())
// perform some remedial action
s = SHelper.read(any.create_input_stream());

The above code fragments will not work with valuetypes, these are always stored by reference.