org.omg.CORBA.package.html Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of openjdk-orb Show documentation
JBoss repackaging of the OpenJDK ORB
The newest version!


   
   
   package



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[TM] Platform, Standard Edition 6 complies, see Official Specifications for CORBA support in 
Java[TM] SE 6.


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
@serial exclude
org.omg.CORBA.package.html Maven / Gradle / Ivy

General Information

The `ORB` Class

`ORB` Methods

Exceptions

Subpackages

Holder classes

Helper Classes

The `narrow` Method

Example of a Basic Helper Class

Value Type Helper Classes

Other Classes

Classes Created by an ORB

Classes That Deal with Requests

Interfaces That Serve as Constants

Interface Repository Interfaces and Classes

Related Documentation

CORBA Features Not Implemented in Java IDL

Features That Throw NO_IMPLEMENT

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

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

Unimplemented Methods in package `org.omg.CORBA`:
