Package org.omg.CORBA

Provides the mapping of the OMG CORBA 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).

See:
Description

Interface Summary

ARG_IN	Signifies an "input" argument to an invocation, meaning that the argument is being passed from the client to the server.
ARG_INOUT	Signifies an argument used for both input and output in an invocation, meaning that the argument is being passed from the client to the server and then back from the server to the client.
ARG_OUT	A constant that signifies an "output" argument to an invocation, meaning that the argument is being passed from the server to the client.
BAD_POLICY	A PolicyErrorCode which would be filled in the PolicyError exception.
BAD_POLICY_TYPE	A PolicyErrorCode which would be filled in the PolicyError exception.
BAD_POLICY_VALUE	Contains the value used to indicate a policy value that is incorrect for a valid policy type in a call to the create_policy method defined in the ORB class.
CTX_RESTRICT_SCOPE	A flag that can be used as the second parameter to the method Context.get_values to restrict the search scope.
Current	Interfaces derived from the Current interface enable ORB and CORBA services to provide access to information (context) associated with the thread of execution in which they are running.
CurrentOperations	The interface for Current.
CustomMarshal	An abstract value type that is meant to be used by the ORB, not the user.
DataInputStream	Defines the methods used to read primitive data types from input streams for unmarshaling custom value types.
DataOutputStream	Defines the methods used to write primitive data types to output streams for marshalling custom value types.
DomainManager	Provides mechanisms for establishing and navigating relationships to superior and subordinate domains, as well as for creating and accessing policies.
DomainManagerOperations	Provides the DomainManager with the means to access policies.
DynAny	Deprecated. Use the new DynAny instead
DynArray	Deprecated. Use the new DynArray instead
DynEnum	Deprecated. Use the new DynEnum instead
DynFixed	Deprecated. Use the new DynFixed instead
DynSequence	Deprecated. Use the new DynSequence instead
DynStruct	Deprecated. Use the new DynStruct instead
DynUnion	Deprecated. Use the new DynUnion instead
DynValue	Deprecated. Use the new DynValue instead
IDLType	An abstract interface inherited by all Interface Repository (IR) objects that represent OMG IDL types.
IDLTypeOperations	This interface must be implemented by all IDLType objects.
IRObject	An IRObject IDL interface represents the most generic interface from which all other Interface Repository interfaces are derived, even the Repository itself.
IRObjectOperations	This is the Operations interface for the mapping from IRObject.
Object	The definition for a CORBA object reference.
OMGVMCID	The vendor minor code ID reserved for OMG.
Policy	Interfaces derived from the Policy interface allow an ORB or CORBA service access to certain choices that affect its operation.
PolicyOperations	Provides the operations for a Policy object.
PRIVATE_MEMBER	Constant to define a private member in the ValueMember class.
PUBLIC_MEMBER	Constant to define a public member in the ValueMember class.
UNSUPPORTED_POLICY	One of the PolicyErrorCodes which would be filled if the requested Policy is understood to be valid by the ORB, but is not currently supported.
UNSUPPORTED_POLICY_VALUE	A PolicyErrorCode which would be filled if the value requested for the Policy is of a valid type and within the valid range for that type, but this valid value is not currently supported.
VM_ABSTRACT	Defines the code used to represent an Abstract interface in a typecode.
VM_CUSTOM	Defines the code used to represent a custom marshalled value type in a typecode.
VM_NONE	Defines the code used to represent the one of the values of a value type in a typecode.
VM_TRUNCATABLE	Defines the code used to represent a truncatable value type in a typecode.

Class Summary

_IDLTypeStub	The Stub for IDLType.
_PolicyStub	The Stub for Policy.
Any	Serves as a container for any data that can be described in IDL or for any IDL primitive type.
AnyHolder	The Holder for Any.
AnySeqHelper	The Helper for AnySeq.
AnySeqHolder	The Holder for AnySeq.
BooleanHolder	The Holder for Boolean.
BooleanSeqHelper	The Helper for BooleanSeq.
BooleanSeqHolder	The Holder for BooleanSeq.
ByteHolder	The Holder for Byte.
CharHolder	The Holder for Char.
CharSeqHelper	The Helper for CharSeq.
CharSeqHolder	The Holder for CharSeq.
CompletionStatus	An object that indicates whether a method had completed running when a SystemException was thrown.
CompletionStatusHelper	The Helper for CompletionStatus.
Context	An object used in Request operations to specify the context object in which context strings must be resolved before being sent along with the request invocation.
ContextList	An object containing a modifiable list of String objects that represent property names.
CurrentHelper	The Helper for Current.
CurrentHolder	The Holder for Current.
DefinitionKind	The class that provides the constants used to identify the type of an Interface Repository object.
DefinitionKindHelper	The Helper for DefinitionKind.
DoubleHolder	The Holder for Double.
DoubleSeqHelper	The Helper for DoubleSeq.
DoubleSeqHolder	The Holder for DoubleSeq.
DynamicImplementation	Deprecated. org.omg.CORBA.DynamicImplementation
Environment	A container (holder) for an exception that is used in Request operations to make exceptions available to the client.
ExceptionList	An object used in Request operations to describe the exceptions that can be thrown by a method.
FieldNameHelper	The Helper for FieldName.
FixedHolder	The Holder for Fixed.
FloatHolder	The Holder for Float.
FloatSeqHelper	The Helper for FloatSeq.
FloatSeqHolder	The Holder for FloatSeq.
IdentifierHelper	The Helper for Identifier.
IDLTypeHelper	The Helper for IDLType.
IntHolder	The Holder for Int.
LocalObject	Used as a base class for implementation of a local IDL interface in the Java language mapping.
LongHolder	The Holder for Long.
LongLongSeqHelper	The Helper for LongLongSeq.
LongLongSeqHolder	The Holder for LongLongSeq.
LongSeqHelper	The Helper for LongSeqHelper.
LongSeqHolder	The Holder for LongSeq.
NamedValue	An object used in the DII and DSI to describe arguments and return values.
NameValuePair	Associates a name with a value that is an attribute of an IDL struct, and is used in the DynStruct APIs.
NameValuePairHelper	The Helper for NameValuePair.
NVList	A modifiable list containing NamedValue objects.
ObjectHelper
ObjectHolder	The Holder for Object.
OctetSeqHelper	The Helper for OctetSeq.
OctetSeqHolder	The Holder for OctetSeq.
ORB	A class providing APIs for the CORBA Object Request Broker features.
ParameterMode	Enumeration of parameter modes for Parameter.
ParameterModeHelper	Enumeration of parameter modes for Parameter.
ParameterModeHolder	Enumeration of parameter modes for Parameter.
PolicyErrorCodeHelper	Encapsulates a reason a Policy may be invalid.
PolicyErrorHelper	Thrown to indicate problems with parameter values passed to the ORB.create_policy operation.
PolicyErrorHolder	Thrown to indicate problems with parameter values passed to the ORB.create_policy operation.
PolicyHelper	The Helper for Policy.
PolicyHolder	The Holder for Policy.
PolicyListHelper	The Helper for PolicyList.
PolicyListHolder	The Holder for PolicyList.
PolicyTypeHelper	The Helper for PolicyType.
Principal	Deprecated. Deprecated by CORBA 2.2.
PrincipalHolder	Deprecated. Deprecated by CORBA 2.2.
RepositoryIdHelper	The Helper for RepositoryId.
Request	An object containing the information necessary for invoking a method.
ServerRequest	An object that captures the explicit state of a request for the Dynamic Skeleton Interface (DSI).
ServiceDetail	An object that represents an ORB service: its service_detail_type field contains the type of the ORB service, and its service_detail field contains a description of the ORB service.
ServiceDetailHelper
ServiceInformation	An IDL struct in the CORBA module that stores information about a CORBA service available in the ORB implementation and is obtained from the ORB.get_service_information method.
ServiceInformationHelper
ServiceInformationHolder	The Holder for ServiceInformation.
SetOverrideType	The mapping of a CORBA enum tagging SET_OVERRIDE and ADD_OVERRIDE, which indicate whether policies should replace the existing policies of an Object or be added to them.
SetOverrideTypeHelper	The Helper for SetOverrideType.
ShortHolder	The Holder for Short.
ShortSeqHelper	The Helper for ShortSeqHelper.
ShortSeqHolder	The Holder for ShortSeq.
StringHolder	The Holder for String.
StringSeqHelper	An array of Strings
StringSeqHolder	An array of Strings
StringValueHelper	The Helper for StringValue.
StructMember	Describes a member of an IDL struct in the Interface Repository, including the name of the struct member, the type of the struct member, and the typedef that represents the IDL type of the struct member described the struct member object.
StructMemberHelper	The Helper for StructMember.
TCKind	The Java mapping of the IDL enum TCKind, which specifies the kind of a TypeCode object.
TypeCode	A container for information about a specific CORBA data type.
TypeCodeHolder	The Holder for TypeCode.
ULongLongSeqHelper	The Helper for ULongLongSeq.
ULongLongSeqHolder	The Holder for ULongLongSeq.
ULongSeqHelper	The Helper for ULongSeq.
ULongSeqHolder	The Holder for ULongSeq.
UnionMember	A description in the Interface Repository of a member of an IDL union.
UnionMemberHelper	The Helper for UnionMember.
UnknownUserExceptionHelper	The Helper for UnknownUserException.
UnknownUserExceptionHolder	The Holder for UnknownUserException.
UShortSeqHelper	The Helper for UShortSeq.
UShortSeqHolder	The Holder for UShortSeq.
ValueBaseHelper
ValueBaseHolder	The Holder for ValueBase.
ValueMember	A description in the Interface Repository of a member of a value object.
ValueMemberHelper	The Helper for ValueMember.
VersionSpecHelper	The Helper for VersionSpec.
VisibilityHelper	The Helper for Visibility.
WCharSeqHelper	The Helper for WCharSeq.
WCharSeqHolder	The Holder for WCharSeq.
WrongTransactionHelper	The Helper for WrongTransaction.
WrongTransactionHolder	The Holder for WrongTransaction.
WStringSeqHelper	An array of WStrings
WStringSeqHolder	An array of WStrings
WStringValueHelper	org/omg/CORBA/WStringValueHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from orb.idl 31 May 1999 22:27:30 o'clock GMT+00:00 The class definition has been modified to conform to the following OMG specifications : ORB core as defined by CORBA 2.3.1 (formal/99-10-07) IDL/Java Language Mapping as defined in ptc/00-01-08

Exception Summary

ACTIVITY_COMPLETED	The ACTIVITY_COMPLETED system exception may be raised on any method for which Activity context is accessed.
ACTIVITY_REQUIRED	The ACTIVITY_REQUIRED system exception may be raised on any method for which an Activity context is required.
BAD_CONTEXT	Exception thrown when an operation is invoked by a client but the passed context does not contain the context values required by the operation.
BAD_INV_ORDER	This exception indicates that the caller has invoked operations in the wrong order.
BAD_OPERATION	Exception thrown when an object reference denotes an existing object, but that the object does not support the operation that was invoked.
BAD_PARAM	Exception thrown when a parameter passed to a call is out of range or otherwise considered illegal.
BAD_QOS	The BAD_QOS exception is raised whenever an object cannot support the quality of service required by an invocation parameter that has a quality of service semantics associated with it.
BAD_TYPECODE	Exception thrown when the ORB has encountered a malformed type code (for example, a type code with an invalid TCKind value).
Bounds	A user exception thrown when a parameter is not within the legal bounds for the object that a method is trying to access.
CODESET_INCOMPATIBLE	This exception is raised whenever meaningful communication is not possible between client and server native code sets.
COMM_FAILURE	This exception is raised if communication is lost while an operation is in progress, after the request was sent by the client, but before the reply from the server has been returned to the client.
DATA_CONVERSION	This exception is raised if an ORB cannot convert the representation of data as marshaled into its native representation or vice-versa.
FREE_MEM	Exception thrown when the ORB failed in an attempt to free dynamic memory, for example because of heap corruption or memory segments being locked.
IMP_LIMIT	This exception indicates that an implementation limit was exceeded in the ORB run time.
INITIALIZE	Exception thrown when an ORB has encountered a failure during its initialization, such as failure to acquire networking resources or detecting a configuration error.
INTERNAL	This exception indicates an internal failure in an ORB, for example, if an ORB has detected corruption of its internal data structures.
INTF_REPOS	Exception raised when an ORB cannot reach the interface repository, or some other failure relating to the interface repository is detected.
INV_FLAG	Exception thrown when an invalid flag was passed to an operation (for example, when creating a DII request).
INV_IDENT	This exception indicates that an IDL identifier is syntactically invalid.
INV_OBJREF	This exception indicates that an object reference is internally malformed.
INV_POLICY	Standard exception thrown when an invocation cannot be made because of an incompatibility between Policy overrides that apply to the particular invocation.
INVALID_ACTIVITY	The INVALID_ACTIVITY system exception may be raised on the Activity or Transaction services' resume methods if a transaction or Activity is resumed in a context different to that from which it was suspended.
INVALID_TRANSACTION	Exception thrown when the request carried an invalid transaction context.
MARSHAL	A request or reply from the network is structurally invalid.
NO_IMPLEMENT	This exception indicates that even though the operation that was invoked exists (it has an IDL definition), no implementation for that operation exists.
NO_MEMORY	Exception thrown when the ORB run time has run out of memory.
NO_PERMISSION	Exception thrown when an invocation failed because the caller has insufficient privileges.
NO_RESOURCES	Exception thrown when the ORB has encountered some general resource limitation.
NO_RESPONSE	This exception is raised if a client attempts to retrieve the result of a deferred synchronous call, but the response for the request is not yet available.
OBJ_ADAPTER	This exception typically indicates an administrative mismatch, for example, a server may have made an attempt to register itself with an implementation repository under a name that is already in use, or is unknown to the repository.
OBJECT_NOT_EXIST	Exception raised whenever an invocation on a deleted object was performed.
PERSIST_STORE	This exception indicates a persistent storage failure, for example, failure to establish a database connection or corruption of a database.
PolicyError	A user exception thrown when a policy error occurs.
REBIND	REBIND is raised when the current effective RebindPolicy, has a value of NO_REBIND or NO_RECONNECT and an invocation on a bound object reference results in a LocateReply message with status OBJECT_FORWARD or a Reply message with status LOCATION_FORWARD.
SystemException	The root class for all CORBA standard exceptions.
TIMEOUT	TIMEOUT is raised when no delivery has been made and the specified time-to-live period has been exceeded.
TRANSACTION_MODE	The CORBA TRANSACTION_MODE exception is thrown by the client ORB if it detects a mismatch between the InvocationPolicy in the IOR and the chosen invocation path (i.e, direct or routed invocation).
TRANSACTION_REQUIRED	Exception indicates that the request carried a null transaction context, but an active transaction is required.
TRANSACTION_ROLLEDBACK	Exception thrown when the transaction associated with the request has already been rolled back or marked to roll back.
TRANSACTION_UNAVAILABLE	The CORBA TRANSACTION_UNAVAILABLE exception is thrown by the ORB when it cannot process a transaction service context because its connection to the Transaction Service has been abnormally terminated.
TRANSIENT	Exception thrown when the ORB attempted to reach an object and failed.
UNKNOWN	This exception is raised if an operation implementation throws a non-CORBA exception (such as an exception specific to the implementation's programming language), or if an operation raises a user exception that does not appear in the operation's raises expression.
UnknownUserException	A class that contains user exceptions returned by the server.
UserException	The root class for CORBA IDL-defined user exceptions.
WrongTransaction	The CORBA WrongTransaction user-defined exception.

Package org.omg.CORBA Description

Provides the mapping of the OMG CORBA 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).

For a precise list of supported sections of official CORBA specifications with which the Java 2 Platform, Standard Edition, v.1.4 complies, see Official Specifications for CORBA support in J2SE 1.4.

General Information

The information in this section is information relevant to someone who compiles Interface Definition Language (IDL) files and uses the ORB to write clients and servers.

The classes and interfaces described in this section can be put into four groups: ORB classes, Exceptions, Helper classes, and Holder classes.

The ORB Class

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.

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

Before an application can enter the CORBA environment, it must first:

• Be initialized into the ORB and possibly the object adapter (POA) environments.
• Get references to ORB object (for use in future ORB operations) and perhaps other objects (including the root POA or some Object Adapter objects).

The following operations are provided to initialize applications and obtain the appropriate object references:

• Operations providing access to the ORB, which are discussed in this section.
• Operations providing access to Object Adapters, Interface Repository, Naming Service, and other Object Services. These operations are described in Other Classes.

When an application requires a CORBA environment it needs a mechanism to get an ORB object reference and possibly an OA object reference (such as the root POA). This serves two purposes. First, it initializes an application into the ORB and OA environments. Second, it returns the ORB object reference and the OA object reference to the application for use in future ORB and OA operations.

In order to obtain an ORB object reference, applications call the ORB.init operation. The parameters to the call can comprise an identifier for the ORB for which the object reference is required, and an arg_list, which is used to allow environment-specific data to be passed into the call.

These are the ORB methods that provide access to the ORB:

• init()
• init(String [] args, Properties props)
• init(Applet app, Properties props)

Using the init() method without parameters initiates a singleton ORB, which can only give typecode creation anys needed in code generated in Helper classes by idlj.

Applications require a portable means by which to obtain their initial object references. References are required for the root POA, POA Current, Interface Repository, and various Object Services instances. The functionality required by the application is similar to that provided by the Naming Service. However, the OMG does not want to mandate that the Naming Service be made available to all applications in order that they may be portably initialized. Consequently, the operations shown in this section provide a simplified, local version of the Naming Service that applications can use to obtain a small, defined set of object references which are essential to its operation. Because only a small well-defined set of objects are expected with this mechanism, the naming context can be flattened to be a single-level name space. This simplification results in only two operations being defined to achieve the functionality required.

Initial references are obtained via two operations provided in the ORB object interface, providing facilities to list and resolve initial object references. These are:

• resolve_initial_references(String name)
• list_initial_services()
• register_initial_reference(String id, org.omg.CORBA.Object obj)

An example that uses some of these methods is Getting Started with Java IDL.

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 package org.omg.CORBA:

        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
        INV_POLICY
        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 
        PolicyError

Subpackages

There are some packages inside the CORBA package with "Package" as part of their names. These packages are generally quite small because all they do is provide exceptions or classes for use by interfaces and classes in the CORBA package.

For example, 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 two exceptions:

• InvalidName
• InconsistentTypeCode

Another package that is a subpackage of CORBA is the portable package. It provides a set of ORB APIs that makes it possible for code generated by one vendor's IDL compiler to run on another vendor's ORB.

Holder classes

Support for out and inout parameter passing modes requires the use of additional holder classes. Because the Java programming language does not support out or inout parameters, holder classes are needed as a means of passing a parameter that can be modified. To support portable stubs and skeletons, holder classes also implement the org.omg.CORBA.portable.Streamable interface.

Holder classes are named by appending "Holder" to the name of the type. The name of the type refers to its name in the Java programming language. For example, a holder class for the interface named Account in the Java programming language would be named AccountHolder.

Holder classes are available for all of the basic IDL datatypes in the org.omg.CORBA package. So, for example, there are already-defined classes for LongHolder, ShortHolder, FloatHolder, and so on. Classes are also generated for all named user-defined IDL types except those defined by typedefs. (Note that in this context user defined includes types that are defined in OMG specifications such as those for the Interface Repository, and other OMG services.)

Each holder class has:

• a constructor from an instance
• a default constructor
• a public instance member, value which is the typed value.
• a method for reading an input stream and assigning the contents to the type's value field
• a method for writing the value of the value field to an output stream
• a method for getting the typecode of the type

The default constructor sets the value field to the default value for the type as defined by the Java language:

• false for boolean
• 0 for numeric and char types
• null for strings and object references

As an example, if the interface Account, defined in OMG IDL, were mapped to the Java programming language, the following holder class would be generated:

public final class AccountHolder implements 
    org.omg.CORBA.portable.Streamable
{
  // field that holds an Account object
  public Account value = null;

  // default constructor
  public AccountHolder ()
  {
  }
  
  // creates a new AccountHolder from initialValue
  public AccountHolder (Account initialValue)
  {
    value = initialValue;
  }
  
  // reads the contents of i and assigns the contents to value
  public void _read (org.omg.CORBA.portable.InputStream i)
  {
    value = AccountHelper.read (i);
  }

  // writes value to o
  public void _write (org.omg.CORBA.portable.OutputStream o)
  {
    AccountHelper.write (o, value);
  }
 
  // returns the typecode for Account
  public org.omg.CORBA.TypeCode _type ()
  {
    return AccountHelper.type ();
  }

}

For more information on Holder classes, see Chapter 1.4, Mapping for Basic Types in the OMG IDL to Java Language Mapping. The Holder classes defined in the package org.omg.CORBA are:

     AnyHolder
     AnySeqHolder
     BooleanHolder
     BooleanSeqHolder
     ByteHolder
     CharHolder
     CharSeqHolder
     CurrentHolder
     DoubleHolder
     DoubleSeqHolder
     FixedHolder
     FloatHolder
     FloatSeqHolder
     IntHolder
     LongHolder
     LongLongSeqHolder
     LongSeqHolder
     ObjectHolder
     OctetSeqHolder
     ParameterModeHolder
     PolicyErrorHolder
     PolicyListHolder
     PrincipalHolder
     ServiceInformationHolder
     ShortHolder
     ShortSeqHolder
     StringHolder
     StringSeqHolder
     TypeCodeHolder
     ULongLongSeqHolder
     ULongSeqHolder
     UnknownUserExceptionHolder
     UShortSeqHolder
     ValueBaseHolder
     WCharSeqHolder
     WrongTransactionHolder
     WStringSeqHolder

Helper Classes

Helper files supply several static methods needed to manipulate the type. These include:

• Any insert and extract operations for the type
• getting the repository id
• getting the typecode
• reading and writing the type from and to a stream
• implement the ValueHelper interface (if it is a user-defined value type)

The helper class for a mapped IDL interface or abstract interface also include narrow operation(s). The static narrow method allows an org.omg.CORBA.Object to be narrowed to the object reference of a more specific type. The IDL exception CORBA.BAD_PARAM is thrown if the narrow fails because the object reference does not support the requested type. A different system exception is raised to indicate other kinds of errors. Trying to narrow a null will always succeed with a return value of null. Generally, the only helper method an application programmer uses is the narrow method. The other methods are normally used behind the scenes and are transparent to the programmer.

Helper classes fall into two broad categories, helpers for value types and helpers for non value types. Because all of the helper classes in one category provide the same methods, one generic explanation of each category of helper classes is presented here.

When OMG IDL is mapped to the Java programming language, a "helper" class is generated for each user-defined type. This generated class will have the name of the user-defined type with the suffix Helper appended. For example, if the interface Account is defined in OMG IDL, the idlj compiler will automatically generate a class named AccountHelper. The AccountHelper class will contain the static methods needed for manipulating instances of the type, in this case, Account objects.

The narrow Method

When an object is the return value for a method, it is returned in the form of a generic object, either an org.omg.CORBA.Object object or a java.lang.Object object. This object must be cast to its more specific type before it can be operated on. For example, an Account object will be returned as a generic object and must be narrowed to an Account object so that Account methods may be called on it.

The narrow method has two forms, one that takes an org.omg.CORBA.Object object and one that takes a java.lang.Object object. Whether the interface is abstract or not determines which narrow method its helper class will provide. The helper class for an interface that is not abstract will have a narrow method that takes a CORBA object, whereas the narrow method for an interface that is abstract will take an object in the Java programming language. The helper class for a non-abstract interface that has at least one abstract base interface will provide both versions of the narrow method.

The Hello World tutorial uses a narrow method that looks like this:

        // create and initialize the ORB
        ORB orb = ORB.init(args, null);

        // get the root naming context
        org.omg.CORBA.Object objRef = 
            orb.resolve_initial_references("NameService");
        // Use NamingContextExt instead of NamingContext. This is 
        // part of latest Inter-Operable naming Service.  
        NamingContextExt ncRef = NamingContextExtHelper.narrow(objRef);
 
        // resolve the Object Reference in Naming
        String name = "Hello";
        helloImpl = HelloHelper.narrow(ncRef.resolve_str(name));

Example of a Basic Helper Class

A basic helper class, for purposes of this explanation, is one with the methods that are provided by every helper class, plus a narrow method if the type defined in OMG IDL maps to an interface in the Java programming language. Types that are not value types will have a basic helper class generated for them.

For example, assuming that the interface Account is not a value type IDL type and is also not an abstract interface and has no abstract base interfaces, its AccountHelper class will look like this:

abstract public class AccountHelper
{
  private static String  _id = "IDL:Account:1.0";

  // inserts an Account object into an Any object
  public static void insert (org.omg.CORBA.Any a, Account that)
  {
    org.omg.CORBA.portable.OutputStream out = a.create_output_stream ();
    a.type (type ());
    write (out, that);
    a.read_value (out.create_input_stream (), type ());
  }

  // extracts an Account object from an Any object
  public static Account extract (org.omg.CORBA.Any a)
  {
    return read (a.create_input_stream ());
  }

  
  private static org.omg.CORBA.TypeCode __typeCode = null;
  // gets the typecode for this type
  synchronized public static org.omg.CORBA.TypeCode type ()
  {
    if (__typeCode == null)
    {
      __typeCode = org.omg.CORBA.ORB.init ().create_interface_tc (AccountHelper.id (), "Account");
    }
    return __typeCode;
  }

  // gets the repository id for this type
  public static String id ()
  {
    return _id;
  }

  // reads an Account object from an input stream
  public static Account read (org.omg.CORBA.portable.InputStream istream)
  {
    return narrow (istream.read_Object (_AccountStub.class));
  }

  // writes an Account object to an outputstream
  public static void write (org.omg.CORBA.portable.OutputStream ostream, Account value)
  {
    ostream.write_Object ((org.omg.CORBA.Object) value);
  }

  // converts (narrows) an Object to an Account object
  public static Account narrow (org.omg.CORBA.Object obj)
  {
    if (obj == null)
      return null;
    else if (obj instanceof Account)
      return (Account)obj;
    else if (!obj._is_a (id ()))
      throw new org.omg.CORBA.BAD_PARAM ();
    else
    {
      org.omg.CORBA.portable.Delegate delegate = ((org.omg.CORBA.portable.ObjectImpl)obj)._get_delegate ();
      _AccountStub stub = new _AccountStub ();
      stub._set_delegate(delegate);
      return stub;
    }
  }

}

Value Type Helper Classes

A helper class for a value type includes different renderings of the same methods generated for non-value type methods. The main difference is that value types are types that can be passed by value as parameters or return values of a method, which means that they must be serializable.

Assuming that Address is a value type, the AddressHelper class will look like this:

abstract public class AddressHelper
{
  private static String  _id = "IDL:Address:1.0";

  // same as for non-value type
  public static void insert (org.omg.CORBA.Any a, Address that)
  {
    org.omg.CORBA.portable.OutputStream out = a.create_output_stream ();
    a.type (type ());
    write (out, that);
    a.read_value (out.create_input_stream (), type ());
  }

  // same as for non-value type
  public static Address extract (org.omg.CORBA.Any a)
  {
    return read (a.create_input_stream ());
  }

  private static org.omg.CORBA.TypeCode __typeCode = null;
  private static boolean __active = false;
  
  // getting the typecode for the type
  synchronized public static org.omg.CORBA.TypeCode type ()
  {
    if (__typeCode == null)
    {
      synchronized (org.omg.CORBA.TypeCode.class)
      {
        if (__typeCode == null)
        {
          if (__active)
          {
            return org.omg.CORBA.ORB.init().create_recursive_tc ( _id );
          }
          __active = true;
          org.omg.CORBA.ValueMember[] _members0 = new org.omg.CORBA.ValueMember[0];
          org.omg.CORBA.TypeCode _tcOf_members0 = null;
          __typeCode = org.omg.CORBA.ORB.init ().create_value_tc (_id, "Address", org.omg.CORBA.VM_NONE.value, null, _members0);
          __active = false;
        }
      }
    }
    return __typeCode;
  }

  // same as for non-value type
  public static String id ()
  {
    return _id;
  }

  // reads a serializable instance of Address from the given input stream
  public static Address read (org.omg.CORBA.portable.InputStream istream)
  {
    return (Address)((org.omg.CORBA_2_3.portable.InputStream) istream).read_value (id ());
  }

  // writes a serializable instance of Address to the given output stream
  public static void write (org.omg.CORBA.portable.OutputStream ostream, Address value)
  {
    ((org.omg.CORBA_2_3.portable.OutputStream) ostream).write_value (value, id ());
  }


}

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

     AnySeqHelper
     BooleanSeqHelper
     CharSeqHelper
     CompletionStatusHelper
     CurrentHelper
     DefinitionKindHelper
     DoubleSeqHelper
     FieldNameHelper
     FloatSeqHelper
     IdentifierHelper
     IDLTypeHelper
     LongLongSeqHelper
     LongSeqHelper
     NameValuePairHelper
     ObjectHelper
     OctetSeqHelper
     ParameterModeHelper
     PolicyErrorCodeHelper
     PolicyErrorHelper
     PolicyHelper
     PolicyListHelper
     PolicyTypeHelper
     RepositoryIdHelper
     ServiceDetailHelper
     ServiceInformationHelper
     SetOverrideTypeHelper
     ShortSeqHelper
     StringSeqHelper
     StringValueHelper
     StructMemberHelper
     ULongLongSeqHelper
     ULongSeqHelper
     UnionMemberHelper
     UnknownUserExceptionHelper
     UShortSeqHelper
     ValueBaseHelper
     ValueMemberHelper
     VersionSpecHelper
     VisibilityHelper
     WCharSeqHelper
     WrongTransactionHelper
     WStringSeqHelper
     WStringValueHelper

Other Classes

The other classes and interfaces in the CORBA package, which are used behind the scenes, 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.

• 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

Interfaces That Serve as Constants

The third group contains interfaces that serve as constants. The IDL-to-Java mapping mandates that IDL enums are mapped to a Java class with the enumerated values represented as public static final fields in that class (e.g. DefinitionKind). On the other hand IDL constants defined outside of an IDL interface are mapped to a Java interface for each constant.

This is why several interfaces in the org.omg.CORBA package consist of a single field, value, which is a short. This field is a constant used for such things as an error code or value modifier. For example, the value field of the interface BAD_POLICY is one of the possible reasons for the exception PolicyError to be thrown. To specify this error code, you would use BAD_POLICY.value.

The exception PolicyError uses the value field of the following interfaces as its possible error codes.

• BAD_POLICY
• BAD_POLICY_TYPE
• BAD_POLICY_VALUE
• UNSUPPORTED_POLICY
• UNSUPPORTED_POLICY_VALUE

The method TypeCode.type_modifier returns the value field of one of the following interfaces. The VM in the names of these interfaces stands for "value modifier."

• VM_NONE
• VM_ABSTRACT
• VM_CUSTOM
• VM_TRUNCATABLE

The following constants are returned by a ValueMember object's access method to denote the visibility of the ValueMember object.

• PRIVATE_MEMBER
• PUBLIC_MEMBER

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 Interfaces and Classes

A fourth group contains the Interface Repository interfaces and classes, which are generated by the idlj compiler from the OMG IDL interface ir.idl. The purpose of the Interface Repository is to identify the interfaces stored in it so that they can be accessed by an ORB. Each module, type, interface, attribute, operation, parameter, exception, constant, and so on is described completely by the Interface Repository API.

An ORB does not require that there be an interface repository, and Java IDL does not include one. Even though this release does not include an implementation of an interface repository, the following IR classes and interfaces have been included for the purpose of creating typecodes (see create_value_tc, create_struct_tc, create_union_tc and create_exception_tc methods in interface org.omg.CORBA.ORB):
&nbs

• IRObject
• IDLType
• DefinitionKind
• StructMember
• UnionMember
• ValueMember

Related Documentation

For overviews, guides, and a tutorial, please see:

• Java IDL home page

CORBA Features Not Implemented in Java IDL

Some of the API included in org.omg subpackages is provided for conformance with the current OMG CORBA specification but is not implemented in Sun's release of the JDK^TM. This enables other JDK licensees to provide implementations of this API in standard extensions and products.

Features That Throw NO_IMPLEMENT

Some of the API included in org.omg subpackages throw NO_IMPLEMENT exceptions for various reasons. Among these reasons are:

• In some cases, for example LocalObject, the complete implementation according to the specification indicates that these API should throw NO_IMPLEMENT.

• In most cases, for example methods in ORB.java, methods that throw NO_IMPLEMENT are actually implemented in subclasses elsewhere in the ORB code.

• In some cases, for example _get_interface_def() and _get_interface, API are really not yet implemented.

General Summary of Features or API Not Implemented in This Release:

• Interface Repository. An Interface Repository is not required for normal operation of Java IDL.
• Java IDL does not support long double.
• Policies (org.omg.CORBA.Policy) and methods for getting them are not implemented.
• Domain managers (org.omg.CORBA.DomainManager) and methods for getting them are not implemented.
• Service Information org.omg.CORBA.ServiceInformation and ORB method public boolean get_service_information(short service_type, ServiceInformationHolder service_info) are not implemented.
• ORB methods for supporting single-threading (perform_work, work_pending) are not implemented.
• IDL contexts.

Specific List of Unimplemented Features in Package org.omg.CORBA

Unimplemented Methods in package org.omg.CORBA:

• ORB
  • public org.omg.CORBA.Policy create_policy(int type, org.omg.CORBA.Any val)
  • public void perform_work()
  • public boolean work_pending()
  • public org.omg.CORBA.Current get_current()
  • create_operation_list
  • get_default_context
  • get_service_information
  • obsolete DynAnys (deprecated in favor of DynamicAny package)

Since:

JDK1.2