Java Doc for ORB.java in  » 6.0-JDK-Modules-sun » omg » org » omg » CORBA » Java Source Code / Java DocumentationJava Source Code and Java Documentation

An ORB makes it possible for CORBA objects to communicate with each other by connecting objects making requests (clients) with objects servicing requests (servers).

The ORB class, which encapsulates generic CORBA functionality, does the following: (Note that items 5 and 6, which include most of the methods in the class ORB, are typically used with the Dynamic Invocation Interface (DII) and the Dynamic Skeleton Interface (DSI). These interfaces may be used by a developer directly, but most commonly they are used by the ORB internally and are not seen by the general programmer.)

1. initializes the ORB implementation by supplying values for predefined properties and environmental parameters
2. obtains initial object references to services such as the NameService using the method resolve_initial_references
3. converts object references to strings and back
4. connects the ORB to a servant (an instance of a CORBA object implementation) and disconnects the ORB from a servant
5. creates objects such as
   • TypeCode
   • Any
   • NamedValue
   • Context
   • Environment
   • lists (such as NVList) containing these objects
6. sends multiple messages in the DII

The ORB class can be used to obtain references to objects implemented anywhere on the network.

An application or applet gains access to the CORBA environment by initializing itself into an ORB using one of three init methods. Two of the three methods use the properties (associations of a name with a value) shown in the table below.

Standard Java CORBA Properties:

Property Name	Property Value
org.omg.CORBA.ORBClass	class name of an ORB implementation
org.omg.CORBA.ORBSingletonClass	class name of the ORB returned by init()

These properties allow a different vendor's ORB implementation to be "plugged in."

When an ORB instance is being created, the class name of the ORB implementation is located using the following standard search order:

1. check in Applet parameter or application string array, if any
2. check in properties parameter, if any
3. check in the System properties
4. check in the orb.properties file located in the user.home directory (if any)
5. check in the orb.properties file located in the java.home/lib directory (if any)
6. fall back on a hardcoded default behavior (use the Java IDL implementation)

Note that Java IDL provides a default implementation for the fully-functional ORB and for the Singleton ORB. When the method init is given no parameters, the default Singleton ORB is returned. When the method init is given parameters but no ORB class is specified, the Java IDL ORB implementation is returned.

The following code fragment creates an ORB object initialized with the default ORB Singleton. This ORB has a restricted implementation to prevent malicious applets from doing anything beyond creating typecodes. It is called a singleton because there is only one instance for an entire virtual machine.

 ORB orb = ORB.init();
 

The following code fragment creates an ORB object for an application. The parameter args represents the arguments supplied to the application's main method. Since the property specifies the ORB class to be "SomeORBImplementation", the new ORB will be initialized with that ORB implementation. If p had been null, and the arguments had not specified an ORB class, the new ORB would have been initialized with the default Java IDL implementation.

 Properties p = new Properties();
 p.put("org.omg.CORBA.ORBClass", "SomeORBImplementation");
 ORB orb = ORB.init(args, p);
 

The following code fragment creates an ORB object for the applet supplied as the first parameter. If the given applet does not specify an ORB class, the new ORB will be initialized with the default Java IDL implementation.

 ORB orb = ORB.init(myApplet, null);
 

An application or applet can be initialized in one or more ORBs. ORB initialization is a bootstrap call into the CORBA world.
version:
   1.70, 09/09/97
since:
   JDK1.2

Calling the method connect has no effect when the servant object is already connected to the ORB.

Deprecated by the OMG in favor of the Portable Object Adapter APIs.
Parameters:
  obj - The servant object reference

Parameters:
  type - the TypeCode object from which to create a newDynAny object the new DynAny object created from the givenTypeCode object
throws:
  org.omg.CORBA.ORBPackage.InconsistentTypeCode - if the givenTypeCode object is not consistent with the operation.
See Also:    CORBA package
See Also:   comments for unimplemented features

Parameters:
  value - the Any object from which to create a newDynAny object the new DynAny object created from the givenAny object
See Also:    CORBA package
See Also:   comments for unimplemented features

Parameters:
  type - the TypeCode object from which to create a newDynArray object the new DynArray object created from the givenTypeCode object
throws:
  org.omg.CORBA.ORBPackage.InconsistentTypeCode - if the givenTypeCode object is not consistent with the operation.
See Also:    CORBA package
See Also:   comments for unimplemented features

Parameters:
  type - the TypeCode object from which to create a newDynEnum object the new DynEnum object created from the givenTypeCode object
throws:
  org.omg.CORBA.ORBPackage.InconsistentTypeCode - if the givenTypeCode object is not consistent with the operation.
See Also:    CORBA package
See Also:   comments for unimplemented features

Parameters:
  type - the TypeCode object from which to create a newDynSequence object the new DynSequence object created from the givenTypeCode object
throws:
  org.omg.CORBA.ORBPackage.InconsistentTypeCode - if the givenTypeCode object is not consistent with the operation.
See Also:    CORBA package
See Also:   comments for unimplemented features

Parameters:
  type - the TypeCode object from which to create a newDynStruct object the new DynStruct object created from the givenTypeCode object
throws:
  org.omg.CORBA.ORBPackage.InconsistentTypeCode - if the givenTypeCode object is not consistent with the operation.
See Also:    CORBA package
See Also:   comments for unimplemented features

Parameters:
  type - the TypeCode object from which to create a newDynUnion object the new DynUnion object created from the givenTypeCode object
throws:
  org.omg.CORBA.ORBPackage.InconsistentTypeCode - if the givenTypeCode object is not consistent with the operation.
See Also:    CORBA package
See Also:   comments for unimplemented features

A NamedValue object serves as (1) a parameter or return value or (2) a context property. It may be used by itself or as an element in an NVList object.
Parameters:
  s - the name of the NamedValue object
Parameters:
  any - the Any value to be inserted into theNamedValue object
Parameters:
  flags - the argument mode flags for the NamedValue: one ofARG_IN.value, ARG_OUT.value,or ARG_INOUT.value. the newly-created NamedValue object
See Also:   NamedValue

For the IDL struct Node in following code fragment, the offset parameter for creating its sequence would be 1:

 Struct Node {
 long value;
 Sequence <Node> subnodes;
 };
 

For example, the following IDL type declaration contains recursion:

 Struct Node {
 Sequence<Node> subnodes;
 };
 

To create a TypeCode for struct Node, you would invoke the TypeCode creation operations as shown below:

 String nodeID = "IDL:Node:1.0";
 TypeCode recursiveSeqTC = orb.create_sequence_tc(0, orb.create_recursive_tc(nodeID));
 StructMember[] members = { new StructMember("subnodes", recursiveSeqTC, null) };
 TypeCode structNodeTC = orb.create_struct_tc(nodeID, "Node", members);
 

Also note that the following is an illegal IDL type declaration:

 Struct Node {
 Node next;
 };
 

Recursive types can only appear within sequences which can be empty. That way marshaling problems, when transmitting the struct in an Any, are avoided.

Parameters:
  id - the logical id of the referenced type the requested TypeCode

If destroy is called on an ORB that has not been shut down, it will start the shut down process and block until the ORB has shut down before it destroys the ORB.
If an application calls destroy in a thread that is currently servicing an invocation, the BAD_INV_ORDER system exception will be thrown with the OMG minor code 3, since blocking would result in a deadlock.

For maximum portability and to avoid resource leaks, an application should always call shutdown and destroy on all ORB instances before exiting.
throws:
  org.omg.CORBA.BAD_INV_ORDER - if the current thread is servicing an invocation

Calling the method disconnect has no effect if the servant is not connected to the ORB.

Deprecated by the OMG in favor of the Portable Object Adapter APIs.
Parameters:
  obj - The servant object to be disconnected from the ORB

Parameters:
  service_type - a short indicating theservice type for which information is being requested
Parameters:
  service_info - a ServiceInformationHolder objectthat will hold the ServiceInformation objectproduced by this method true if service information is availablefor the service_type; false if no information for therequested services type is available
See Also:    CORBA package
See Also:   comments for unimplemented features

This no-argument version of the method init is used primarily as a factory for TypeCode objects, which are used by Helper classes to implement the method type. It is also used to create Any objects that are used to describe union labels (as part of creating a TypeCode object for a union).

This method is not intended to be used by applets, and in the event that it is called in an applet environment, the ORB it returns is restricted so that it can be used only as a factory for TypeCode objects. Any TypeCode objects it produces can be safely shared among untrusted applets.

If an ORB is created using this method from an applet, a system exception will be thrown if methods other than those for creating TypeCode objects are invoked. the singleton ORB

The resulting String object may be stored or communicated in any way that a String object can be manipulated.
Parameters:
  obj - the object reference to stringify the string representing the object reference

While the ORB is in the process of shutting down, the ORB operates as normal, servicing incoming and outgoing requests until all requests have been completed. Once an ORB has shutdown, only object reference management operations may be invoked on the ORB or any object reference obtained from it. An application may also invoke the destroy operation on the ORB itself. Invoking any other operation will throw the BAD_INV_ORDER system exception with the OMG minor code 4.

The ORB.run method will return after shutdown has been called.
Parameters:
  wait_for_completion - true if the callshould block until the shutdown is complete;false if it should return immediately
throws:
  org.omg.CORBA.BAD_INV_ORDER - if the current thread is servicingan invocation