![]() |
![]() |
e-docs > Tuxedo > Administering a Tuxedo Application at Run Time > TP Framework |
Administering a Tuxedo Application at Run Time
|
Tobj_ServantBase::deactivate_object()
Synopsis
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.
C++ Binding
class Tobj_ServantBase : public PortableServer::ServantBase {
public:
virtual void deactivate_object(const char* stroid,
TobjS::DeactivateReasonValue reason) {}
};
Arguments
Note: The restriction on the length of the object ID has been removed in this release.
Description
Object deactivation is initiated either by the system or by the application, depending on the activation policy of the implementation for the CORBA object. The deactivate_object() method is invoked before the CORBA object is deactivated. For details of these policies and their use, see the section ICF Syntax.
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, the BEA Tuxedo software supports the use of user-controlled deactivation of CORBA objects having an activation policy of process or method via the use of the TP::deactivateEnable() and TP::deactivateEnable(-,-,-) methods. TP::deactivateEnable can be called inside a method of an object to cause the object to be deactivated at the end of the method. If TP::deactivateEnable is called in an object with the transaction activation policy, an exception is raised (TobjS::IllegalOperation) and the TP Framework takes no action. TP::deactivateEnable(-,-,-) can be called to deactivate any object that has a process activation policy. For more information, see the section TP::deactivateEnable().
Note: The deactivate_object method will be called at server shutdown time for every object remaining in the Active Object Map, whether it was entered there implicitly by the TP Framework (the activation-on-demand technique: TP::create_servant and the servant's activate_object method) or explicitly by the user with TP::create_active_object_reference.
The activate_object() and deactivate_object() methods and explicit methods 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 CORBA Server Applications.
The CORBA object with transaction activation policy gets to vote on the outcome of the transaction when the deactivate_object() method is invoked with the DR_TRANS_COMMITTING reason code. By calling Current.rollback_only() the method can force the transaction to be rolled back; otherwise, the two-phase commit algorithm continues. The transaction will not necessarily be committed just because Current.rollback_only() is not called in this method. Any other CORBA object or resource manager involved in the transaction could also vote to roll back the transaction.
Restriction
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:
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 suspend a transaction nor to initiate a new transaction. Since a call to a CORBA object that was in another process would require that process to join the transaction, and the transaction manager is already executing the prepare phase, this would cause an error1. Since a call to a CORBA object that had no transactional properties would require that the current transaction be suspended, this would also cause an error. The same is true of a tpcall().
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.
Return Value
None.
Exceptions
If the CORBA object method that is invoked by the client raises an exception, that exception is caught by the TP Framework and is eventually returned to the client. This is true even if deactivate_object() is invoked and raises an exception.
The client will never be notified about exceptions that are raised in deactivate_object(). It is the responsibility of the application code to check that the stored state of the CORBA object is consistent. For example, the application code could save a persistent flag that indicates whether or not deactivate_object() successfully saved the state. That flag can then be checked in activate_object().
If an error occurs while executing deactivate_object(), the application code should raise either a CORBA standard exception or a DeactivateObjectFailed exception. If deactivate_object() was invoked by the TP Framework, the TP Framework catches the exception and the following events occur:
![]() |
![]() |
![]() |
![]() |
||
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |