|
•
|
method (This is the default activation policy.)
|
The transaction activation policy provides a means for an object to vote on the outcome of the transaction prior to the execution of the two-phase commit algorithm. An object votes to roll back the transaction by calling
Current.rollback_only() in the
Tobj_ServantBase::deactivate_object method. It votes to commit the transaction by not calling
Current.rollback_only() in the method.
The initial object preactivates this iterator object by using TP::create_active_object_reference. It also creates an object reference to that object to return to the client. The client then invokes repeatedly on the iterator object to receive, say, the next 100 items in the list each time. The advantage of preactivation in this situation is that the state might be complex. It is often easiest to set such state initially, from a method that has all the information in its context (call frame), when the initial object still has control.
Just as it is possible to preactivate an object with the process activation policy, it is possible to request the deactivation of an object with the
process activation policy. The ability to preactivate and the ability to request deactivation are independent; regardless of how an object was activated, it can be deactivated explicitly.
A method in the application can request (via TP::deactivateEnable) that the object be deactivated. When
TP::deactivateEnable is called and the object is subsequently deactivated, no guarantee is made that subsequent invocations on the CORBA object will result in reactivation in the same process as a previous activation. The association between the
ObjectId and the servant exists from the activation of the CORBA object until one of the following events occurs: (1) the shutdown of the server process or (2) the application calls
TP::deactivateEnable. After the association is broken, when the object is invoked again, it can be reactivated anywhere that is allowed by the Oracle Tuxedo configuration parameters.
There are two forms of TP::deactivateEnable. In the first form (with no parameters), the object currently executing will be deactivated after completion of the method in which the call is made. The object itself makes the decision that it should be deactivated. This is often done during a method call that acts as a "signoff" signal.
The second form of TP::deactivateEnable allows a server to request deactivation of any active object, whether it is the object that is executing or not; that is, any part of the server can ask that the object be deactivated. This form takes parameters identifying the object to be deactivated. Explicit deactivation is not allowed for objects with an activation policy of
transaction, because such objects cannot be safely deactivated until the end of a transaction.
In the TP::deactivateEnable call, the TP Framework calls the servant’s
deactivate_object method. Exactly when the TP Framework invokes
deactivate_object depends on the state of the object to be deactivated. If the object is not currently in execution, the TP Framework deactivates it before returning to the caller. The object might be currently executing a method; this is always the case for
TP::deactivateEnable with no parameters (since it refers to the currently executing object). In this case,
TP::deactivateEnable is not told whether the object was deactivated immediately or not.
|
Note:
|
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.
|
While CORBA objects are active, their state is contained in a servant. Unless an application uses TP::create_active_object_reference, state must be initialized when the object is first invoked (that is, the first time a method is invoked on a CORBA object after its object reference is created), and on subsequent invocations after they have been deactivated. While a CORBA object is deactivated, its state must be saved outside the process in which the servant was active. The object’s state can be saved in shared memory, in a file, or in a database. Before a CORBA object is deactivated, its state must be saved, and when it is activated, its state must be restored.
|
•
|
optional (This is the default transaction_policy.)
|
|
Note:
|
The optional policy is the only transaction policy that can be influenced by administrative configuration. If the system administrator sets the AUTOTRAN attribute for the interface by means of the UBBCONFIG file or by using administrative tools, the system automatically starts a transaction upon invocation of the object, if it is not already infected with a transaction (that is, the behavior is as if the always policy were specified).
|
|
•
|
By the application code via use of the CosTransactions::Current::begin() operation. This can be done in either the client or the server. For a description of this operation, see Using CORBA Transactions.
|
|
•
|
Illegal server application behavior: Return from the method with the transaction in the suspended state (that is, return from the method without invoking resume if suspend was invoked).
|
|
•
|
Error Processing: If illegal behavior occurs, the TP Framework raises the CORBA::TRANSACTION_ROLLEDBACK exception to the client application and the transaction is rolled back by the Oracle Tuxedo system.
|
|
Note:
|
For each CORBA interface, set AUTOTRAN to Yes if you want a transaction to start automatically when an operation invocation is received. Setting AUTOTRAN to Yes has no effect if the interface is already in transaction mode. For more information about AUTOTRAN, see Using CORBA Transactions.
|
|
•
|
Illegal server behavior: Return from the method with the transaction in the suspended state (that is, return from the method without invoking resume if suspend was invoked).
|
|
•
|
Error Processing: If illegal behavior occurs, the TP Framework raises the CORBA::OBJ_ADAPTER exception to the client, and the transaction is rolled back by the system. The CORBA::OBJ_ADAPTER exception is raised because the client application did not initiate the transaction, and, therefore, does not expect transaction error conditions to be raised.
|
|
•
|
Error Processing: If illegal behavior occurs, the TP Framework raises the CORBA::OBJ_ADAPTER exception to the client application and the transaction is rolled back by the Oracle Tuxedo system. The CORBA::OBJ_ADAPTER exception is raised because the client application did not initiate the transaction, and, therefore, does not expect transaction error conditions to be raised.
|
|
•
|
If the application begins a transaction in Server::initialize(), it must either commit or roll back the transaction before returning from the method. If the application does not, the TP Framework shuts down the server. This is because the application has no predictable way of regaining control after completing the Server::initialize method.
|
The Current.rollback_only method can be used to ensure that the only possible outcome is to roll back the current transaction.
Current.rollback_only() can be invoked from any CORBA object method.
Note that this behavior does not apply to objects with process or
method activation policies. If the CORBA object wants to roll back the transaction, it can call
Current::rollback_only. If it wants to vote to commit the transaction, it does not make that call. Note, however, that a vote to commit does not guarantee that the transaction is committed, since other objects may subsequently vote to roll back the transaction.
|
Note:
|
Users of SQL cursors must be careful when using an object with the method or process activation policy. A process opens an SQL cursor within a client-initiated transaction. For typical SQL database products, once the client commits the transaction, all cursors that were opened within that transaction are automatically closed; however, the object will not receive any notification that its cursor has been closed.
|
The retry_policy option has two settings:
|
•
|
never: The default setting. It indicates that the interface implementation is not idempotent and that requests should never be automatically retried.
|
|
•
|
always: Indicates that the interface implementation is idempotent and that requests should always be retried in case of failure.
|
In the following UBBCONFIG file example shown in
Listing 3‑1, the ISL servers specified in lines 1 and 2 will support client failover. The ISL server in line 3 will not.
|
•
|
Tuxedo system-supplied object failover Only application-supplied object failover is supported.
|
[#pragma activation_policy method|transaction|process]
[#pragma transaction_policy never|ignore|optional|always]
[#pragma concurrency_policy user_controlled|system_controlled]
[Module module-name {]
implementation [implementation-name]
{
implements (module-name::interface-name);
[activation_policy (method|transaction|process);]
[transaction_policy (never|ignore|optional|always);]
[concurrency_policy (user_controlled|system_controlled);]
};
[};]
|
Note:
|
There is one restriction with user-controlled concurrency. TP::create_active_object_reference 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.
|
|
•
|
The Server C++ class, which has virtual methods for application-specific server initialization and termination logic
|
|
•
|
The ServerBase C++ class, which has virtual methods for multithreaded server applications.
|
|
•
|
The Tobj_ServantBase C++ class, which has virtual methods for object state management
|
|
•
|
The TP C++ class, which provides methods to:
|
|
•
|
The Server class is a C++ native class.
|
|
•
|
The Server.h file contains the declarations and definitions for the Server class.
|
|
•
|
The create_servant_with_id() method to support implementations requiring knowledge of the target object during the creation of a servant
|
The ServerBase class provides the same operations that were available in the
Server class in earlier releases. The Server class inherits from the ServerBase class.
|
•
|
ServerBase::thread_release()
|
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:
Where reason is a user-supplied reason, and
interfaceName and
oid are the interface ID and object ID, respectively, of the invoked CORBA object.
Where reason is a user-supplied reason, and
interfaceName and
oid are the interface ID and object ID, respectively, of the invoked CORBA object.
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.
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.
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.
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):
Where interfaceName is the interface ID of the invoked interface and
oid is the corresponding object ID.
Tobj_Servant create_servant_with_id (const char*
interfaceName,
const char*
stroid);
The TP Framework invokes the create_servant_with_id method when a request arrives at the server and there no servant is available to satisfy the request. The TP Framework passes in the interface name for the servant to be created and the object ID associated with the object with which the servant will be associated. 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. Providing the object ID allows a servant implementation to make decisions during the creation of the servant instance that require knowledge of the target object. Reentrancy support is one example of how a servant implementation might employ knowledge of the target object.
The ServerBase class provides a default implementation of
create_servant_with_id which calls the standard
create_servant method passing the interface name. This default implementation ignores the target object ID parameter.
The argc and
argv arguments are passed from the command line. The
argc argument contains the name of the server. The
argv argument contains the first command-line option that is specific to the application, if there are any.
Command-line options are specified in the UBBCONFIG file using the
CLOPT parameter in the entry for the server in the
SERVERS section. System-recognized options come first in the
CLOPT parameter, followed by a double-hyphen (
--), followed by the application-specific options. The value of
argc is one greater than the number of application-specific options. For details, see
ubbconfig(5) in the
File Formats, Data Descriptions, MIBs, and System Processes Reference.
If an exception is raised in Server::initialize(), the TP Framework catches the exception. The TP Framework behavior is the same as if
initialize() returned FALSE (that is, an exception is considered to be a failure). In addition, an error message is written to the user log (
ULOG) file, as follows, for each exception type:
Where reason is a string supplied by application code. For example:
Where exception is the interface ID of the CORBA exception that was raised.
The initialize callback method, which is invoked as the last step in server initialization, allows the application to perform application-specific initialization.
|
•
|
TP::open_xa_rm()
This is the preferred technique for server applications, since it can be done on a static function, without the need to obtain an object reference.
|
|
Note:
|
You must use the TP::open_xa_rm() method if you use the INS bootstrap mechanism to obtain initial object references.
|
|
•
|
Transactions may be started in the initialize method after invoking the Tobj::TransactionCurrent::open_xa_rm() or TP::open_xa_rm method. However, any transactions that are started in initialize() must be terminated by the server application before initialize() returns. If the transactions are still active when control is returned, the server application fails to boot, and it exits gracefully. This happens because the server application has no logical way of either committing or rolling back the transaction after Server::initialize() returns. This condition is an error.
|
Boolean TRUE or
FALSE.
TRUE indicates success.
FALSE indicates failure. If an error occurs in
initialize(), the application code should return
FALSE. The application code should not call the system call
exit(). Calling
exit() does not give the TP Framework a chance to release resources allocated during startup and may cause unpredictable results.
CORBA::Boolean thread_initialize(int argc, char** argv)
The thread_initialize callback method is invoked each time a thread is created, to initialize the thread. Note that the Oracle Tuxedo software manages a number of system-owned threads that are used for dispatching requests; these system-owned threads are in addition to those threads in the thread pool. Under some circumstances the servant methods you implement are also executed in these system-owned threads; for this reason the Oracle Tuxedo software invokes the
thread_initialize method to initialize the system-owned threads.
The ServerBase class provides a default implementation of the
thread_initialize method that opens the XA resource manager in the initialized thread.
True if the initialization of the thread was successful.
If an exception is raised in release(), the TP Framework catches the exception. Each exception causes an error message to be written to the user log (
ULOG) file, as follows:
Where reason is a string supplied by application code. For example:
Where exception is the interface ID of the CORBA exception that was raised.
The release callback method, which is invoked as the first step in server shutdown, allows the server application to perform any application-specific cleanup. The user must override the virtual function definition.
The TP Framework provides a default implementation of Server::release(). The default implementation closes XA resource managers for the server. The implementation does this by issuing a
tx_close() invocation, which uses the default
CLOSEINFO configured for the server's group in the
UBBCONFIG file.
|
Note:
|
You must use the TP::close_xa_rm() method if you use the INS bootstrap mechanism to obtain initial object references.
|
|
Note:
|
Once a server receives a request from the tmshutdown(1) command to shut down, it can no longer receive requests from other remote objects. This may require servers to be shut down in a specific order. For example, if the Server::release() method in Server 1 needs to access a method of an object that resides in Server 2, Server 2 should be shut down after Sever 1 is shut down. In particular, the TP::unregister_factory() method accesses the FactoryFinder Registrar object that resides in a separate server. The TP::unregister_factory() method is typically invoked from the release() method; therefore, the FactoryFinder server should be shut down after all servers that call TP::unregister_factory() in their Server::release() method.
|
The thread_release callback method is invoked each time a thread is released. Implement the
thread_release method as necessary to perform application-specific resource cleanup.
The ServerBase class provides a default implementation of the
thread_release method that closes the XA resource manager in the released thread.
The Tobj_ServantBase interface inherits from the
PortableServer::RefCountServantBase class and defines operations that allow a CORBA object to assist in the management of its state in a thread-safe manner. Every implementation skeleton generated by the IDL compiler automatically inherits from the
Tobj_ServantBase class. The
Tobj_ServantBase class contains two virtual methods,
activate_object() and
deactivate_object(), that may be optionally implemented by the programmer.
|
Note:
|
Tobj_ServantBase::activate_object() and Tobj_ServantBase::deactivate_object() are the only methods that the TP Framework guarantees will be invoked for CORBA object activation and deactivation. The servant class constructor and destructor may or may not be invoked at activation or deactivation time (through the Server::create_servant call for C++). Therefore, the server application code must not do any state handling for CORBA objects in either the constructor or destructor of the servant class.
|
|
Note:
|
The programmer does not need to use a cast or reference to Tobj_ServantBase directly. The Tobj_ServantBase methods show up as part of the skeleton and, therefore, in the implementation class for a servant. The programmer may provide definitions for the activate_object and deactivate_object methods, but the programmer should never make direct invocations on those methods; only the TP Framework should call those methods.
|
Specifies the object ID in string format. The object ID uniquely identifies this instance of the class. This is the same object ID that was specified when the object reference was created (using
TP:create_object_reference()) or in the
TP::create_active_object_reference() for the object reference used for this invocation.
The activate_object() and
deactivate_object() methods and the method invoked by the client can be used by the programmer to manage object state. The particular way these methods are used to manage object state may vary according to the needs of the application. For a discussion of how these methods might be used, see
Creating CORBA Server Applications.
If an error occurs while executing activate_object(), the application code should raise either a CORBA standard exception or a
TobjS::ActivateObjectFailed exception. When an exception is raised, the TP Framework catches the exception, and the following events occur:
|
•
|
If activate_object() is executing within a transaction and the client initiated the transaction, the transaction is not rolled back.
|
|
•
|
A CORBA::OBJECT_NOT_EXIST exception is raised back to the client.
|
|
Note:
|
For each CORBA interface, set AUTOTRAN to Yes if you want a transaction to start automatically when an operation invocation is received. Setting AUTOTRAN to Yes has no effect if the interface is already in transaction mode. For more information about AUTOTRAN, see Using CORBA Transactions.
|
Where reason is a user-supplied reason, and
interfaceName and
oid are the interface ID and object ID, respectively, of the invoked CORBA object.
Where reason is a user-supplied reason, and
interfaceName and
oid are the interface ID and object ID, respectively, of the invoked CORBA object.
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.
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.
myServant * servant = new intf_i();
if(servant != NULL)
servant->_add_ref();
Specifies the object ID in string format. The object ID uniquely identifies this instance of the class.
This reason code is used only for objects that have the
transaction activation policy. It can occur when the transaction is started by either the client or automatically by the system. When the
deactivate_object() method is invoked with this reason code, the transaction is marked for rollback only.
This reason code is used only for objects that have the
transaction activation policy. It can occur when the transaction is started by either the client or the TP Framework. It indicates that a
Current.commit() operation was invoked for the transaction in which the object is involved. The
deactivate_object() method is invoked just before the transaction manager’s two-phase commit algorithm begins; that is, before
prepare is sent to the resource managers.
The CORBA object is allowed to vote on the outcome of the transaction when the deactivate_object() method is invoked with the
DR_TRANS_COMMITTING reason code. By invoking
Current.rollback_only(), the method can force the transaction to be rolled back; otherwise, the two-phase commit algorithm continues. The transaction is not necessarily committed just because the
Current.rollback_only() is not invoked in this method. Any other CORBA object or resource manager involved in the transaction could also vote to roll back the transaction.
|
Note:
|
The deactivate_object method will be called at server shutdown time for every object remaining in the Active Object Map, whether it was entered there implicitly by the TP Framework (the activation-on-demand technique: TP::create_servant and the servant’s activate_object method) or explicitly by the user with TP::create_active_object_reference.
|
The activate_object() and
deactivate_object() methods and explicit methods invoked by the client can be used by the programmer to manage object state. The manner in which these methods are used to manage object state may vary according to the needs of the application. For a discussion of how these methods might be used, see
Creating CORBA Server Applications.
The CORBA object with transaction activation policy gets to vote on the outcome of the transaction when the
deactivate_object() method is invoked with the
DR_TRANS_COMMITTING reason code. By calling
Current.rollback_only() the method can force the transaction to be rolled back; otherwise, the two-phase commit algorithm continues. The transaction will not necessarily be committed just because
Current.rollback_only() is not called in this method. Any other CORBA object or resource manager involved in the transaction could also vote to roll back the transaction.
Similarly, when the invocation with reason code
DR_TRANS_ABORTED is made, the transaction manager is already aborting. While the transaction manager is aborting, it is not possible to either suspend a transaction or initiate a new transaction. The same restrictions apply as for
DR_TRANS_COMMITTING.
The client will never be notified about exceptions that are raised in deactivate_object(). It is the responsibility of the application code to check that the stored state of the CORBA object is consistent. For example, the application code could save a persistent flag that indicates whether or not
deactivate_object() successfully saved the state. That flag can then be checked in
activate_object().
If an error occurs while executing deactivate_object(), the application code should raise either a CORBA standard exception or a
DeactivateObjectFailed exception
. If
deactivate_object() was invoked by the TP Framework, the TP Framework catches the exception and the following events occur:
Where reason is a user-supplied reason, and
interfaceName and
oid are the interface ID and object ID, respectively, of the invoked CORBA object.
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.
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.
CORBA::Boolean _
is_reentrant()
The Tobj_ServantBase class provides a default implementation of the
_is_reentrant method that returns
FALSE.
Returns TRUE if the servant can support reentrancy.
|
•
|
The TP class is a C++ native class.
|
|
•
|
The TP.h file contains the declarations and definitions for the TP class.
|
class TP {
public:
static CORBA::Object_ptr create_object_reference(
const char* interfaceName,
const char* stroid,
CORBA::NVList_ptr criteria);
static CORBA::Object_ptr create_active_object_reference(
const char* interfaceName,
const char* stroid,
Tobj_Servant servant);
static CORBA::Object_ptr get_object_reference();
static void register_factory(
CORBA::Object_ptr factory_or,
const char* factory_id);
static void unregister_factory(
CORBA::Object_ptr factory_or,
const char* factory_id);
static void deactivateEnable()
static void deactivateEnable(
const char* interfaceName,
const char* stroid,
Tobj_Servant servant);
static CORBA::ORB_ptr orb();
static Tobj_Bootstrap* bootstrap();
static void open_xa_rm();
static void close_xa_rm();
static int userlog(char*, ... );
static char* get_object_id(CORBA::Object_ptr obj);
static void application_responsibility(
Tobj_Servant servant);
};
Returns a pointer to a Tobj::Tobj_Bootstrap object. The Bootstrap object is used to access initial object references for the FactoryFinder object, the Interface Repository, the TransactionCurrent, and the SecurityCurrent objects.
Upon successful completion, bootstrap() returns a pointer to the
Tobj::Tobj_Bootstrap object that is created by the TP Framework when the server application is started.
The TP Framework creates a Tobj::Tobj_Bootstrap object as part of initialization; it is not necessary for the application code to create any other
Tobj::Tobj_Bootstrap objects in the server.
The close_xa_rm() method closes the XA resource manager to which the invoking process is linked. XA resource managers are provided by database vendors, such as Oracle and Informix.
|
Note:
|
The functionality of this call is also provided by Tobj::TransactionCurrent::close_xa_rm(). The TP::close_xa_rm() method provides a more convenient way for a server application to close a resource manager because there is no need to obtain an object reference to the TransactionCurrent object. A reference to the TransactionCurrent object can be obtained from the Bootstrap object. See TP::bootstrap() for an explanation of how to obtain a reference to the Bootstrap object. For more information about the TransactionCurrent object, see the CORBA Bootstrapping Programming Reference section and Using CORBA Transactions.
|
This method should be invoked once from the Server::release() method for each server that is involved in global transactions. This includes servers that are linked with an XA resource manager, as well as servers that are involved in global transactions, but are not actually linked with an XA-compliant resource manager.
The close_xa_rm() method should be invoked in place of a close invocation that is specific to the resource manager. Because resource managers differ in their initialization semantics, the specific information needed to close a particular resource manager is placed in the
CLOSEINFO parameter in the
GROUPS section of the Oracle Tuxedo system
UBBCONFIG file.
The format of the CLOSEINFO string is dependent on the requirements of the database vendor providing the underlying resource manager. For more information about the
CLOSEINFO parameter, see
Setting Up a Oracle Tuxedo Application and the
ubbconfig(5) reference page in the
File Formats, Data Descriptions, MIBs, and System Processes Reference. Also, refer to database vendor documentation for information about how to develop and install applications that use the XA libraries.
The tx_close() call returned an error return code.
|
Note:
|
Unlike other exceptions returned by the TP Framework, the Tobj::RMFailed exception is defined in tobj_c.h (which is derived from tobj.idl), not TobjS_c.h (which is derived from TobjS.idl). This is because native clients can also open XA resource managers. Therefore, the exception returned is consistent with the exception expected by native client code and by Server::release() if it uses the alternate mechanism, TransactionCurrent::close_xa_rm, which is shared with native clients.
|
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 Oracle Tuxedo software cannot guarantee any uniqueness in object references, since these may be legitimately copied and shared outside the Oracle Tuxedo environment, for example by stringifying the object reference.
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.
|
•
|
In Server::initialize() to preactivate process objects so that they do not need activation on the first invocation.
|
where <CORBA interface name> is any object class name. For example:
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 Oracle Tuxedo software cannot guarantee any uniqueness in object references, since object references may be legitimately copied and shared outside the Oracle 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.
|
•
|
In Server::initialize() to create factories for the server.
|
Specifies the ObjectId in string format for the object to be deactivated.
Indicates that the TP::deactivateEnable method was invoked by an object with the activation policy set to
transaction.
|
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.
|
|
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.
|
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 Oracle Tuxedo transaction manager.
This method allows a server to retrieve the string ObjectId contained in an object reference that was created in the TP Framework. If the object reference was not created in the TP Framework (for example, it was created by a client ORB), an exception is raised.
The caller must call CORBA::string_free on the returned value when the object reference is no longer needed.
The string ObjectId passed to
TP::create_object_reference or
TP::create_active_object_reference when the object reference was created.
static CORBA::Object_ptr TP::get_object_reference ();
Note that if get_object_reference() is invoked from within either
Server::initialize() or
Server::release(), it is considered to be invoked outside the scope of an application’s TP object execution; therefore, the
TobjS::NilObject exception is raised.
The get_object_reference() method returns a
CORBA::Object_ptr for the current object when invoked within the scope of a CORBA object execution. Otherwise, the
TobjS::NilObject exception is raised.
The tx_open() call returned an error return code.
|
Note:
|
Unlike other exceptions returned by the TP Framework, this exception is defined in tobj_c.h (which is derived from tobj.idl), not in TobjS_c.h (which is derived from TobjS.idl). This is because native clients can also open XA resource managers. Therefore, the exception returned is consistent with the exception expected by native client code and by Server::release() if it uses the alternate mechanism, TransactionCurrent::close_xa_rm, which is shared with native clients.
|
The open_xa_rm() method opens the XA resource manager to which the invoking process is linked. XA resource managers are provided by database vendors, such as Oracle and Informix.
|
Note:
|
The functionality of this method is also provided by Tobj::TransactionCurrent::close_xa_rm(). However, TP::open_xa_rm() provides a more convenient way for a server application to close a resource manager because there is no need to obtain an object reference to the TransactionCurrent object. A reference to the TransactionCurrent object can be obtained from the Bootstrap object. See TP::bootstrap() for an explanation of how to obtain a reference to the Bootstrap object. For more information about the TransactionCurrent object, see the CORBA Bootstrapping Programming Reference section and Using CORBA Transactions.
|
This method should be invoked once from the Server::initialize() method for each server that participates in a global transaction. This includes servers that are linked with an XA resource manager, as well as servers that participate in a global transaction, but are not actually linked with an XA-compliant resource manager.
The open_xa_rm() method should be invoked in place of an open invocation that is specific to a resource manager. Because resource managers differ in their initialization semantics, the specific information needed to open a particular resource manager is placed in the
OPENINFO parameter in the
GROUPS section of the
UBBCONFIG file.
The format of the OPENINFO string is dependent on the requirements of the database vendor providing the underlying resource manager. For more information about the
CLOSEINFO parameter, see
Setting Up a Oracle Tuxedo Application and the
ubbconfig(5) reference page in the
File Formats, Data Descriptions, MIBs, and System Processes Reference. Also, refer to database vendor documentation for information about how to develop and install applications that use the XA libraries.
Access to the ORB object allows the application to invoke ORB operations, such as
string_to_object() and
object_to_string().
Upon successful completion, orb() returns a pointer to the
ORB object that is created by the TP Framework when the server program is started.
static void TP::register_factory(
CORBA::Object_ptr factory_or, const char* factory_id);
Indicates that the id string is empty. It is also raised if the field contains blank spaces or control characters.
Indicates that the id string is longer than 128 bytes (currently the maximum allowable length).
static void TP::unregister_factory (
CORBA::Object_ptr factory_or, const char* factory_id);
Indicates that the id string is empty. It is also raised if the field contains blank spaces or control characters.
Indicates that the id string is longer than 128 bytes (currently the maximum allowable length).
The first argument is a printf(3S) style format specification. The
printf(3S) argument is described in a C or C++ reference manual.
The userlog() method writes a message to the user log (
ULOG) file. Messages are appended to the
ULOG file with a tag made up of the time (hhmmss), system name, process name, and process-id of the invoking process. The tag is terminated with a colon.
The userlog() method returns the number of characters that were output, or a negative value if an output error was encountered. Output errors include the inability to open or write to the current log file.
For Tobj_ServantBase::deactivate_object(), the following line of code throws a
DeactivateObjectFailed exception:
Where 151104 is the time (3:11:04pm),
T1 is the system name,
simpapps is the process name,
247 is the process-id, and
APPEXC identifies the message as an application exception message.
