# Initialization

Before a Java program can use CORBA objects, it must initialize itself as follows:

- Create an ORB object.
- Obtain one or more initial object references, typically at least a naming context.

Topics in this section include:

- Creating an ORB Object
  - Creating an ORB for an Application
  - Creating an ORB for an Applet
  - Arguments to ORB.init()
  - System Properties
- Obtaining Initial Object References
  - Stringified Object References
  - Getting References from an ORB

## Creating an ORB Object

Before it can create or invoke a CORBA object, an applet or application must first create an ORB object. Doing so introduces the applet or application to the ORB and obtains access to important operations that are defined on the ORB object.

Applets and applications create ORB instances slightly differently, because their parameters, which must be passed in the `ORB.init()` call, are arranged differently.

### Creating an ORB for an Application

This fragment shows how an application might create an ORB:

        import org.omg.CORBA.ORB;

        public static void main(String args[])
        {
          try{
            ORB orb = ORB.init(args, null);
        // code continues

### Creating an ORB for an Applet

An applet creates an ORB like this:

        import org.omg.CORBA.ORB;

        public void init() {
          try {
            ORB orb = ORB.init(this, null);
        // code continues

Some web browsers have an ORB built directly into them. This can cause problems if that ORB is not perfectly compliant. In this case, special steps must be taken to initialize the Java IDL ORB specifically. For example, because of missing classes in the installed ORB in Netscape Communicator 4.01, an applet displayed in that browser must contain code similar to the following in its `init()` method:

        import java.util.Properties;
        import org.omg.CORBA.*;

        public class MyApplet extends java.applet.Applet {
          public void init()
          {
            // Instantiate the Java IDL ORB, passing in this applet
            // so that the ORB can retrieve the applet properties.
            Properties props = new Properties();
            props.put("org.omg.CORBA.ORBClass", "com.sun.CORBA.iiop.ORB");
            ORB orb = ORB.init(this, props);
            ...
          }
        }

### Arguments to ORB.init()

For both applications and applets, the arguments for the initialization method are:

args or this
  Provides the ORB access to the application's arguments or applet's parameters.
null
  A `java.util.Properties` object.

The `init()` operation uses these parameters, as well as the system properties, to obtain information it needs to configure the ORB. It searches for ORB configuration properties in the following places and order:

1. The application or applet parameters (first argument)
2. A `java.util.Properties` object (second argument), if one has been supplied
3. The `java.util.Properties` object returned by `System.getProperties()`

The first value found for a particular property is the value the `init()` operation uses. If a configuration property cannot be found in any of these places, the `init()` operation assumes an implementation-specific value for it. For maximum portability among ORB implementations, applets and applications should explicitly specify configuration property values that affect their operation, rather than relying on the assumptions of the ORB they happen to be running in.

### System Properties

With respect to the system `Properties` object, note that Sun's Java virtual machine* adds `-D` command line arguments to it. Other Java virtual machines may or may not do the same.

Currently, the following configuration properties are defined for all ORB implementations:

`org.omg.CORBA.ORBClass`
  The name of a Java class that implements the `org.omg.CORBA.ORB` interface. Applets and applications do not need to supply this property unless they must have a particular ORB implementation. The value for the Java IDL ORB is `com.sun.CORBA.iiop.ORB`.
`org.omg.CORBA.ORBSingletonClass`
  The name of a Java class that implements the `org.omg.CORBA.ORB` interface. This is the object returned by a call to `orb.init()` with no arguments. It is used primarily to create typecode instances than can be shared across untrusted code (such as unsigned applets) in a secured environment.

In addition to the standard properties listed above, Java IDL also supports the following properties:

`org.omg.CORBA.ORBInitialHost`
  The host name of a machine running a server or daemon that provides initial bootstrap services, such as a name service. The default value for this property is `localhost` for applications. For applets it is the applet host, equivalent to `getCodeBase().getHost()`.
`org.omg.CORBA.ORBInitialPort`
  The port the initial naming service listens to. The default value is `900`.

Note: When specifying a property as a command-line argument to a Java IDL application, omit the `org.omg.CORBA.` portion of the property name. For example, a command line that starts an application looks like this:

        -ORBInitialPort 800

Applet parameters should specify the full property names. The conventions for applications differ from applets so as not to expose language-specific details in command-line invocations.

## Obtaining Initial Object References

To invoke a CORBA object, an applet or application must have a reference for it. There are three ways to get a reference for a CORBA object:

- From a string that was specially created from an object reference
- From another object, such as a naming context
- From the `ORB` operation `resolve_initial_references()`

### Stringified Object References

The first technique, converting a stringified reference to an actual object reference, is ORB-implementation independent. No matter what Java ORB an applet or application runs on, it can convert a stringified object reference. However, it is up to the applet or application developer to:

- Ensure that the object referred to is in fact accessible from where the applet or application is running.
- Obtain the stringified reference, perhaps from a file or a parameter.

The following fragment shows how a server converts a CORBA object reference to a string:

>     org.omg.CORBA.ORB orb =    // get an ORB object
>     org.omg.CORBA.Object obj = // create the object reference
>     String str = orb.object_to_string(obj);
>     // make the string available to the client

This code fragment shows how a client converts the stringified object reference back to an object:

>     org.omg.CORBA.ORB orb =    // get an ORB object
>     String stringifiedref =    // read string
>     org.omg.CORBA.Object obj = orb.string_to_object(stringifiedref);

### Getting References from an ORB

If you don't use a stringified reference to get an initial CORBA object, you use the ORB itself to produce an initial object reference. However, doing so may make your applet or application ORB-dependent, because, although the CORBA specification defines the interface for getting initial object references, it doesn't yet provide enough information for ORB vendors to implement it in a standard way. Applet and application developers should therefore be cautious when using this operation until the standard is more tightly specified. To guarantee ORB-implementation-independence, use the stringified object reference technique instead.

The ORB interface defines an operation called `resolve_initial_references()` that is intended for bootstrapping object references into a newly started application or applet. The operation takes a string argument that names one of a few recognized objects; it returns a CORBA Object, which must be narrowed to the type the applet or application knows it to be. Two string values are presently defined:

`NameService`
  Passing this value returns a reference to a root naming context which, after narrowing, can be used to look up references for objects whose names are known to the applet or application (assuming those objects are registered by those names in the root or subordinate naming contexts).
`InterfaceRepository`
  This value returns a reference to an interface repository, a CORBA object that contains interface definitions. The current release of Java IDL does not include an implementation of the interface repository. If you are using another server-side orb, you can still use "InterfaceRepository" as the argument to `resolve_initial_references()`.

The Java IDL implementation of `resolve_initial_references()` requires an already-running naming service whose host and port are identified by the `ORBInitialHost` and `ORBInitialPort` properties described previously, or by their default values. See Naming Service for details on starting the Java IDL name server.

*As used on this web site, the terms "Java Virtual Machine" or "JVM" mean a virtual machine for the Java platform.

Home

Copyright © 1996, 1997 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA. 94043-1100 USA., All rights reserved.