duke@1: duke@1:
duke@1: duke@1: duke@1:For a precise list of supported sections of official CORBA specifications with which duke@1: the Java[TM] Platform, Standard Edition 6 complies, see Official Specifications for CORBA support in duke@1: Java[TM] SE 6. duke@1: duke@1: duke@1:
The classes and interfaces described in this section can be put into duke@1: four groups: ORB classes, Exceptions, Helper classes, duke@1: and Holder classes. duke@1: duke@1:
An ORB handles (or brokers) method invocations between a client and duke@1: the method's implementation on a server. Because the client and server duke@1: may be anywhere on a network, and because the invocation and implementation duke@1: may be written in different programming languages, an ORB does a great duke@1: deal of work behind the scenes to accomplish this communication. duke@1: duke@1:
Most of what an ORB does is completely transparent to the user, and a major duke@1: portion of the CORBA package consists of classes used by the ORB duke@1: behind the scenes. The result is that most programmers will use only a duke@1: small part of this package directly. In fact, most programmers will use duke@1: only a few methods from the ORB class, some exceptions, and duke@1: occasionally, duke@1: a holder class. duke@1:
Before an application can enter the CORBA environment, it must first: duke@1:
duke@1:
The following operations are provided to initialize applications and obtain duke@1: the appropriate object references: duke@1:
duke@1:
duke@1: When an application requires a CORBA environment it needs a mechanism to duke@1: get an ORB object reference and possibly an OA object reference duke@1: (such as the root POA). This serves two purposes. First, it initializes duke@1: an application into the ORB and OA environments. Second, it returns the duke@1: ORB object reference and the OA object reference to the application duke@1: for use in future ORB and OA operations. duke@1: duke@1:
In order to obtain an ORB object reference, applications call duke@1: the ORB.init operation. The parameters to the call can comprise an duke@1: identifier for the ORB for which the object reference is required, duke@1: and an arg_list, which is used to allow environment-specific data to be duke@1: passed into the call. duke@1: duke@1:
These are the ORB methods duke@1: that provide access to the ORB: duke@1:
Using the init() method without parameters initiates duke@1: a singleton ORB, which can only duke@1: give typecode creation anys needed in code generated duke@1: in Helper classes by idlj. duke@1: duke@1:
Applications require a portable means by which to obtain their duke@1: initial object references. References are required for the root duke@1: POA, POA Current, Interface Repository, and various Object Services duke@1: instances. The functionality required by the application is similar duke@1: to that provided by the Naming Service. However, the OMG does not duke@1: want to mandate that the Naming Service be made available to all duke@1: applications in order that they may be portably initialized. duke@1: Consequently, the operations shown in this section provide a duke@1: simplified, local version of the Naming Service that applications duke@1: can use to obtain a small, defined set of object references which duke@1: are essential to its operation. Because only a small well-defined duke@1: set of objects are expected with this mechanism, the naming context duke@1: can be flattened to be a single-level name space. This simplification duke@1: results in only two operations being defined to achieve the functionality duke@1: required. duke@1: duke@1:
Initial references are obtained via two operations provided in duke@1: the ORB object interface, providing facilities to list and duke@1: resolve initial object references. These are: duke@1:
An example that uses some of these methods is duke@1: Getting Started with Java IDL. duke@1: duke@1:
The documentation on Java duke@1: IDL exceptions has more information and explains the difference between duke@1: system exceptions and user-defined exceptions. duke@1: duke@1:
The following is a list of the system exceptions (which are unchecked duke@1: exceptions inheriting through duke@1: org.omg.CORBA.SystemException from duke@1: java.lang.RuntimeException) that are defined in the package duke@1: org.omg.CORBA: duke@1:
duke@1: BAD_CONTEXT
duke@1: BAD_INV_ORDER
duke@1: BAD_OPERATION
duke@1: BAD_PARAM
duke@1: BAD_TYPECODE
duke@1: COMM_FAILURE
duke@1: DATA_CONVERSION
duke@1: FREE_MEM
duke@1: IMP_LIMIT
duke@1: INITIALIZE
duke@1: INTERNAL
duke@1: INTF_REPOS
duke@1: INVALID_TRANSACTION
duke@1: INV_FLAG
duke@1: INV_IDENT
duke@1: INV_OBJREF
duke@1: INV_POLICY
duke@1: MARSHAL
duke@1: NO_IMPLEMENT
duke@1: NO_MEMORY
duke@1: NO_PERMISSION
duke@1: NO_RESOURCES
duke@1: NO_RESPONSE
duke@1: OBJECT_NOT_EXIST
duke@1: OBJ_ADAPTER
duke@1: PERSIST_STORE
duke@1: TRANSACTION_REQUIRED
duke@1: TRANSACTION_ROLLEDBACK
duke@1: TRANSIENT
duke@1: UNKNOWN
duke@1:
duke@1: duke@1: The following is a list of user-defined exceptions defined in the package duke@1: org.omg.CORBA. duke@1:
duke@1: Bounds
duke@1: UnknownUserException
duke@1: WrongTransaction
duke@1: PolicyError
duke@1:
duke@1:
duke@1: For example, the package duke@1: org.omg.CORBA.TypeCodePackage contains duke@1: two exceptions thrown by methods in the class TypeCode. These duke@1: exceptions are: duke@1:
Another package that is a subpackage of CORBA is the duke@1: portable package. It duke@1: provides a set of ORB APIs that makes it duke@1: possible for code generated by one vendor's IDL compiler to run duke@1: on another vendor's ORB. duke@1: duke@1: duke@1: duke@1: duke@1:
Support for out and inout parameter passing modes requires the use of duke@1: additional holder duke@1: classes. Because the Java programming language does not support out or duke@1: inout parameters, holder classes are needed as a means of passing a parameter duke@1: that can be modified. To support portable stubs and skeletons, holder classes also implement duke@1: the org.omg.CORBA.portable.Streamable duke@1: interface. duke@1: duke@1:
Holder classes are named by appending "Holder" to the name of the type. duke@1: The name of the type refers to its name in the Java programming language. For duke@1: example, a holder class for the interface named Account in the Java programming duke@1: language would be named AccountHolder. duke@1: duke@1: duke@1:
Holder classes are available for all of the basic IDL duke@1: datatypes in the org.omg.CORBA package. So, for example, duke@1: there are already-defined classes for LongHolder, ShortHolder, duke@1: FloatHolder, and so on. Classes are also generated for duke@1: all named user-defined IDL types except those defined by typedefs. duke@1: (Note that in this context user defined includes types that are duke@1: defined in OMG specifications such as those for the Interface duke@1: Repository, and other OMG services.) duke@1: duke@1: duke@1:
Each holder class has: duke@1:
duke@1:
The default constructor sets the value field to the default value for the duke@1: type as defined by the Java language: duke@1:
duke@1:
duke@1: As an example, if the interface Account
, defined in OMG IDL,
duke@1: were mapped to the Java programming language, the following holder class
duke@1: would be generated:
duke@1:
duke@1: public final class AccountHolder implements duke@1: org.omg.CORBA.portable.Streamable duke@1: { duke@1: // field that holds an Account object duke@1: public Account value = null; duke@1: duke@1: // default constructor duke@1: public AccountHolder () duke@1: { duke@1: } duke@1: duke@1: // creates a new AccountHolder from initialValue duke@1: public AccountHolder (Account initialValue) duke@1: { duke@1: value = initialValue; duke@1: } duke@1: duke@1: // reads the contents of i and assigns the contents to value duke@1: public void _read (org.omg.CORBA.portable.InputStream i) duke@1: { duke@1: value = AccountHelper.read (i); duke@1: } duke@1: duke@1: // writes value to o duke@1: public void _write (org.omg.CORBA.portable.OutputStream o) duke@1: { duke@1: AccountHelper.write (o, value); duke@1: } duke@1: duke@1: // returns the typecode for Account duke@1: public org.omg.CORBA.TypeCode _type () duke@1: { duke@1: return AccountHelper.type (); duke@1: } duke@1: duke@1: } duke@1:duke@1: duke@1:
For more information on Holder classes, see Chapter 1.4, Mapping for duke@1: Basic Types in the duke@1: OMG IDL to Java Language Mapping. The Holder classes defined duke@1: in the package org.omg.CORBA are: duke@1:
duke@1: AnyHolder duke@1: AnySeqHolder duke@1: BooleanHolder duke@1: BooleanSeqHolder duke@1: ByteHolder duke@1: CharHolder duke@1: CharSeqHolder duke@1: CurrentHolder duke@1: DoubleHolder duke@1: DoubleSeqHolder duke@1: FixedHolder duke@1: FloatHolder duke@1: FloatSeqHolder duke@1: IntHolder duke@1: LongHolder duke@1: LongLongSeqHolder duke@1: LongSeqHolder duke@1: ObjectHolder duke@1: OctetSeqHolder duke@1: ParameterModeHolder duke@1: PolicyErrorHolder duke@1: PolicyListHolder duke@1: PrincipalHolder duke@1: ServiceInformationHolder duke@1: ShortHolder duke@1: ShortSeqHolder duke@1: StringHolder duke@1: StringSeqHolder duke@1: TypeCodeHolder duke@1: ULongLongSeqHolder duke@1: ULongSeqHolder duke@1: UnknownUserExceptionHolder duke@1: UShortSeqHolder duke@1: ValueBaseHolder duke@1: WCharSeqHolder duke@1: WrongTransactionHolder duke@1: WStringSeqHolder duke@1: duke@1:duke@1: duke@1:
Helper files supply several static methods needed to manipulate the type. duke@1: These include: duke@1:
duke@1:
ValueHelper
interface (if it is a user-defined
duke@1: value type)
duke@1: The helper class for a mapped IDL interface or abstract interface
duke@1: also include narrow operation(s). The static narrow method allows
duke@1: an org.omg.CORBA.Object to be narrowed to the object reference
duke@1: of a more specific type. The IDL exception CORBA.BAD_PARAM
duke@1: is thrown if the narrow fails because the object reference does not
duke@1: support the requested type. A different system exception is raised
duke@1: to indicate other kinds of errors. Trying to narrow a null will always
duke@1: succeed with a return value of null. Generally, the only helper method an application programmer uses is
duke@1: the narrow
method. The other methods are normally used behind
duke@1: the scenes and are transparent to the programmer.
duke@1:
duke@1:
Helper classes duke@1: fall into two broad categories, helpers for value types and duke@1: helpers for non value types. Because all of the helper duke@1: classes in one category duke@1: provide the same methods, one generic explanation of each duke@1: category of helper classes is presented here. duke@1: duke@1:
duke@1: When OMG IDL is mapped to the Java programming language,
duke@1: a "helper" class is generated for each user-defined type.
duke@1: This generated class will have the name of the user-defined type with
duke@1: the suffix Helper
appended. For example, if the
duke@1: interface Account
is defined in OMG IDL, the
duke@1: idlj
compiler will automatically generate a class named
duke@1: AccountHelper
. The AccountHelper
class
duke@1: will contain the static methods needed for manipulating instances of the type,
duke@1: in this case, Account
objects.
duke@1:
duke@1:
duke@1:
duke@1:
narrow
Methodorg.omg.CORBA.Object
object
duke@1: or a java.lang.Object
object. This object must be cast to its
duke@1: more specific type before it can be operated on. For example, an
duke@1: Account
object will be returned as a generic object and must
duke@1: be narrowed to an Account
object so that Account
duke@1: methods may be called on it.
duke@1:
duke@1: The narrow
method has two forms, one that takes an
duke@1: org.omg.CORBA.Object
object and one that takes a
duke@1: java.lang.Object
object. Whether the interface is abstract or
duke@1: not determines which narrow
method its helper class will provide.
duke@1: The helper class for an interface
duke@1: that is not abstract will have a narrow
method that takes a CORBA
duke@1: object, whereas the narrow
method for an interface that is abstract
duke@1: will
duke@1: take an object in the Java programming language. The helper class for a
duke@1: non-abstract interface that has at least one abstract base interface will provide
duke@1: both versions of the narrow
method.
duke@1:
The Hello World duke@1: tutorial uses a narrow method that looks duke@1: like this: duke@1:
duke@1:
duke@1: // create and initialize the ORB duke@1: ORB orb = ORB.init(args, null); duke@1: duke@1: // get the root naming context duke@1: org.omg.CORBA.Object objRef = duke@1: orb.resolve_initial_references("NameService"); duke@1: // Use NamingContextExt instead of NamingContext. This is duke@1: // part of latest Inter-Operable naming Service. duke@1: NamingContextExt ncRef = NamingContextExtHelper.narrow(objRef); duke@1: duke@1: // resolve the Object Reference in Naming duke@1: String name = "Hello"; duke@1: helloImpl = HelloHelper.narrow(ncRef.resolve_str(name)); duke@1:duke@1: duke@1: duke@1:
narrow
duke@1: method if the type defined in OMG IDL maps to an interface in the Java
duke@1: programming language. Types that are not value types will have a basic
duke@1: helper class generated for them.
duke@1:
duke@1: For example, assuming that the interface Account
is not a
duke@1: value type IDL type and is also not an abstract interface and has no
duke@1: abstract base interfaces, its AccountHelper
class will look
duke@1: like this:
duke@1:
duke@1: abstract public class AccountHelper duke@1: { duke@1: private static String _id = "IDL:Account:1.0"; duke@1: duke@1: // inserts an Account object into an Any object duke@1: public static void insert (org.omg.CORBA.Any a, Account that) duke@1: { duke@1: org.omg.CORBA.portable.OutputStream out = a.create_output_stream (); duke@1: a.type (type ()); duke@1: write (out, that); duke@1: a.read_value (out.create_input_stream (), type ()); duke@1: } duke@1: duke@1: // extracts an Account object from an Any object duke@1: public static Account extract (org.omg.CORBA.Any a) duke@1: { duke@1: return read (a.create_input_stream ()); duke@1: } duke@1: duke@1: duke@1: private static org.omg.CORBA.TypeCode __typeCode = null; duke@1: // gets the typecode for this type duke@1: synchronized public static org.omg.CORBA.TypeCode type () duke@1: { duke@1: if (__typeCode == null) duke@1: { duke@1: __typeCode = org.omg.CORBA.ORB.init ().create_interface_tc (AccountHelper.id (), "Account"); duke@1: } duke@1: return __typeCode; duke@1: } duke@1: duke@1: // gets the repository id for this type duke@1: public static String id () duke@1: { duke@1: return _id; duke@1: } duke@1: duke@1: // reads an Account object from an input stream duke@1: public static Account read (org.omg.CORBA.portable.InputStream istream) duke@1: { duke@1: return narrow (istream.read_Object (_AccountStub.class)); duke@1: } duke@1: duke@1: // writes an Account object to an outputstream duke@1: public static void write (org.omg.CORBA.portable.OutputStream ostream, Account value) duke@1: { duke@1: ostream.write_Object ((org.omg.CORBA.Object) value); duke@1: } duke@1: duke@1: // converts (narrows) an Object to an Account object duke@1: public static Account narrow (org.omg.CORBA.Object obj) duke@1: { duke@1: if (obj == null) duke@1: return null; duke@1: else if (obj instanceof Account) duke@1: return (Account)obj; duke@1: else if (!obj._is_a (id ())) duke@1: throw new org.omg.CORBA.BAD_PARAM (); duke@1: else duke@1: { duke@1: org.omg.CORBA.portable.Delegate delegate = ((org.omg.CORBA.portable.ObjectImpl)obj)._get_delegate (); duke@1: _AccountStub stub = new _AccountStub (); duke@1: stub._set_delegate(delegate); duke@1: return stub; duke@1: } duke@1: } duke@1: duke@1: } duke@1:duke@1:
duke@1: duke@1:
Assuming that Address
is a value type, the
duke@1: AddressHelper
class will look like this:
duke@1:
duke@1: abstract public class AddressHelper duke@1: { duke@1: private static String _id = "IDL:Address:1.0"; duke@1: duke@1: // same as for non-value type duke@1: public static void insert (org.omg.CORBA.Any a, Address that) duke@1: { duke@1: org.omg.CORBA.portable.OutputStream out = a.create_output_stream (); duke@1: a.type (type ()); duke@1: write (out, that); duke@1: a.read_value (out.create_input_stream (), type ()); duke@1: } duke@1: duke@1: // same as for non-value type duke@1: public static Address extract (org.omg.CORBA.Any a) duke@1: { duke@1: return read (a.create_input_stream ()); duke@1: } duke@1: duke@1: private static org.omg.CORBA.TypeCode __typeCode = null; duke@1: private static boolean __active = false; duke@1: duke@1: // getting the typecode for the type duke@1: synchronized public static org.omg.CORBA.TypeCode type () duke@1: { duke@1: if (__typeCode == null) duke@1: { duke@1: synchronized (org.omg.CORBA.TypeCode.class) duke@1: { duke@1: if (__typeCode == null) duke@1: { duke@1: if (__active) duke@1: { duke@1: return org.omg.CORBA.ORB.init().create_recursive_tc ( _id ); duke@1: } duke@1: __active = true; duke@1: org.omg.CORBA.ValueMember[] _members0 = new org.omg.CORBA.ValueMember[0]; duke@1: org.omg.CORBA.TypeCode _tcOf_members0 = null; duke@1: __typeCode = org.omg.CORBA.ORB.init ().create_value_tc (_id, "Address", org.omg.CORBA.VM_NONE.value, null, _members0); duke@1: __active = false; duke@1: } duke@1: } duke@1: } duke@1: return __typeCode; duke@1: } duke@1: duke@1: // same as for non-value type duke@1: public static String id () duke@1: { duke@1: return _id; duke@1: } duke@1: duke@1: // reads a serializable instance of Address from the given input stream duke@1: public static Address read (org.omg.CORBA.portable.InputStream istream) duke@1: { duke@1: return (Address)((org.omg.CORBA_2_3.portable.InputStream) istream).read_value (id ()); duke@1: } duke@1: duke@1: // writes a serializable instance of Address to the given output stream duke@1: public static void write (org.omg.CORBA.portable.OutputStream ostream, Address value) duke@1: { duke@1: ((org.omg.CORBA_2_3.portable.OutputStream) ostream).write_value (value, id ()); duke@1: } duke@1: duke@1: duke@1: } duke@1:duke@1: duke@1:
The Helper classes defined in the package org.omg.CORBA are: duke@1:
duke@1: AnySeqHelper
duke@1: BooleanSeqHelper
duke@1: CharSeqHelper
duke@1: CompletionStatusHelper
duke@1: CurrentHelper
duke@1: DefinitionKindHelper
duke@1: DoubleSeqHelper
duke@1: FieldNameHelper
duke@1: FloatSeqHelper
duke@1: IdentifierHelper
duke@1: IDLTypeHelper
duke@1: LongLongSeqHelper
duke@1: LongSeqHelper
duke@1: NameValuePairHelper
duke@1: ObjectHelper
duke@1: OctetSeqHelper
duke@1: ParameterModeHelper
duke@1: PolicyErrorCodeHelper
duke@1: PolicyErrorHelper
duke@1: PolicyHelper
duke@1: PolicyListHelper
duke@1: PolicyTypeHelper
duke@1: RepositoryIdHelper
duke@1: ServiceDetailHelper
duke@1: ServiceInformationHelper
duke@1: SetOverrideTypeHelper
duke@1: ShortSeqHelper
duke@1: StringSeqHelper
duke@1: StringValueHelper
duke@1: StructMemberHelper
duke@1: ULongLongSeqHelper
duke@1: ULongSeqHelper
duke@1: UnionMemberHelper
duke@1: UnknownUserExceptionHelper
duke@1: UShortSeqHelper
duke@1: ValueBaseHelper
duke@1: ValueMemberHelper
duke@1: VersionSpecHelper
duke@1: VisibilityHelper
duke@1: WCharSeqHelper
duke@1: WrongTransactionHelper
duke@1: WStringSeqHelper
duke@1: WStringValueHelper
duke@1:
duke@1:
duke@1:
duke@1: This is why several interfaces in the org.omg.CORBA package duke@1: consist of a single field, value, which is a short. This duke@1: field is a constant used for such things as an error code or value modifier. duke@1: For example, the value field of the interface BAD_POLICY duke@1: is one of the possible reasons for the exception PolicyError to duke@1: be thrown. To specify this error code, you would use BAD_POLICY.value. duke@1: duke@1:
The exception PolicyError uses the value field of duke@1: the following interfaces as its possible error codes. duke@1:
ValueMember
object's
duke@1: access method to denote the visibility of the ValueMember
object.
duke@1: An ORB does not require that there be an interface repository, and Java
duke@1: IDL does not include one. Even though this release does not include an
duke@1: implementation of an interface repository, the following IR classes and
duke@1: interfaces have been included for the purpose of creating typecodes (see
duke@1: create_value_tc, create_struct_tc, create_union_tc and create_exception_tc
duke@1: methods in interface org.omg.CORBA.ORB):
duke@1:
&nbs
duke@1:
Some of the API included in org.omg subpackages is provided for duke@1: conformance with the current OMG CORBA specification but is not implemented duke@1: in Sun's release of the JDKTM. This enables duke@1: other JDK licensees to provide implementations of this API in standard duke@1: extensions and products. duke@1: duke@1:
Some of the API included in org.omg subpackages throw duke@1: NO_IMPLEMENT exceptions for various reasons. Among these reasons duke@1: are: duke@1:
duke@1:
duke@1:
duke@1: