TP Framework

CORBA Programming Reference

Server::create_servant()

Synopsis

Creates a servant to instantiate a C++ object.

C++ Binding

class Server {
public:
      Tobj_Servant     create_servant(const char* interfaceName);
};

Argument

interfaceName

Specifies a character string that contains the fully qualified interface name for the object. This will be the same interface name that was supplied when the object reference was created (TP::create_object_reference() or TP::create_active_object_reference()) for the object reference used for this invocation. This name can be used to determine which servant needs to be constructed.

Exception

If an exception is thrown in Server::create_servant(), the TP Framework catches the exception. Activation fails. A CORBA::OBJECT_NOT_EXIST() exception is raised back to the client. In addition, an error message is written to the user log (ULOG) file, as follows, for each exception type:

TobjS::CreateServantFailed

"TPFW_CAT:23: ERROR: Activating object - application raised TobjS::CreateServantFailed. Reason = reason. Interface = interfaceName, OID = oid"

Where reason is a user-supplied reason, and interfaceName and oid are the interface ID and object ID, respectively, of the invoked CORBA object.

TobjS::OutOfMemory

"TPFW_CAT:22: ERROR: Activating object - application raised TobjS::OutOfMemory. Reason = reason. Interface = interfaceName, OID = oid"

Where reason is a user-supplied reason, and interfaceName and oid are the interface ID and object ID, respectively, of the invoked CORBA object.

CORBA::Exception

"TPFW_CAT:28: ERROR: Activating object - CORBA Exception not handled by application. Exception ID = exceptionID. Interface = interfaceName, OID = oid"

Where exceptionID is the interface ID of the exception, and interfaceName and oid are the interface ID and object ID, respectively, of the invoked CORBA object.

Other Exception

"TPFW_CAT:29: ERROR: Activating object - Unknown Exception not handled by application. Exception ID = exceptionID. Interface = interfaceName, OID = oid"

Where exceptionID is the interface ID of the exception, and interfaceName and oid are the interface ID and object ID, respectively, of the invoked CORBA object.

Description

The create_servant method is invoked by the TP Framework when a request arrives at the server and there is no available servant to satisfy the request. The TP Framework calls the create_servant method with the interface name for the servant to be created. The server application instantiates an appropriate C++ object and returns a pointer to it. Typically, the method contains a switch statement on the interface name and creates a new object, depending on the interface name.

Caution: The server application must not depend on this method being invoked for every activation of a CORBA object. The server application must not do any handling of CORBA object state in the constructors or destructors of any servant classes for CORBA objects. This is because the TP Framework may possibly reuse servants on activation and may possibly not destroy servants on deactivation.

Return Value

Tobj_Servant

The pointer to the newly created servant (instance) for the specified interface. A NULL value should be returned if create_servant() is invoked with an interface name that it does not recognize or if the servant cannot be created for some reason.

If the create_servant method returns a NULL pointer, activation fails. A CORBA::OBJECT_NOT_EXIST() exception is raised back to the client. Also, the following message is written to the user log (ULOG):

"TPFW_CAT:23: ERROR: Activating object - application raised TobjS::CreateServantFailed. Reason = Application's Server::create_servant returned NULL. Interface = interfaceName, OID = oid"

Where interfaceName is the interface ID of the invoked interface and oid is the corresponding object ID.

Note: The restriction on the length of the ObjectId has been removed in this release.