Java IDL Programming Concepts

This topic includes the following sections:

• Exceptions

• Initializations

• The FactoryFinder Interface

 

---

Exceptions

CORBA has two types of exceptions: standard system exceptions, which are fully specified by the OMG, and user exceptions, which are defined by the individual application programmer. CORBA exceptions differ slightly from Java exception objects, but those differences are largely handled in the mapping from IDL-to-Java.

Topics in this section include:

• Differences Between CORBA and Java Exceptions

• System Exceptions

• User Exceptions

• Minor Code Meanings

Differences Between CORBA and Java Exceptions

To specify an exception in IDL, the interface designer uses the raises keyword. This is similar to the throws specification in Java. When you use the exception keyword in IDL, you create a user-defined exception. The standard system exceptions need not (and cannot) be specified this way.

System Exceptions

CORBA defines a set of standard system exceptions, which are generally raised by the ORB libraries to signal systemic error conditions including:

• Server-side system exceptions, such as resource exhaustion or activation failure.

• Communication system exceptions, for example, losing contact with the object, host down, or cannot talk to the ISL or ISH.

• Client-side system exceptions, such as invalid operand type or anything that occurs before a request is sent or after the result comes back.

All IDL operations can throw system exceptions when invoked. The interface designer need not specify anything to enable operations in the interface to throw system exceptions; the capability is automatic.

This makes sense because no matter how trivial an operation's implementation is, the potential of an operation invocation coming from a client that is in another process, and perhaps (likely) on another machine, means that a whole range of errors is possible.

Therefore, a CORBA Java client should always catch CORBA system exceptions. Moreover, developers cannot rely on the idltojava compiler to notify them of a system exception they should catch, because CORBA system exceptions are descendants of java.lang.RuntimeException.

System Exception Structure

All CORBA system exceptions have the same structure:

exception <SystemExceptionName> { // descriptive of error
    unsigned long minor;          // more detail about error
    CompletionStatus completed;   // yes, no, maybe
}

System exceptions are subtypes of java.lang.RuntimeException through org.omg.CORBA.SystemException:

java.lang.Exception
 |
 +--java.lang.RuntimeException
     |
     +--org.omg.CORBA.SystemException
         |
         +--BAD_PARAM
         |
         +--//etc. 

Completion Status

All CORBA system exceptions have a completion status field which indicates the status of the operation that threw the exception. The completion codes are:

• COMPLETED_YES

  The object implementation has completed processing prior to the exception being raised.

• COMPLETED_NO

  The object implementation was not invoked prior to the exception being raised.

• COMPLETED_MAYBE

  The status of the invocation is unknown.

User Exceptions

CORBA user exceptions are subtypes of java.lang.Exception through org.omg.CORBA.UserException:

java.lang.Exception
 |
 +--org.omg.CORBA.UserException
      |
      +-- Stocks.BadSymbol
      |
      +--//etc. 

Each user-defined exception specified in IDL results in a generated Java exception class. These exceptions are entirely defined and implemented by the programmer.

Minor Code Meanings

Every system exception has a "minor" field that allows CORBA vendors to provide additional information about the cause of the exception. Table  4-1 and Table  4-2 list the minor codes of Java IDL's system exceptions and describes their significance.

Table 4-1 ORB Minor Codes and Their Meanings  

Code	Meaning
BAD_PARAM Exception Minor Codes
1	A null parameter was passed to a Java IDL method.
COMM_FAILURE Exception Minor Codes
1	Unable to connect to the host and port specified in the object reference, or in the object reference obtained after location/object forward.
2	Error occurred while trying to write to the socket. The socket has been closed by the other side, or is aborted.
3	Error occurred while trying to write to the socket. The connection is no longer alive.
6	Unable to successfully connect to the server after several attempts.
DATA_CONVERSION Exception Minor Codes
1	Encountered a bad hexadecimal character while doing ORB string_to_object operation.
2	The length of the given IOR for string_to_object() is odd. It must be even.
3	The string given to string_to_object() does not start with IOR; and hence, is a bad stringified IOR.
4	Unable to perform ORB resolve_initial_references operation due to the host or the port being incorrect or unspecified, or the remote host does not support the Java IDL bootstrap protocol.
INTERNAL Exception Minor Codes
3	Bad status returned in the IIOP Reply message by the server.
6	When unmarshaling, the repository ID of the user exception was found to be the incorrect length.
7	Unable to determine the local hostname using the Java APIs InetAddress.getLocalHost().getHostName().
8	Unable to create the listener thread on the specific port. Either the port is already in use, there was an error creating the daemon thread, or security restrictions prevent listening.
9	Bad locate reply status found in the IIOP locate reply.
10	Error encountered while stringifying an object reference.
11	IIOP message with bad GIOP 1.0 message type found.
14	Error encountered while unmarshaling the user exception.
18	Internal initialization error.
INV_OBJREF Exception Minor Codes
1	An IOR with no profile was encountered.
MARSHAL Exception Minor Codes
4	Error occurred while unmarshaling an object reference.
5	Marshaling/unmarshaling unsupported IDL types like wide characters and wide strings.
6	Character encountered while marshaling or unmarshaling a character or string that is not ISO Latin-1 (8859.1) compliant. It is not in the range of 0 to 255.
NO_IMPLEMENT Exception Minor Codes
1	Dynamic Skeleton Interface is not implemented.
OBJ_ADAPTER Exception Minor Codes
1	No object adapter was found matching the one in the object key when dispatching the request on the server side to the object adapter layer.
2	No object adapter was found matching the one in the object key when dispatching the locate request on the server side to the object adapter layer.
4	Error occurred when trying to connect a servant to the ORB.
OBJ_NOT_EXIST Exception Minor Codes
1	Locate request received a response indicating that the object is not known to the locator.
2	Server ID of the server that received the request does not match the server ID baked into the object key of the object reference that was invoked upon.
4	No skeleton was found on the server side that matches the contents of the object key inside the object reference.
UNKNOWN Exception Minor Codes
1	Unknown user exception encountered while unmarshaling; the server returned a user exception that does not match any expected by the client.
3	Unknown run-time exception thrown by the server implementation.

 

Table 4-2 Name Server Minor Codes and Their Meanings  

Code	Meaning
INITIALIZE Exception Minor Codes
150	Transient name service caught a SystemException while initializing.
151	Transient name service caught a Java exception while initializing.
INTERNAL Exception Minor Codes
100	An AlreadyBound exception was thrown in a rebind operation.
101	An AlreadyBound exception was thrown in a rebind_context operation.
102	Binding type passed to the internal binding implementation was not BindingType.nobject or BindingType.ncontext.
103	Object reference was bound as a context, but it could not be narrowed to CosNaming.NamingContext.
200	Implementation of the bind operation encountered a previous binding.
201	Implementation of the list operation caught a Java exception while creating the list iterator.
202	Implementation of the new_context operation caught a Java exception while creating the new NamingContext servant.
203	Implementation of the destroy operation caught a Java exception while disconnecting from the ORB.

 

 

---

Initializations

Before a CORBA Java client or a CORBA Java joint client/server can use CORBA objects, it must initialize itself by:

• Creating an ORB object.

• Obtaining one or more initial object references, typically using a FactoryFinder object.

Creating an ORB Object

Before it can create or invoke a CORBA object, a CORBA Java client or a CORBA Java joint client/server must first create an ORB object. By creating an ORB object, the client or joint client/server introduces itself to the ORB and obtains access to important operations that are defined on the ORB object.

Clients and joint client/servers 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

The following code fragment shows how a CORBA Java client 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

A Java 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 a built-in ORB. This can cause problems if that ORB is not entirely 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 p = new Properties();
        p.put("org.omg.CORBA.ORBClass", "com.sun.CORBA.iiop.ORB");
        p.put("org.omg.CORBA.ORBSingletonClass","com.sun.CORBA.idl.ORBSingleton");
        System.setProperties(p);
        ORB orb = ORB.init(args, p);
        ...
      }
    }

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 used by the init() operation. 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 in which they are running.

System Properties

The BEA Tuxedo product uses the Sun Microsystem, Inc. Java virtual machine, which 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.

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 FactoryFinder

• From the bootstrap method

Stringified Object References

The first technique, converting a stringified reference to an actual object reference, is ORB-implementation independent. Regardless of which 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 actually accessible from where the applet or application is running.

• Obtain the stringified reference, perhaps from a file or a parameter.

Getting References from the ORB

If you do not use a stringified reference to get an initial CORBA object, you use the ORB itself to produce an initial object reference.

The Bootstrap object 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.

Using the Bootstrap object, you can obtain the following object references (SecurityCurrent, TransactionCurrent, FactoryFinder, NotificationService, Tobj_SimpleEventsService, NameService, and InterfaceRepository). The object of concern to us here is the FactoryFinder object.

The FactoryFinder interface provides clients with one object reference that serves as the single point of entry into the BEA Tuxedo domain. The FactoryFinder object is used to obtain a specific factory object, which in turn can create the needed objects.

For more information on how to use the Bootstrap object, see the CORBA Programming Reference.

 

---

The FactoryFinder Interface

The FactoryFinder interface provides clients with one object reference that serves as the single point of entry into the BEA Tuxedo domain. Multiple FactoryFinders provide increased availability and reliability. Mapping across multiple domains is supported.

The FactoryFinder interface and the NameManager are a mechanism for registering, storing, and finding objects. In the BEA Tuxedo environment, you can:

• Use the Bootstrap object to obtain an object reference to a FactoryFinder object.

• Use the FactoryFinder object to find the Factory object you need.

• Use the Factory object to create new instances of the CORBA object.

For more information about how to use the FactoryFinder object, see the CORBA Programming Reference.