Comments for Package `org.omg.CORBA`

The org.omg.CORBA package supplies the mapping of the OMG CORBA 2.0 APIs to the Java^TM programming language including the class ORB, which is implemented so that a programmer can use it as a fully functional Object Request Broker (ORB).

An ORB handles (or brokers) method invocations between a client and the method's implementation (on a server). Because the client and server may be anywhere on a network, and because the invocation and implementation may be written in different programming languages, an ORB does a great deal of work behind the scenes to accomplish this communication.

What the General User Needs to Know

Most of what an ORB does is completely transparent to the user, and a major portion of the CORBA package consists of classes used by the ORB behind the scenes. The result is that most programmers will use only a small part of this package directly. In fact, most programmers will use only a few methods from the ORB class, some exceptions, and occasionally, a holder class.

`ORB` Methods

These are the ORB methods that a general user might invoke:

connect()
disconnect()
init()
init(String [] args, Properties props)
init(Applet app, Properties props)
list_initial_services()
resolve_initial_references(String name)
object_to_string(Object obj)
string_to_object(String str)

Exceptions

Exceptions in Java IDL are similar to those in any code written in the Java programming language. If a method is defined to throw an exception, then any code using that method must have a try/catch block and handle that exception when it is thrown.

The documentation on Java IDL exceptions has more information and explains the difference between system exceptions and user-defined exceptions.

The following is a list of the system exceptions (which are unchecked exceptions inheriting through org.omg.CORBA.SystemException from java.lang.RuntimeException) that are defined in the class ORB:

 
        BAD_CONTEXT
        BAD_INV_ORDER
        BAD_OPERATION
        BAD_PARAM
        BAD_TYPECODE
        COMM_FAILURE
        DATA_CONVERSION
        FREE_MEM
        IMP_LIMIT
        INITIALIZE
        INTERNAL
        INTF_REPOS
        INVALID_TRANSACTION
        INV_FLAG
        INV_IDENT
        INV_OBJREF
        MARSHAL
        NO_IMPLEMENT
        NO_MEMORY
        NO_PERMISSION
        NO_RESOURCES
        NO_RESPONSE
        OBJECT_NOT_EXIST
        OBJ_ADAPTER
        PERSIST_STORE
        TRANSACTION_REQUIRED
        TRANSACTION_ROLLEDBACK
        TRANSIENT
        UNKNOWN

The following is a list of user-defined exceptions defined in the package org.omg.CORBA.

 
        Bounds
        UnknownUserException
        WrongTransaction

Note that there are two packages whose only purpose is to contain user-defined exceptions thrown by classes in the package org.omg.CORBA.

The package org.omg.CORBA.TypeCodePackage contains two exceptions thrown by methods in the class TypeCode. These exceptions are:

BadKind
Bounds

The package org.omg.CORBA.ORBPackage contains one exception, which is:

InvalidName

Holder classes

Operations in an IDL interface may take out or inout parameters as well as in parameters. The Java programming language only passes parameters by value and thus does not have out or inout parameters, so these are mapped to what are called Holder classes. In place of the IDL out parameter, the Java programming language method will take an instance of the Holder class of the appropriate type. The result that was assigned to the out or inout parameter in the IDL interface is assigned to the value field of the Holder class.

The package org.omg.CORBA contains a Holder class for each of the basic types (BooleanHolder, LongHolder, StringHolder, and so on). It also has Holder classes for each generated class (such as TypeCodeHolder), but these are used transparently by the ORB, and the programmer usually does not see them.

The Holder classes defined in the package org.omg.CORBA are:

     AnyHolder
     BooleanHolder
     ByteHolder
     CharHolder
     DoubleHolder
     FloatHolder
     IntHolder
     LongHolder
     ObjectHolder
     PrincipalHolder
     ShortHolder
     StringHolder
     TypeCodeHolder

For Advanced Users

The other, behind-the-scenes, classes and interfaces in the CORBA package can be put into four groups. Three of the groups are used with requests in some capacity, and the fourth group, concerning the Interface Repository, is a category by itself.

Classes Created by an ORB

The first group contains classes that are created by an ORB and contain information used in request operations. They are listed in roughly increasing order of complexity:

TCKind -- indicates the kind (datatype) for a TypeCode object
TypeCode -- indicates a datatype and possibly other information
Any -- contains a value and its typecode
NamedValue -- contains a name, an Any object, and an argument mode flag. (NamedValue objects contain information about method arguments, method return values, or a context.)
ContextList -- a list of strings that describe the contexts that need to be resolved and sent with an invocation
ExceptionList -- a list of TypeCodes for exceptions that may be thrown by a method
Environment -- a container for the exception thrown during a method invocation
Context -- a list of NamedValue objects used to pass auxiliary information from client to server
NVList -- a list of NamedValue objects, used to pass arguments or get results

Classes That Deal with Requests

The second group of classes deals with requests:

Object -- the base class for all CORBA object references
Request -- the main class in the DII, which contains methods for adding arguments to the request, for accessing information about the method being invoked (the method name, its arguments, exceptions it throws, and so on), and for making invocations on the request
DynamicImplementation -- the base class for server implementations using the DSI. It has the method invoke, which is used by an implementation of this class to determine the state of a ServerRequest object and to set its result or exception
ServerRequest -- captures the explicit state of a request for the Dynamic Skeleton Interface

Constants Used as Flags

The third group contains interfaces that define constants used as flags. These flags, used in NamedValue objects or as parameters to methods, are defined in the following interfaces:

ARG_IN
ARG_INOUT
ARG_OUT
CTX_RESTRICT_SCOPE

Interface Repository Classes

A fourth group contains the Interface Repository classes, which are generated by the idltojava compiler from the IDL interface ir.idl. This API is available for developers but is not implemented in Java IDL.

Comments for Package org.omg.CORBA