TP Framework

CORBA Programming Reference

TP::deactivateEnable()

Synopsis

Enables application-controlled deactivation of CORBA objects.

C++ Binding

Current-object format:

static void           TP::deactivateEnable();

Any-object format:

static void        TP::deactivateEnable(
                           const char*  interfaceName,
                           const char* stroid,
                            Tobj_Servant servant);

Arguments

interfaceName

Specifies a character string that contains the fully qualified interface name for the object.

stroid

Specifies the ObjectId in string format for the object to be deactivated.

servant

A pointer to the servant associated with the stroid.

Exceptions

The following exceptions can be raised by the deactivateEnable() method:

IllegalOperation

Indicates that the TP::deactivateEnable method was invoked by an object with the activation policy set to transaction.

TobjS::ObjectNotActive

In the Any-object format, the object specified could not be deactivated because it was not active (the stroid and servant parameters did not identify an object that was in the Active Object Map).

Description

This method can be used to cause deactivation of an object, either the object currently executing (upon completion of the method in which it is called) or another object. It can only be used for objects with the process activation policy. It provides additional flexibility for objects with the process activation policy.

Note: For single-threaded servers, the TP::deactivateEnable(interface, object id, servant) method can be used to deactivate an object. However, if that object is currently in a transaction, the object will be deactivated when the transaction commits or rolls back. If an invoke occurs on the object before the transaction is committed or rolled back, the object will not be deactivated.

To ensure the desired behavior, make sure that the object is not in a transaction or ensure that no invokes occur on the object after the TP::deactivateEnable() call until the transaction is complete.

Note: For multithreaded servers, use of the TP::deactivateEnable(interface, object id, servant) method is not supported for deactivation of objects in per-object servers. This method is supported for deactivation objects in per-request servers, however, the deactivation may be delayed because others threads are acting on the object.

Depending on which of the overloaded functions are called, the actions are as follows.

Current-object format

When called from within a method of an object with process activation policy, the object currently executing will be deactivated after completing the method being executed.

When called from within a method of an object with method activation, the effect is the same as the normal behavior of such objects (effectively, a NOOP).

When the object is deactivated, the TP Framework first removes the object from the Active Object Map. It then calls the associated servant's deactivate_object method with a reason of DR_METHOD_END.

Any-object format

The application can request deactivation of an object by specifying its ObjectId and the associated servant.

If the object is currently executing, the TP Framework marks it for deactivation and waits until the object's method completes before deactivating the object (as with the "current-object format"). If the object is not currently executing, the TP Framework may deactivate it immediately. No indication is given to the caller as to the status of the deactivation. When the object is deactivated, the TP Framework first removes the object from the Active Object Map. It then calls the associated servant's deactivate_object method with a reason of DR_EXPLICIT_DEACTIVATE.

If the object for which the deactivate is requested has a transaction activation policy, an IllegalOperation exception is raised. This is because deactivation of such objects may interfere with their correct notification of transaction completion by the BEA Tuxedo transaction manager.

Return Value

None.