
	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	e-docs.beasys.com \| Site Map \| Search \| PDF Files \| Contact \| Glossary

WLE Doc Home \| CORBA Programming & Related Topics \| Previous \| Next \| Contents \| Index

Joint Client/Server Applications

This chapter contains the following topics:

Introduction. This section includes the following topics:
Callbacks Interface API

This chapter describes programming requirements for joint client/server applications. For a description of the BEAWrapper package and the Callbacks interface API, see the Javadoc.

Introduction

For either a WebLogic Enterprise client applications or a joint client/server application (that is, a client that can receive and process object invocations), create a Java client main() method. The main() method uses WebLogic Enterprise environmental objects to establish connections, set up security, and start transactions.

WebLogic Enterprise clients invoke operations on objects. In the case of DII, client code creates the DII Request object and then invokes one of two operations on the DII Request. In the case of static invocation, client code performs the invocation by performing what looks like an ordinary Java invocation (which ends up calling code in the generated client stub). Additionally, the client programmer uses ORB interfaces defined by OMG and WebLogic Enterprise environmental objects that are supplied with the WebLogic Enterprise software to perform functions unique to WebLogic Enterprise.

For WebLogic Enterprise joint client/server applications, the client code must be structured so that it can act as a server for callback WebLogic Enterprise objects only. Such clients do not use the TP Framework and are not subject to WebLogic Enterprise system administration. Besides the programming implications, this means that joint client/server applications do not have the same scalability and reliability as WebLogic Enterprise servers, nor do they have the state management and transaction behavior available in the TP Framework. If a user wants to have those characteristics, the application must be structured in such a way that the object implementations are in a WebLogic Enterprise server, rather than in a client.

The following sections describe the mechanisms you use to add callback support to a WebLogic Enterprise client. In some cases, the mechanisms are contrasted with the WebLogic Enterprise server mechanisms that use the TP Framework.

interface Hospital{  };

The skeleton generated by idltojava contains a skeleton class, _HospitalImplBase , from which the user-written class inherits, as in:

class HospitalImpl extends _HospitalImplBase {};

In a WLE server application, the skeleton class inherits from the TP Framework class com.beasys.Tobj_Servant , which in turn inherits from the CORBA-defined class org.omg.PortableServer.Servant .

The inheritance tree for a callback object implementation in a joint client/server application is different from that of a client. The skeleton class does not inherit from the TP Framework class, but instead inherits from the org.omg.CORBA.DynamicImplementation class, which in turn inherits from the org.omg.CORBA.portable.ObjectImpl class.

Not having the Tobj_Servant class in the inheritance tree for a servant means that the servant does not have the activate_object and deactivate_object methods. In a WLE server application, these methods are invoked by the TP Framework to dynamically initialize and save a servant's state before invoking a method on the servant. For a joint client/server application, user code must explicitly create a servant and initialize a servant's state; therefore, the Tobj_Servant operations are not needed.

Callback Object Models Supported

WebLogic Enterprise software supports the three kinds of callback objects. These object types are described here primarily in terms of their behavioral characteristics rather than in the details about how the ORB and the wrapper classes handle them.

The three kinds of callback objects are:

Transient/SystemId
Object references are valid only for the life of the client process. The objectId is not assigned by the client application, but is a unique value assigned by the system. This type of object is useful for invocations that a client wants to receive only until the client terminates. If used with a Notification or Event Service, for example, these are callbacks that correspond to the concept of transient events and transient channels. (The corresponding POA LifeSpanPolicy value is TRANSIENT , and the IdAssignmentPolicy is SYSTEM_ID .)
Persistent/SystemId
Object references are valid across multiple activations. The objectId is not assigned by the client application, but is a unique value assigned by the system. This type of object and object reference is useful when the client goes up and down over a period of time. When the client is up, it can receive callback objects on that particular object reference. Typically, the client creates the object reference once, saves it in its own permanent storage area, and reactivates the servant for that object every time the client comes up. If used with a Notification Service, for example, these are callbacks that correspond to the concept of a persistent subscription; that is, the Notification Service remembers the callback reference and delivers events any time the client is up and declares that it is again ready to receive them. This allows notification to survive client failures or offline-time. (The corresponding POA policy values are PERSISTENT and SYSTEM_ID .)
Persistent/UserId
This is the same as Persistent/SystemId, except that the objectId has to be assigned by the client application. Such an objectId might be, for example, a database key meaningful only to the client. (The corresponding POA policy values are PERSISTENT and USER_ID .)
Note: The Transient/UserId policy combination is not considered particularly important. In any event, this policy combination is not available in Java server applications.
Note: For WebLogic Enterprise native joint client/server applications, neither of the Persistent policies is supported, only the Transient policy.

In C++, these object models are established by using combinations of the following POA policies, which control both the types of objects and the types of object references that are possible:

LifeSpanPolicy, which controls how long an object reference is valid
IdAssignmentPolicy, which controls who assigns the objectId -the user or the system

However, since the ORB used for Java server applications does not provide a POA, the WLE system provides a Callbacks wrapper class that emulates these POA policies.

Preparing Callback Objects using BEAWrapper Callbacks

Because the code to prepare for callback objects is nearly identical for every joint client/server application, and because the Java JDK ORB does not implement a POA, WLE provides a wrapper class in the joint client/server library that is virtually identical to the wrapper class provided in C++. This wrapper class emulates the POA policies needed to support the three types of callback objects.

The following code shows the Callback wrapper interfaces.

package com.beasys.BEAWrapper;

       class Callbacks{
             public Callbacks ();

             public Callbacks (org.omg.CORBA.Object init_orb);

             public org.omg.CORBA.Object start_transient (
                                 org.omg.PortableServer.ObjectImpl servant,
                                 java.lang.String rep_id)
                                 throws ServantAlreadyActive,
                                        org.omg.CORBA.BAD_PARAMETER;

             public org.omg.CORBA.Object start_persistent_systemid (
                                 org.omg.PortableServer.ObjectImpl servant,
                                 java.lang.String rep_id,
                                 org.omg.CORBA.StringHolder stroid)
                                 throws ServantAlreadyActive,
                                        org.omg.CORBA.BAD_PARAMETER,
                                        org.omg.CORBA.IMP_LIMIT;

             public org.omg.CORBA.Object restart_persistent_systemid (
                                 org.omg.PortableServer.ObjectImpl servant,
                                 java.lang.String rep_id,
                                 java.lang.String stroid)
                                 throws ServantAlreadyActive,
                                        ObjectAlreadyActive,
                                        org.omg.CORBA.BAD_PARAMETER,
                                        org.omg.CORBA.IMP_LIMIT;

             public org.omg.CORBA.Object start_persistent_userid (
                                 org.omg.PortableServer.ObjectImpl servant,
                                 java.lang.String rep_id,
                                 java.lang.String stroid) 
                                 throws ServantAlreadyActive,
                                        ObjectAlreadyActive,
                                        org.omg.CORBA.BAD_PARAMETER,
                                        org.omg.CORBA.IMP_LIMIT;
             public void stop_object(
                                 org.omg.PortableServer.ObjectImpl
                                                         servant);

             public String get_string_oid ()
                                 throws NotInRequest;

             public void stop_all_objects();
};

Threading Considerations in the Main Program

When a program acts as both a client and a server in a Java client, those two parts can execute concurrently in different threads. Since Java as an execution environment is inherently multithreaded, there is no reason to invoke the org.omg.CORBA.orb.work_pending and org.omg.CORBA.orb.perform_work methods from a Java client. In fact, if the Java client tries to invoke these methods, these methods throw an org.omg.CORBA.NO_IMPLEMENT exception. The client does not need to invoke the org.omg.CORBA.orb.run method. As in any multithreaded environment, any code that may execute concurrently (client and servant code for a callback) in the client application must be coded to be thread safe. This is a departure from C++ clients, which are currently single-threaded.

Multiple Threads

In Java, the client starts up in the main thread. The client can then set up callback objects via an invocation to any of the (re) start_ xxxx methods provided by the Callbacks wrapper class. The wrapper class handles registering the servant and its associated OID in the ORB's object manager. The application is then free to pass the object reference returned by the (re) start_ xxxx method to an application that needs to call back to the servant.

Note: The ORB requires an explicit invocation to one of the (re) start_ xxxx methods to effectively initialize the servant and create a valid object reference that can be marshaled properly to another application. This is a deviation from the base JDK 1.2 ORB behavior that allows implicit object reference creation via an internal invocation to the orb.connect method when marshaling an object reference, if the application has not yet done so.

Invocations on the callback object are handled by the ORB. As each request is received, the ORB validates the request against the object manager and spawns a thread for that request. Multiple requests can be made simultaneously to the same object because the ORB creates a new thread for each request; that is why the Servant code of the Callback must be written thread safe. As each request terminates, the thread that runs the servant also terminates.

The main client thread can make as many client invocations as necessary. An invocation to the stop_ (all_) object methods merely takes the object out of the object manager's list, thereby preventing any further invocations on it. Any invocation to a stopped object fails as if it never existed.

If the client application needs to retrieve the results of a callback from another thread, the client application must use normal thread synchronization techniques to do so.

If any thread (client main or servant) in the WLE remote-like client application exits, all the client process activity is stopped, and the Java execution environment terminates. We recommend only to invoke the return method to terminate a thread.

Java Client ORB Initialization

A client application must initialize the ORB with the BEA-supplied properties. This is so that the ORB will utilize the BEA-supplied classes and methods that support the Callbacks wrapper class and the Bootstrap object. You can find these classes in wleclient.jar , which is installed in $TUXDIR/udataobj/java/jdk (on Solaris) or %TUXDIR%\udataobj\java\jdk (on Windows NT). The application must set certain system properties to do this, as shown in the following example:

Properties prop = new Properties(System.getProperties());
prop.put("org.omg.CORBA.ORBClass","com.beasys.CORBA.iiop.ORB");
prop.put("org.omg.CORBA.ORBSingletonClass",
         "com.beasys.CORBA.idl.ORBSingleton");
System.setProperties(prop);
// Initialize the ORB.
ORB orb = ORB.init(args, prop);

IIOP Support

IIOP is the protocol used for communication between ORBs. IIOP allows ORBs from different vendors to interoperate. For Java server applications, a port number must be supplied at the client for persistent or user ID object reference policies.

Java Applet Support

IIOP support for applets that want to receive callbacks or callouts is limited due to applet security mechanisms. Any applet run-time environment that allows an applet to create and listen on sockets (via their proprietary environment or protocol) will be able to act as WLE joint client/server applications. If the applet run-time environment restricts socket communication, then the applet cannot be a joint client/server application to a WLE application.

Port Numbers for Persistent Object References

WLE Java server applications support only GIOP V1.0, as described in Chapter 13 of the OMG CORBA 2.2 specification.

For a WLE Java remote joint client/server application to support IIOP, the object references created for the server component must contain a host and a port. For transient object references, any port is sufficient and can be obtained by the ORB dynamically; however, this is not sufficient for persistent object references.

Persistent references must be served on the same port after the ORB restarts. That is, the ORB must be prepared to accept requests on the same port with which it created the object reference. Therefore, there must be some way to configure the ORB to use a particular port.

Java clients that expect to act as servers for callbacks of persistent references must now be started with a specified port. This is done by setting the system property org.omg.CORBA.ORBPort, as in the following commands:

For Windows NT:

java -DTOBJADDR=//host:port

  -Dorg.omg.CORBA.ORBPort=xxxx

  -classpath=%CLASSPATH% client

For Unix:

java -DTOBJADDR=//host:port
 
  -Dorg.omg.CORBA.ORBPort=xxxx

  -classpath=$CLASSPATH client

Typically, a system administrator assigns the port number for the client from the user range of port numbers, rather from the dynamic range. This keeps the joint client/server applications from using conflicting ports.

If a WLE remote joint client/server application tries to create a persistent object reference without having set a port (as in the preceding command line), the operation raises an exception, IMP_LIMIT , informing the user that a truly persistent object reference cannot be created.

Callbacks Interface API

For a complete description of the BEAWrapper.Callbacks interface API, see the Javadoc.