For a precise list of supported sections of official CORBA specifications with which the Java[TM] Platform, Standard Edition 6 complies, see Official Specifications for CORBA support in Java[TM] SE 6.

General Information

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

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

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

• BadKind
• Bounds

• 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

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

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

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

Classes Created by an ORB

• 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

• 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

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

• VM_NONE
• VM_ABSTRACT
• VM_CUSTOM
• VM_TRUNCATABLE

• PRIVATE_MEMBER
• PUBLIC_MEMBER

• ARG_IN
• ARG_INOUT
• ARG_OUT
• CTX_RESTRICT_SCOPE

Interface Repository Interfaces and Classes

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

• 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)

Related Documentation

• comments on the CORBA package

CORBA Features Throwing NO_IMPLEMENT() Exceptions

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

Unimplemented Interfaces in package org.omg.CORBA.portable

• InvokeHandler
• ResponseHandler

Unimplemented Methods in package org.omg.CORBA.portable

• InputStream
  • public int read()
  • public.math.BigDecimal read_fixed()
  • public org.omg.CORBA.Context read_Context()
  • public org.omg.CORBA.Object read_Object(java.lang.Class clz)
  • public org.omg.CORBA.ORB orb()
• OutputStream
  • public org.omg.CORBA.ORB orb()
  • public void write_Context(org.omg.CORBA.Context ctx, org.omg.CORBA.ContextList contexts)
  • public void write_fixed(java.math.BigDecimal value)
  • public void write(int b)
• Delegate
  • public void releaseReply(org.omg.CORBA.Object self, InputStream input)
  • public InputStream invoke(org.omg.CORBA.Object self, OutputStream output)
  • public OutputStream request(org.omg.CORBA.Object self, String operation, boolean responseExpected)
  • public org.omg.CORBA.Object set_policy_override(org.omg.CORBA.Object self, org.omg.CORBA.Policy[] policies, org.omg.CORBA.SetOverrideType set_add)
  • public org.omg.CORBA.DomainManager[] get_domain_managers( org.omg.CORBA.Object self)
  • public org.omg.CORBA.Policy get_policy(org.omg.CORBA.Object self, int policy_type)

Related Documentation

• comments on the CORBA package

Package Specification

For a precise list of supported sections of official specifications with which the Java[tm] Platform, Standard Edition 6, ORB complies, see Official Specifications for CORBA support in Java[tm] SE 6.

The following methods in the abstract class org.omg.CORBA_2_3.ORB are unimplemented:

• public org.omg.CORBA.portable.ValueFactory register_value_factory(String id, org.omg.CORBA.portable.ValueFactory factory)
• public void unregister_value_factory(String id)
• public org.omg.CORBA.portable.ValueFactory lookup_value_factory(String id)
• public org.omg.CORBA.Object get_value_def(String repid)
• public void set_delegate(java.lang.Object wrapper)

@since 1.3 @serial exclude

The package and all its classes and interfaces were generated by running the tool idlj on the file nameservice.idl, which is a module written in OMG IDL.

Package Specification

For a precise list of supported sections of official specifications with which the Java[tm] Platform, Standard Edition 6, ORB complies, see Official Specifications for CORBA support in Java[tm] SE 6.

Interfaces

The interfaces are:

• NamingContext
• BindingIterator

These two interfaces provide the means to bind/unbind names and object references, to retrieve bound object references, and to iterate through a list of bindings. The NamingContext interface supplies the main functionality for the naming service, and BindingIterator provides a means of iterating through a list of name/object reference bindings.

Auxiliary Classes

Classes Used by NamingContext and BindingIterator

• public final class NameComponent -- a building block for names. (Names are bound to object references in a naming context.)

  A name is an array of one or more NameComponent objects. A name with a single NameComponent is called a simple name; a name with multiple NameComponent objects is called a compound name.

  A NameComponent object consists of two fields:

  1. id -- a String used as an identifier
  2. kind -- a String that can be used for any descriptive purpose. Its importance is that it can be used to describe an object without affecting syntax. The C programming language, for example, uses the the syntactic convention of appending the extension ".c" to a file name to indicate that it is a source code file. In a NameComponent object, the kind field can be used to describe the type of object rather than a file extension or some other syntactic convention. Examples of the value of the kind field include the strings "c_source", "object_code", "executable", "postscript", and "". It is not unusual for the kind field to be the empty string.

  In a name, each NameComponent object except the last denotes a NamingContext object; the last NameComponent object denotes the bound object reference. This is similar to a path name, in which the last name is the file name, and all names before it are directory names.

• public final class Binding -- an object that associates a name with an object reference or a naming context. A Binding object has two fields:
  1. binding_name - an array of one or more NameComponent objects that represents the bound name
  2. binding_type - a BindingType object indicating whether the binding is between a name and an object reference or between a name and a naming context

  The interface NamingContext has methods for binding/unbinding names with object references or naming contexts, for listing bindings, and for resolving bindings (given a name, the method resolve returns the object reference bound to it).

• public final class BindingType -- an object that specifies whether the given Binding object is a binding between a name and an object reference (that is, not a naming context) or between a name and a naming context.

  The classBindingType consists of two methods and four constants. Two of these constants are BindingType objects, and two are ints.

  The BindingType objects can be passed to the constructor for the class Binding or used as parameters or return values. These BindingType objects are:

  • public static final BindingType nobject -- to indicate that the binding is with an object reference
  • public static final BindingType ncontext -- to indicate that the binding is with a naming context

  The int constants can be supplied to the method from_int to create BindingType objects, or they can be return values for the method value. These constants are:

  • public static final int _nobject
  • public static final int _ncontext
  If the method from_int is supplied with anything other than _nobject or _ncontext, it will throw the exception org.omg.CORBA.BAD_PARAM.

  Usage is as follows:

         BindingType btObject = from_int(_nobject);
         BindingType btContext = from_int(_ncontext);
      

  The variable btObject refers to a BindingType object initialized to represent a binding with an object reference. The variable btContext refers to a BindingType object initialized to represent a binding with a NamingContex object.

  The method value returns either _nobject or _ncontext, so in the following line of code, the variable bt will contain _nobject or _ncontext:

         int bt = BindingType.value();
      

Holder Classes

The following holder classes are generated for the package org.omg.CosNaming:

• NamingContextHolder
• BindingIteratorHolder
• BindingHolder
• BindingListHolder
• BindingTypeHolder
• NameComponentHolder
• NameHolder

Note that in the org.omg.CORBA package, there is a holder class for each of the basic Java types: IntHolder, ShortHolder, StringHolder, and so on.

Note also that there is a NameHolder class even though there is no Name class; similarly, there is a BindingListHolder class even though there is no BindingList class. This is true because in the OMG IDL interface, Name and BindingList are typedefs. There is no mapping from an IDL typedef to a Java construct, but holder classes are generated if the typedef is for a sequence or an array. As mapped to the Java programming language, Name is an array of NameComponent objects, and a BindingList is an array of Binding objects. All holder classes have at least two constructors and one field:

• value field -- an instance of the type being used as an OUT or INOUT parameter. For example, the value field of a NamingContextHolder will be a NamingContext object.
• default constructor -- a constructor that creates a new holder object initialized with the default value for the type. For example, a new BindingHolder object created with the default constructor will have its value field set to null because that is the default value for an object. Other defaults are false for boolean, 0 for numeric and char types, and null for object references.
• constructor from an instance -- a constructor that creates a new holder object whose value field is initialized with the instance supplied

A holder class for a user-defined type (a Java class) has three more methods, but application developers do not use them directly.

Helper Classes

There is only one method in a helper class that an application programmer uses: the method narrow. Only Java interfaces mapped from IDL interfaces will have a helper class that includes a narrow method, so in the CosNaming package, only the classes NamingContextHelper and BindingIteratorHelper have a narrow method.

• public static NamingContext narrow(org.omg.CORBA.Object obj) -- converts the given CORBA object to a NamingContext object
• public static BindingIterator narrow(org.omg.CORBA.Object obj) -- converts the given CORBA object to a BindingIterator object

Package org.omg.CosNaming.NamingContextPackage

There are Helper and Holder classes for the following exceptions:

• AlreadyBound
• CannotProceed
• InvalidName
• NotEmpty
• NotFound

Naming Service Compatibility

Instructions for Using a Third Party's Naming Service

1. Create a properties file for the Bootstrap server and give it two entries. For example, you could call this properties file /tmp/services and put the following in it: NameService, <Stringified IOR of the Root Naming Context>.

   This associates NameService with the Root Naming Context of the CosNaming implementation that you want to use.

2. Start the standalone Bootstrap server using the following command:

         
         java -classpath $(CLASSPATH)
         com.sun.corba.ee.internal.CosNaming.BootstrapServer -InitialServicesFile
         "/tmp/services" [-ORBInitialPort port]
         
     

   Note that the square brackets at the end of the command indicate that specifying a port number is optional.

Now when an application calls the method org.omg.CORBA.ORB.resolve_initial_references, CORBA processes will contact the Bootstrap Server to get the Root Naming Context.

Package Specification

• Interoperable Naming Service (ptc/00-08-07)

Related Documentation

• Naming Service

For an overview of Java IDL, please see:

• Java IDL home page

In Java, Portable Object Adaptor (POA)-based Dynamic Skeleton Interface (DSI) servants inherit from the standard DynamicImplementation class, which inherits from the Servant class. The native Servant type is defined by the PortableServer module for the POA. In Java, the Servant type is mapped to the Java org.omg.PortableServer.Servant class. It serves as the base class for all POA servant implementations and provides a number of methods that may be invoked by the application programmer, as well as methods which are invoked by the POA itself and may be overridden by the user to control aspects of servant behavior.

Package Specification

For a precise list of supported sections of official OMG specifications with which the Java[tm] Platform, Standard Edition 6 complies, see Official Specifications for CORBA support in Java[tm] SE 6.

POA-related Interfaces

The PortableServer module defines the following POA-related interfaces:

• POA
• POAManager
• ServantManager
• ServantActivator
• ServantLocator
• AdapterActivator
• ThreadPolicy
• LifespanPolicy
• IdUniquenessPolicy
• IdAssignmentPolicy
• ImplicitActivationPolicy
• ServantRetentionPolicy
• RequestProcessingPolicy
• Current

In addition, the POA defines the Servant native type.

Operations classes

Each of the interfaces listed above has an associated Operations interface. The Operations interface is generated by the idlj compiler and contains the method signatures for methods defined in its associated interface. The Operations interface can be accessed by both the client and the server, while its associated interface can only be called by the client.

Value Classes

• IdAssignmentPolicyValue
• IdUniquenessPolicyValue
• ImplicitActivationPolicyValue
• LifespanPolicyValue
• RequestProcessingPolicyValue
• ServantRetentionPolicyValue
• ThreadPolicyValue

Helper Classes

Helper classes, which are generated for all user-defined types in an OMG IDL interface, supply static methods needed to manipulate those types. There is only one method in a helper class that an application programmer uses: the narrow method. Only Java interfaces mapped from IDL interfaces will have a helper class that includes a narrow method, so in the PortableServer package, only the following classes have a narrow method:

• ForwardRequestHelper
• ServantActivatorHelper
• ServantLocatorHelper

POA Classes

POA classes are used to implement the ServantActivator or ServantLocator.

Exceptions

The ForwardRequest exception indicates to the ORB that it is responsible for delivering the current request and subsequent ForwardRequest requests to the object denoted in the forward_reference member of the exception.

Interfaces Implemented by the Application Programmer

Most of what PortableServer does is transparent to the user. The result is that programmers will use only a few of the interfaces mentioned above. The remaining interfaces will be provided by the ORB implementation. The interfaces of interest to application programmers are the following:

• AdapterActivator

  Adapter activators are associated with POAs. An adapter activator supplies a POA with the ability to create child POAs on demand, as a side-effect of receiving a request that names the child POA (or one of its children), or when find_POA is called with an activate parameter value of TRUE. An application server that creates all its needed POAs at the beginning of execution does not need to use or provide an adapter activator; it is necessary only for the case in which POAs need to be created during request processing.

• ServantLocator

  When the POA has the NON_RETAIN policy, it uses servant managers that are ServantLocators.

• ServantActivator

  When the POA has the RETAIN policy, it uses servant managers that are ServantActivators.

Package org.omg.PortableServer.ServantLocatorPackage

This package supplies a CookieHolder class for passing the Cookie type as an out parameter. The CookieHolder class follows exactly the same pattern as the other holder classes for basic types.

Related Documentation

For an overview of Java IDL, please see:

import javax.naming.InitialContext;
import javax.naming.Context;
import javax.rmi.PortableRemoteObject ;
import com.sun.corba.se.impl.poa.POAORB;
import org.omg.PortableServer.*;
import java.util.*;
import org.omg.CORBA.*;
import javax.rmi.CORBA.Stub;
import javax.rmi.CORBA.Util;



public class HelloServer {
    public HelloServer(String[] args) {
        try {
            Properties p = System.getProperties();
         //   p.put("org.omg.CORBA.ORBClass", "com.sun.corba.ee.internal.POA.POAORB");
            ORB orb = ORB.init( args, p );

            POA rootPOA = (POA)orb.resolve_initial_references("RootPOA");

            Policy[] tpolicy = new Policy[3];
            tpolicy[0] = rootPOA.create_lifespan_policy(
                LifespanPolicyValue.TRANSIENT );
            tpolicy[1] = rootPOA.create_request_processing_policy(
                RequestProcessingPolicyValue.USE_ACTIVE_OBJECT_MAP_ONLY );
            tpolicy[2] = rootPOA.create_servant_retention_policy(
                ServantRetentionPolicyValue.RETAIN);
            POA tpoa = rootPOA.create_POA("MyTransientPOA", null, tpolicy);


            String  ObjectId = "MyObjectId";
            byte[] oid = ObjectId.getBytes();

            org.omg.CORBA.Object obj = tpoa.create_reference_with_id(oid,
                new _HelloImpl_Tie()._all_interfaces(tpoa, oid)[0]);
            HelloInterface helloRef = (HelloInterface)PortableRemoteObject.narrow(
                obj, HelloInterface.class );

            Context initialNamingContext = new InitialContext();
            initialNamingContext.rebind("HelloService", helloRef);
            System.out.println("Hello Server: Ready...");
            orb.run();
         } catch (Exception e) {
            System.out.println("Trouble: " + e);
            e.printStackTrace();
         } 
     }


     public static void main(String args[]) {
         new HelloServer( args );
     }
}

The portable package contains interfaces and classes that are designed for and intended to be used by an ORB implementor. It exposes the publicly defined APIs that are used to connect stubs and skeletons to the ORB. The Delegate interface provides the ORB-vendor-specific implementation of PortableServer::Servant. This package conforms CORBA Specification V2.3.1, ptc/00-01-08. @since 1.4
@serial exclude

This package supplies a CookieHolder class for passing the Cookie type as an out parameter. The CookieHolder class follows exactly the same pattern as the other holder classes for basic types.

Package Specification

For a precise list of supported sections of official OMG specifications with which the Java[tm] Platform, Standard Edition 6 complies, see Official Specifications for CORBA support in Java[tm] SE 6.

@since 1.4
@serial exclude

A sending context may be either the client side or the server side of an invocation, depending on which contains a value type. The sending context is the client side of an invocation if the request contains a value type. It is the server side if the reply contains a value type. The other party in the communication is the receiving context.

The service context marshalled for SendingContext consists of an encapsulated IOR for the SendingContext.RunTime interface. RunTime is just a marker interface defined to allow extensibility in the future. There is currently only one subinterface of RunTime defined: the SendingContext.CodeBase interface. The interface CodeBase defines operations to obtain code URLs and meta-information about a value type received from the sending context.

Note that these classes are currently defined in the com.sun.org.omg.SendingContext package rather than in the package org.omg.SendingContext. This has been done to avoid including large parts of the interface repository in the JDK core, since the interface repository is still evolving in response to the needs of the CORBA Components work.

Package Specification

For a precise list of supported sections of official specifications with which the Java[tm] Platform, Standard Edition 6 ORB complies, see Official Specifications for CORBA support in Java[tm] SE 6.

@since 1.3
@serial exclude

@since 1.3
@serial exclude