com.beasys.BEAWrapper
Class Callbacks

java.lang.Object
  |
  +--com.beasys.BEAWrapper.Callbacks

public class Callbacks

extends java.lang.Object

Supplies a set of methods that provide similar functionality as the ones provided by the C++ wrappers. These routines provide a POA like functionality in terms of defining the LifeSpan policies of object references created by the provided methods.

Constructor Summary

Callbacks()
Returns a reference to the Callbacks interface.

Callbacks(org.omg.CORBA.ORB init_orb)
Returns a reference to the Callbacks interface.

Method Summary

java.lang.String	get_string_oid() Returns the string version of the object ID of the current request.
org.omg.CORBA.Object	restart_persistent_systemid(org.omg.CORBA.portable.ObjectImpl servant, java.lang.String rep_id, java.lang.String stroid) Performs the following actions:
org.omg.CORBA.Object	start_persistent_systemid(org.omg.CORBA.portable.ObjectImpl servant, java.lang.String rep_id, org.omg.CORBA.StringHolder stroid) Performs the following actions:
org.omg.CORBA.Object	start_persistent_userid(org.omg.CORBA.portable.ObjectImpl servant, java.lang.String rep_id, java.lang.String stroid) Performs the following actions:
org.omg.CORBA.Object	start_transient(org.omg.CORBA.portable.ObjectImpl servant, java.lang.String rep_id) Performs the following actions:
void	stop_all_objects() Tells the ORB to stop accepting requests on all servants, if any, that have been set up in this Java VM.
void	stop_object(org.omg.CORBA.portable.ObjectImpl servant) Tells the ORB to stop accepting requests on the given servant.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Callbacks

public Callbacks()

Returns a reference to the Callbacks interface. Only one such object should be created for a Java VM, even if multiple threads are used. Using more than one such object will result in unpredictable behavior.

Parameters:

init_orb - Is the orb to be used for all further operations.

Throws:

org.omg.CORBA.IMP_LIMIT - The BEAWrapper.Callbacks class has already been instantiated with an ORB pointer. Only one instance of this class can be used in a Java VM.

Callbacks

public Callbacks(org.omg.CORBA.ORB init_orb)

Returns a reference to the Callbacks interface. Only one such object should be created for a Java VM, even if multiple threads are used. Using more than one such object will result in unpredictable behavior.

Parameters:

init_orb - The orb to be used for all further operations.

Throws:

org.omg.CORBA.IMP_LIMIT - The BEAWrapper.Callbacks class has already been instantiated with an ORB pointer. Only one instance of this class can be used in a Java VM.

Method Detail

start_transient

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

Performs the following actions:

• Activates an object using the Servant supplied to service objects of the type rep_id, using an object ID generated by the system.
• Sets the ORB into the state in which they will accept requests on that object.
• Return an object reference to the object so activated. The object reference returned will be valid only until the termination of the client or until the callback servant is halted by the user via the stop_object method; after that, invocations on that object reference are no long valid and can never be made valid.

Parameters:

servant - An instance of the Java implementation class for the interface.

rep_id - The repository id of the interface.

Returns:

A reference to the servant object that was created with the object ID generated by the system and the rep_id provided by the user. The object reference will need to be converted to a specific object type by invoking the _narrow() operation defined for the specific object.

Throws:

ServantAlreadyActive - The servant is already being used for a callback. A servant can be used only for a callback with a single object ID. To receive callbacks on objects containing different object IDs, you must create different servants and activate them separately. The same servant can be re-used only if a stop_object operation tells the system to stop using the servant for its original object ID.

BAD_PARAMETER - The repository id was a null string or the servant was a null pointer.

start_persistent_systemid

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

Performs the following actions:

• Activates an object using the Servant supplied to service objects of the type rep_id, using an object ID generated by the system.
• Sets the ORB into the state in which it accepts requests on that object.
• Sets the output parameter stroid to the stringified version of an object ID assigned by the system.
• Returns an object reference to the activated object. The object reference returned is valid even after termination of the client. That is, if the client terminates, restarts again, and then activates a servant with the same rep_id and for the same object ID, the servant accepts requests made on that same object reference.

Parameters:

servant - Is an instance of the JAVA implementation class for the interface.

rep_id - Is the repository id of the interface.

stroid - Is set by the system and is opaque to the user. The client uses it when the client reactivates the object at a later time (using the restart_persistent_systemid method), most likely after the client process has terminated and restarted. If an exception occurs, the value returned is invalid and is set to a null string.

Returns:

An object reference created with the object ID generated by the system and the rep_id provided by the user. The object reference needs to be converted to a specific object type by invoking the _narrow() operation defined for the specific object. The caller is responsible for initializing object state and saving to persistent store, if necessary, when it is finished execution.

Throws:

ServantAlreadyActive - The servant is already being used for a callback. A servant can be used only for a callback with a single object ID. To receive callbacks on objects containing different object IDs, you must create different servants and activate them separately. The same servant can be reused only if a stop operation tells the system to stop using the servant for its original object ID.

BAD_PARAMETER - The repository id was a null string or the servant was a null pointer.

org.omg.CORBA.IMP_LIMIT - In addition to other system reasons for this exception, a reason unique to this situation is that the JointClientServer ORB was not initialized with a port number, so that a persistent object reference cannot be created.

restart_persistent_systemid

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

Performs the following actions:

• Activates an object using the servant supplied to service objects of the type rep_id, using the supplied stroid (a stringified object ID), which must have been obtained by a previous invocation on the start_persistent_systemid method.
• Sets the ORB into the state in which it accepts requests on that object.
• Returns an object reference to the activated object.

Parameters:

servant - Is an instance of the Java implementation class for the interface.

rep_id - Is the repository id of the interface.

stroid - Is the stringified version of the object ID provided by the user to be set in the object reference being created. This argument must have been returned from a previous invocation to the start_persistent_systemid method.

Returns:

An object reference created with the stringified object ID stroid and the rep_id provided by the user. The object reference will need to be converted to a specific object type by invoking the _narrow() operation defined for the specific object. The caller is responsible for initializing object state and saving to persistent store, if necessary, when it is finished execution.

Throws:

ObjectAlreadyActive - The stringified object ID is already being used for a callback. A given object ID can have only one servant associated with it. If you want to change to a different servant, you must first invoke the stop_object method with the servant currently in use.

BAD_PARAMETER - The repository id was a null string, the servant was a null pointer, or the object ID supplied was not previously assigned by the system.

org.omg.CORBA.IMP_LIMIT - In addition to other system reasons for this exception, the JointClientServer ORB was not initialized with a port number; therefore, a persistent object reference cannot be created.

start_persistent_userid

public org.omg.CORBA.Object start_persistent_userid(org.omg.CORBA.portable.ObjectImpl servant,
                                                    java.lang.String rep_id,
                                                    java.lang.String stroid)
                                             throws ServantAlreadyActive,
                                                    ObjectAlreadyActive

Performs the following actions:

• Activates an object using the servant supplied to service objects of the type rep_id, using the object ID stroid.
• Sets the ORB into the state in which it accepts requests on that object.
• Returns an object reference to the activated object. The object reference returned is valid even after termination of the client. That is, if the client terminates, and restarts again, and then activates a servant with the same rep_id and for the same object ID, the servant accepts requests made on that same object reference.

Parameters:

servant - Is an instance of the Java implementation class for the interface.

rep_id - Is the repository id of the interface.

stroid - Is the stringified version of an object ID provided by the user to be set in the object reference being created. The stroid holds application-specific data and is opaque to the ORB.

Returns:

An object reference created with the stringified object ID stroid and the rep_id provided by the user. The object reference will need to be converted to a specific object type by invoking the _narrow() operation defined for the specific object. The caller is responsible for initializing object state and saving to persistent store, if necessary, when the object is finished execution.

Throws:

ServantAlreadyActive - The servant is already being used for a callback. A servant can be used only for a callback with a single object ID. To receive callbacks on objects containing different object IDs, you must create different servants and activate them separately. The same servant can be reused only if a stop_object operation tells the system to stop using the servant for its original object ID.

ObjectAlreadyActive - The stringified object ID is already being used for a callback. A given object ID can have only one servant associated with it. If you wish to change to a different servant, you must first invoke the stop_object method with the servant currently in use.

BAD_PARAMETER - The repository id was a null string or the servant was a null pointer.

org.omg.CORBA.IMP_LIMIT - In addition to other system reasons for this exception, the JointClientServer ORB was not initialized with a port number; therefore, a persistent object reference cannot be created.

stop_object

public void stop_object(org.omg.CORBA.portable.ObjectImpl servant)

Tells the ORB to stop accepting requests on the given servant. If the servant was not already activated, no error is reported.

Note: If you do an invocation on a callback object after you call the stop_object operation, the OBJECT_NOT_EXIST exception is returned to the caller. This is because the stop_object operation, in effect, deletes the object.

Parameters:

Servant - Is an instance of the Java implementation class for the interface. The association between this servant and its object ID will be removed from the Active Object Map.

get_string_oid

public java.lang.String get_string_oid()
                                throws NotInRequest

Returns the string version of the object ID of the current request. This method should be invoked only in Servant code. Calling this method in client thread will throw the NotInRequest exception becauyse the client thread has no OID associated to it.

Returns:

The string version of the object ID of the current request. This is the string that was supplied when the object reference was created. The string is meaningful to users only in the case when the object reference was created by the start_persistent_userid method. (That is, the object ID created by the start_transient and start_persistent_systemid methods were created by the ORB and have no relationship to the user application.)

Throws:

NotInRequest - The function was called when the ORB was not in the context of a request; that is, not while servicing a request in method code. Do not invoke this function from client code. Invoking this method is valid only during the execution of a method of the Standalone Tuxedo CORBA Object (that is, the servant).

stop_all_objects

public void stop_all_objects()

Tells the ORB to stop accepting requests on all servants, if any, that have been set up in this Java VM.