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.
The classes and interfaces described in this section can be put into
four groups: ORB classes
, Exceptions, Helper
classes,
and Holder
classes.
ORB
ClassAn 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
MethodsBefore an application can enter the CORBA environment, it must first:
The following operations are provided to initialize applications and obtain the appropriate object references:
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 any
s 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.
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
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
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.
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:
value
which is the typed value.
value
field
value
field to an output stream
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 files supply several static methods needed to manipulate the type. These include:
Any
insert and extract operations for the type
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.
narrow
Methodorg.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));
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; } } }
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
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.
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 TypeCode
s 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
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
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
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
ValueMember
object's
access method to denote the visibility of the ValueMember
object.
PRIVATE_MEMBER
PUBLIC_MEMBER
NamedValue
objects or as parameters to methods,
are defined in the following interfaces:
ARG_IN
ARG_INOUT
ARG_OUT
CTX_RESTRICT_SCOPE
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):
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™. This enables
other JDK licensees to provide implementations of this API in standard
extensions and products.
Some of the API included in org.omg
subpackages throw
NO_IMPLEMENT
exceptions for various reasons. Among these reasons
are:
LocalObject
, the complete
implementation according to the specification indicates that
these API should throw NO_IMPLEMENT
.
ORB.java
,
methods that throw
NO_IMPLEMENT
are actually implemented in subclasses
elsewhere in the ORB code.
_get_interface_def()
and _get_interface
, API are really not yet implemented.
long double
.
org.omg.CORBA.Policy
)
and methods for getting them are not implemented.
org.omg.CORBA.DomainManager
) and methods for
getting them are not implemented.
org.omg.CORBA.ServiceInformation
and ORB method
public boolean get_service_information(short service_type, ServiceInformationHolder service_info)
are not implemented.
perform_work
, work_pending
) are not implemented.
org.omg.CORBA
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
DynAnys
(deprecated in favor of DynamicAny
package)