TP Framework

e-docs > Tuxedo > Administering a Tuxedo Application at Run Time > TP Framework

Administering a Tuxedo Application at Run Time

TP::create_active_object_reference()

Synopsis

Creates an object reference and preactivates an object.

C++ Binding

static CORBA::Object_ptr
    create_active_object_reference(
           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. The ObjectId uniquely identifies this instance of the class. The programmer decides what information to place in the ObjectId. One possibility would be to use it to hold a database key. Choosing the value of an object identifier, and the degree of uniqueness, is part of the application design. The BEA Tuxedo software cannot guarantee any uniqueness in object references, since these may be legitimately copied and shared outside the BEA Tuxedo environment, for example by stringifying the object reference.

servant

A pointer to a servant that the application has already created and initialized.

Exceptions:

TobjS::InvalidInterface

Indicates that the specified interfaceName is NULL.

TobjS::InvalidObjectId

Indicates the specified stroid is NULL.

TobjS::ServantAlreadyActive

The object could not be activated explicitly because the servant is already being used with another ObjectId. A servant can be used only with a single ObjectId. To preactivate objects containing different ObjectIds, the application must create multiple servants and preactivate them separately, one per ObjectId.

TobjS::ObjectAlreadyActive

The object could not be activated explicitly because the ObjectId is already being used in the Active Object Map. A given ObjectId can have only one servant associated with it. To change to a different servant, the application must first deactivate the object and activate it again.

TobjS::IllegalOperation

The object could not be activated explicitly because it does not have the process activation policy.

Description

This method creates an object reference and preactivates an object. The resulting object reference may be passed to clients who will use it to access the object.

Ordinarily, the application will call this method in two places:

In Server::initialize() to preactivate process objects so that they do not need activation on the first invocation.
In any method that creates object references to be returned to clients.

This method allows an application to activate an object explicitly before its first invocation. (For reasons you might want to do this, refer to the section Explicit Activation.) The user first creates a servant and sets its state before calling create_active_object_reference. The TP Framework then enters the servant and string ObjectId in the Active Object Map. The result is exactly the same as if the TP Framework had previously invoked Server::create_servant, received back the servant pointer, and then had invoked servant::activate_object.

The object so activated must be for an interface that was declared with the process activation policy; otherwise, an exception is raised.

If the object is deactivated, an object reference held by a client might cause the object to be activated again in some other process. For a discussion about situations in which this might be a problem, refer to the section Explicit Activation.

Note: There is one restriction on this method when the user-controlled concurrency policy option is set in the ICF file (See Parallel Objects.). The TP::create_active_object_reference method throws a TobjS::IllegalOperation exception if it is passed an interface with user-controlled concurrency set. Since the AOM is not used when user-controlled concurrency is set, there is no way for the TP Framework to connect an active object to this server.

Caution

When you preactivate objects in an interface, you must specify an activation policy of process in the ICF file for that interface. However, when you specify the process activation policy for an interface in the ICF file, this can lead to the following problem.

Problem Statement

You write SERVER1 such that all objects on interface A are preactivated. To prevent the object from being activated on demand by the TP Framework, you write the interface's activate_object method to always throw the ActivateObjectFailed exception.
SERVER2 also implements objects of interface A. However, instead of preactivating the objects, SERVER2 lets the TP Framework activate them on demand.
If the administrator configures SERVER1 and SERVER2 in the same group, then a client can get an interface A object reference from SERVER2 and invoke on it. Then, due to load balancing, SERVER1 could be asked to activate an object on interface A. However, SERVER1 is not able to activate an object on interface A on demand because its activate_object method throws the ActivateObjectFailed exception.

Workaround

You can avoid this problem by having the administrator configure SERVER1 and SERVER2 in different groups. The administrator uses the SERVERS section of the UBBCONFIG file to define groups.

Return Value

The newly created object reference.