3.7.3.5.5 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.