TP Framework

CORBA Programming Reference

TP::create_object_reference()

Synopsis

Creates an object reference. The resulting object reference may be passed to clients who use it to access the object.

C++ Binding

static CORBA::Object_ptr    TP::create_object_reference (
                               const char* interfaceName,
                               const char* stroid,
                               CORBA::NVList_ptr criteria);

Arguments

interfaceName

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

The interface name can be retrieved by making a call on the following interface typecode ID function:

const char* _tc_<CORBA interface name>::id();

where <CORBA interface name> is any object class name. For example:

char* idlname = _tc_Simple->id();

stroid

Specifies the ObjectId in string format. The ObjectId uniquely identifies this instance of the class. It is up to the programmer to decide what information to place in the ObjectId. One possibility would be to use the ObjectId 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 object references may be legitimately copied and shared outside the BEA Tuxedo domain (for example, by passing the object reference as a string). It is strongly recommended the you choose a unique ObjectId in order to allow parallel execution of invokes on object references.

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

criteria

Specifies a list of named values that can be used to provide factory-based routing for the object reference. The list is optional and is of type CORBA::NVList. The use of factory-based routing is optional and is dependent on the use of this argument. If you do not want to use factory-based routing, you can pass a value of 0 (zero) for this argument.

The BEA Tuxedo system administrator configures factory-based routing by specifying routing rules in the UBBCONFIG file. See Setting Up a BEA Tuxedo Application online document for details on this facility.

Exceptions

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

InvalidInterface

Indicates that the specified interfaceName is NULL.

InvalidObjectId

Indicates that the specified stroid is NULL.

Description

The server application is responsible for invoking the create_object_reference() method. This method creates an object reference. The resulting object reference may be passed to clients who will use it to access the object.

Ordinarily, the server application calls this method in two places:

In Server::initialize() to create factories for the server.
In factory methods to create object references to be returned to clients.

For examples of how and when to call the create_object_reference() method, see Creating CORBA Server Applications.

Return Value

Object

The newly created object reference.

Example

The following example shows how to use the criteria argument:

CORBA::NVList_ptr criteria;
CORBA::Long branch_id = 7;
CORBA::Long account_id = 10001;
CORBA::Any any_val;

// Create the list and assign to _var to cleanup on exit
CORBA::ORB::create_list (2, criteria);
CORBA::NVList_var criteria_var(criteria);

// Add the BRANCH_ID
any_val <<= branch_id;
criteria->add_value("BRANCH_ID", any_val, 0);

// Add the ACCOUNT_ID
any_val <<= account_id;
criteria->add_value("ACCOUNT_ID", any_val, 0);

// Create the object reference.
TP::create_object_reference ("IDL:BankApp/Teller:1.0",
"Teller_01", criteria);