com.beasys
Class Tobj_Servant

java.lang.Object
  |
  +--org.omg.CORBA.portable.ObjectImpl
        |
        +--org.omg.CORBA.DynamicImplementation
              |
              +--org.omg.PortableServer.Servant
                    |
                    +--com.beasys.Tobj_Servant

public abstract class Tobj_Servant

extends org.omg.PortableServer.Servant

The Tobj_Servant interface defines operations that allow a CORBA object to assist in the management of its state. Every implementation skeleton generated by the IDL compiler automatically inherits from the Tobj_Servant class. The Tobj_Servant class contains two methods, activate_object and deactivate_object, that can be redefined by the programmer.

Whenever a request comes in for an inactive CORBA object, the object is activated and the activate_object method is invoked on the servant. When the CORBA object is deactivated, the deactivate_object method is invoked on the servant. The timing of deactivation is driven by the implementation's activation policy. When the deactivate_object method is invoked, the TP Framework passes in a reason code to indicate why the call was made.

Note: Tobj_Servant.activate_object and Tobj_Servant.deactivate_object are the only methods that the TP Framework guarantees will be invoked for CORBA object activation and deactivation. The servant class constructor and finalizer may or may not be invoked at activation or deactivation time. Therefore, the server-application code must not do any state handling for CORBA objects in either the constructor or finalizer of the servant class.

See Also:

Serialized Form

Constructor Summary

Tobj_Servant()

Method Summary

void	activate_object(java.lang.String oid) Associates an object ID with a servant.
void	deactivate_object(java.lang.String oid, DeactivateReasonValue dr) Removes the association of an object ID with its servant.

Methods inherited from class org.omg.PortableServer.Servant

_all_interfaces, _default_POA, _object_id, _orb, _orb, _poa, _this_object, _this_object, equals, hashCode, toString

Methods inherited from class org.omg.CORBA.DynamicImplementation

invoke

Methods inherited from class org.omg.CORBA.portable.ObjectImpl

_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _ids, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Tobj_Servant

public Tobj_Servant()

Method Detail

activate_object

public void activate_object(java.lang.String oid)
                     throws ActivateObjectFailed,
                            OutOfMemory

Associates an object ID with a servant. This method gives the application an opportunity to restore the object's state when the object is activated. The state may be restored from shared memory, from an ordinary flat file, or from a database file.

Object activation is triggered by a client invoking a method on an inactive CORBA object. This causes the Portable Object Adapter (POA) to assign a servant to the CORBA object. The activate_object method is invoked before the method invoked by the client is invoked. If the activate_object method returns successfully, that is, without raising an exception, the requested method is executed on the servant.

The activate_object and deactivate_object methods and the method invoked by the client can be used by the programmer to manage object state. The particular way these methods are used to manage object state may vary according to the needs of the application. For a discussion of how these methods might be used, see Creating Java Server Applications.

If the object is currently infected with a global transaction, the activate_object method executes within the scope of that same global transaction. It is the responsibility of the programmer of the object to check that the stored state of the object is consistent. In other words, it is up to the application code to save a persistent flag that indicates whether or not the deactivate_object method successfully saved the state of the object. That flag should be checked in the activate_object method.

Parameters:

stroid - Specifies the object ID in string format. The object ID uniquely identifies this instance of the class. This is the same object ID that was specified in the com.beasys.Tobj.TP.create_object_reference method for the object reference used for this invocation.

Throws:

ActivateObjectFailed - If an error occurs while executing the activate_object method, the application code should raise either a CORBA standard exception or a com.beasys.TobjS.ActivateObjectFailed exception. When an exception is raised, the TP Framework catches the exception, and the following events occur:

• The activation fails.

• The method invoked by the client is not executed.

• A com.beasys.TobjS.OBJECT_NOT_EXIST exception is raised back to the client.

• If the activate_object method is executing within a transaction and the client initiated the transaction, the transaction is not rolled back.

• If the TP Framework automatically initiated the transaction prior to invoking the activate_object method, the transaction is rolled back. This can occur if the transaction policy is always or if the AUTOTRAN attribute is set for the interface.

  Note: For each CORBA interface, set AUTOTRAN to Yes if you want a transaction to start automatically when an operation invocation is received. Setting AUTOTRAN to Yes has no effect if the interface is already in transaction mode. For more information about AUTOTRAN, refer to the Administration Guide.

• Based on which exception is raised, a message is written to the user log (ULOG) file. For more information, see the System Messages manual.

OutOfMemory - Ran out of memory.

deactivate_object

public void deactivate_object(java.lang.String oid,
                              DeactivateReasonValue dr)
                       throws DeactivateObjectFailed

Removes the association of an object ID with its servant. This method gives the application an opportunity to save all or part of the object's state before the object is deactivated. The state may be saved in shared memory, in an ordinary flat file, or in a database file.

Object deactivation is initiated either by the system, depending on the activation policy of the implementation for the CORBA object, or by the application. The deactivate_object method is invoked before the CORBA object is deactivated.

Deactivation may occur after an execution of a method invoked by a client if the activation policy for the CORBA object implementation is method, or as a result of the end of transactional work if the activation policy is transaction. It may also occur as the result of server shutdown if the activation policy is transaction or process.

In addition, you can use the com.beasys.Tobj.TP.deactivateEnable method to control the deactivation of CORBA objects. You can invoke the com.beasys.Tobj.TP.deactivateEnable method inside a method of an object that has its activation policy set to process. This causes the object to be deactivated at the end of the method. The com.beasys.Tobj.TP.deactivateEnable method should not be invoked in an object with the activation policy set to method or transaction.

The activate_object and deactivate_object methods and the method invoked by the client can be used by the programmer to manage object state. The manner in which these methods are used to manage object state may vary according to the needs of the application. For a discussion of how these methods might be used, see Creating Java Server Applications.

The CORBA object is allowed to vote on the outcome of the transaction when the deactivate_object method is invoked with the DR_TRANS_COMMITTING reason code. By invoking the rollback_only method on the TransactionCurrent object, the method can force the transaction to be rolled back; otherwise, the two-phase commit algorithm continues. The transaction is not necessarily committed just because the rollback_only method is not invoked in this method. Any other CORBA object or resource manager involved in the transaction could also vote to roll back the transaction.

Parameters:

oid - Specifies the object ID in string format. The object ID uniquely identifies this instance of the class. This is the same object ID that was specified in the com.beasys.Tobj.TP.create_object_reference method.

dr - Indicates the event that caused this method to be invoked.

Throws:

- If an error occurs while executing the deactivate_object method, the application code should raise either a CORBA standard exception or a com.beasys.TobjS.DeactivateObjectFailed exception. If the deactivate_object method was invoked by the TP Framework, the TP Framework catches the exception and the following events occur:

• The object is deactivated.

• If the client initiated a transaction, the transaction is not rolled back.

• If the system automatically initiated a transaction, the transaction is rolled back.

• The client is not notified of the exception that is raised in the deactivate_object method.

• Based on which exception is raised, a message is logged to the user log (ULOG) file. See the System Messages manual for more information.

  Restrictions:

  Note that if the object is involved in a transaction when this method is invoked, there are restrictions on what type of processing can be done based on the reason the object is invoked. If the object was involved in a transaction, the activation policy is transaction and the reason code for the call is:

  DR_TRANS_ABORTED
  No invocations on any CORBA objects are allowed in the method. No tpcall() is allowed. Transactions cannot be suspended or begun.

  DR_TRANS_COMMITTING
  No invocations on any CORBA objects are allowed in the method. No tpcall() is allowed. Transactions cannot be suspended or begun.

  The reason for these restrictions is that the deactivation of objects with activation policy transaction is controlled by a call to the TP Framework from the transaction manager for the transaction. When the call with reason code DR_TRANS_COMMITTING is made, the transaction manager is executing phase 1 (prepare) of the two-phase commit. At this stage, it is not possible to issue a call to either suspend a transaction or initiate a new transaction.

  Invocations on other CORBA objects are not allowed because an invocation to a CORBA object that is in another process would require that the process join the transaction; since the transaction manager is already executing the prepare phase, an error would occur. In addtion, invocations are not allowed because an invocation to a CORBA object that had no transactional properties would require that the current transaction be suspended, which would cause an error. A tpcall() is not allowed for the same reason.

  Similarly, when the invocation with reason code DR_TRANS_ABORTED is made, the transaction manager is already aborting. While the transaction manager is aborting, it is not possible to either suspend a transaction or initiate a new transaction. The same restrictions apply as for DR_TRANS_COMMITTING.