• A Simple Programming Model. This section describes:
• State Management. This section describes:
• Transactions. This section describes:State management involves the saving and restoring of object state on object deactivation and activation. It also concerns the duration of activation of objects, which influences the performance of servers and their resource usage. The external API of the TP Framework provides activate_object and deactivate_object methods, which are a possible location for state management code.The activation policy determines the default in-memory activation duration for a CORBA object. A CORBA object is active in a POA if the POA's active object map contains an entry that associates an object ID with an existing servant. Object deactivation removes the association of an object ID with its active servant. You can choose from one of three activation policies: method (the default), transaction, or process.
Note:
• method (This is the default activation policy.)
• If a user-initiated transaction is in effect when the object is activated, the object is deactivated when the first of the following occurs: the transaction is committed or rolled back, or the server is shut down in an orderly fashion. The latter is done using either the tmshutdown or tmadmin command. These commands are described in the Oracle Tuxedo Command Reference online document.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.
Note: This is a model of resource allocation that is similar to that of an Oracle Tuxedo conversational service. However, this model is less expensive than the Oracle Tuxedo conversational service in that it uses fewer system resources. This is because of the Oracle Tuxedo ORB’s multicontexted dispatching model (that is, the presence of many servants in memory at the same time for one server), which makes it possible for a single server process to be shared by many concurrently active servants that service many clients. In the Oracle Tuxedo system, the process would be dedicated to a single client and to only one service for the duration of a conversation.
•
Note: The TP Framework API provides an interface method (TP::deactivateEnable) that allows the application to control the timing of object deactivation for objects that have the activation policy set to process. For a description of this method, see the section TP::deactivateEnable().Application code can bypass the on-demand activation feature of the TP Framework for objects that use the process activation policy. The application can “preactivate” an object (that is, activate it before any invocation) using the TP::create_active_object_reference call.Preactivation works as follows. Before the application creates an object reference, the application instantiates a servant and initializes that servant’s state. The application uses TP::create_active_object_reference to put the object into the Active Object Map (that is, associate the servant with an ObjectId). Then, when the first invocation is made, the TP Framework immediately directs the request to the process that created the object reference and then to the existing servant, bypassing the necessity to call Server::create_servant and then the servant’s activate_object method (just as if this were the second or later invocation on the object). Note that the object reference for such an object will not be directed to another server and the object will never go through on-demand activation as long as the object remains activated.Since the preactivated object has the process activation policy, it will remain active until one of two events occurs: (1) the ending of the process or (2) a TP::deactivateEnable call.Preactivation is especially useful if the application needs to establish the servant with an initial state in the same process, perhaps using shared memory to initialize state. Waiting to initialize state until a later time and in a potentially different process may be very difficult if that state includes pointers, object references, or complex data structures. TP::create_active_object_reference guarantees that the preactivated object is in the same process as the code that is doing the preactivation. While this is convenient, preactivation should be used sparingly, as should all process objects, because it preallocates precious resources. However, when needed and used properly, preallocation is more efficient than alternatives.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.When the client is finished with the iterator object, it invokes a final method on the initial object which deacativates the iterator object. The initial object deactivates the iterator object by invoking a method on the iterator object that calls the TP::deactivateEnable method, that is, the iterator object calls TP::deactivateEnable on itself.The solution is to refuse to allow the object to be activated automatically by the TP Framework. If the user provides the TobjS::ActivateObjectFailed exception to the TP Framework as a result of the activate_object call, the TP Framework will not complete the activation and will return an exception to the client, CORBA::OBJECT_NOT_EXIST. The client has presumably been warned about this possibility, since it knows about the iterator (or similar) pattern. The client must be prepared to restart the iteration.
Note: This defensive measure may not be necessary in the future; the TP Framework itself may detect that the object reference is no longer valid. In particular, you should not depend on the possibility that the activate_object method might be called. If the TP Framework does in fact change, activate_object will not be called and the framework itself will generate the OBJECT_NOT_EXIST exception.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.To ensure the desired behavior, make sure that the object is not in a transaction or ensure that no invokes occur on the object after the TP::deactivateEnable() call until the transaction is complete.In the normal case, the TP Framework completely controls the lifetime of a servant. The basic model is that, when a request for an inactive object arrives, the TP Framework obtains a servant and then activates it (by calling its activate_object method). At deactivation time, the TP Framework calls the servant’s deactivate_object method and then disposes of the servant.The phase “the TP Framework obtains a servant” means that when the TP Framework needs a servant to be created, it calls a user-written Server method, either Server::create_servant or ServerBase::create_servant_with_id. At that time, the application code must return a pointer to the requested servant. The application almost always does this by using the C++ “new” statement to create a new instance of a servant. The phrase “disposes of the servant” means that the TP Framework removes the reference to the servant, which actually deletes it.The application must be aware that this current behavior of always creating and removing a servant may change in future versions of this product. The application should not depend on the current behavior, but should write servant code that allows reuse of a servant. Specifically, the servant code must work even if the servant has not been freshly created (by the C++ “new” statement). The TP Framework reserves the right not to remove a servant after it has been deactivated and then to reactivate it. This means that the servant must completely initialize itself at the time of the callback on the servant’s activate_object method, not at the time of servant creation (not in the constructor).The application can alter the “obtaining” mechanism by using explicit preactivation. In this case, the application creates and initializes a servant before asking the TP Framework to declare it activated. Once such a servant has been turned over to the TP Framework (by the TP::create_active_object_reference call), that servant is treated by the TP Framework just like every other servant. The only difference is in its method of creation and initialization.The application can alter the “disposing” mechanism by taking the responsibility for disposing of a servant instead of leaving that responsibility with the TP Framework. Once a servant is known to the TP Framework (through Server::create_servant, ServerBase::create_servant_with_id, or TP::create_active_object_reference), the TP Framework’s default behavior is to remove that servant itself. In this case, the application code must no longer use references to the servant after deactivation.However, the application may tell the TP Framework not to dispose of the servant after the TP Framework deactivates it. Taking responsibility for a servant is done on an individual servant basis, not for a whole class of servants, by calling Tobj_ServantBase::_add_ref with a parameter identifying the servant.
Note: In applications written using Oracle Tuxedo release 8.0 or later, use the Tobj_ServantBase::_add_ref method instead of the TP::application_responsibility() method. Unlike the TP::application_responsibility() method, the add_ref() method takes no arguments.The advantage of the application taking responsibility for the servant is that the servant does not have to be created anew. If obtaining the servant is an expensive proposition, the application may choose to save the servant and reuse it later. This is especially likely to be true for servants for preactivated objects, but is true in general. For example, the next time the TP Framework makes a call on Server::create_servant or ServerBase::create_servant_with_id, the application might return a previously saved servant.Additionally, once an application has taken responsibility for a servant, the application must take care to remove the servant (using Tobj_ServantBase::_remove_ref) when the servant is no longer needed, that is, when the reference count drops to zero, the same as for any other C++ instance. For more information about how the _remove_ref() method works, see Tobj_ServantBase::_remove_ref().For more information on writing single-threaded and multithreaded server applications, see Creating CORBA Server Applications.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.
Note:
• The implementation is not transactional. Objects created for this interface can never be involved in a transaction. The system generates an exception (INVALID_TRANSACTION) if an implementation with this policy is involved in a transaction. An AUTOTRAN policy specified in the UBBCONFIG file for the interface is ignored.
• The implementation is not transactional. This policy instructs the system to allow requests within a transaction to be made of this implementation. An AUTOTRAN policy specified in the UBBCONFIG file for the interface is ignored.
• optional (This is the default transaction_policy.)The implementation may be transactional. Objects can be involved in a transaction if the request is transactional. Servers containing transactional objects must be configured within a group associated with an XA-compliant resource manager. If the AUTOTRAN parameter is specified in the UBBCONFIG file for the interface, AUTOTRAN is on.
• The implementation is transactional. Objects are required to always be involved in a transaction. If a request is made outside a transaction, the system automatically starts a transaction before invoking the method. The transaction is committed when the method ends. (This is the same behavior that results from specifying AUTOTRAN for an object with the option transaction policy, except that no administrative configuration is necessary to achieve this behavior, and it cannot be overridden by administrative configuration.) Servers containing transactional objects must be configured within a group that is associated with an XA-compliant resource manager.
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.
• Transaction policy always
• For more information, see Using CORBA Transactions.
• If no transaction is active when a method on a CORBA object is invoked and that method begins a transaction, the transaction must be either committed, rolled back, or suspended when the method invocation returns. If none of these actions is taken, the transaction is rolled back by the TP Framework, and the CORBA::OBJ_ADAPTER exception is raised to the client application. This exception is raised because the transaction was initiated in the server application; therefore, the client application would not expect a transactional error condition such as TRANSACTION_ROLLEDBACK.
• Legal server application behavior: Suspend and resume the transaction within the method execution.
• 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.
• Legal server behavior: Suspend and resume the transaction within the method execution.
• 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.
• Illegal server behavior: Begin a transaction and return from the method with the transaction active.
• 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.
• A CORBA object can be infected by only one transaction at a time. If an invocation tries to infect an already infected object, a CORBA::INVALID_TRANSACTION exception is returned.
• If a CORBA object is infected with a transaction and a nontransactional request is made on it, a CORBA::OBJ_ADAPTER exception is 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.
• If a CORBA object is infected by a transaction and with an activation policy of transaction, and if the reason code passed to the method is either DR_TRANS_COMMITTING or DR_TRANS_ABORTED, no invocation on any CORBA object can be done from within the Tobj_ServantBase::deactivate_object method. Such an invocation results in a CORBA::BAD_INV_ORDER exception.
• The SQL COMMIT and ROLLBACK statements cannot be used to terminate a global transaction that has been either started explicitly using Current.begin() or started implicitly by the system. Check the database vendor documentation for each database product for other possible restrictions when using global transactions.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.When a transaction timeout occurs, the transaction is marked so that the only possible outcome is to roll back the transaction, and the CORBA::TRANSACTION_ROLLEDBACK standard exception is returned to the client. Any attempts to send new requests will also fail with the CORBA::TRANSACTION_ROLLEDBACK exception until the transaction has been aborted.IIOP client failover marks an interface implementation as idempotent. An idempotent implementation is one that can be repeated without any negative side-effects. For example, SET BALANCE.In order to mark an interface implementation as idempotent, you must set the retry policy in the implementation configuration file (ICF) using the retry_policy option. For a description of the ICF, refer to the Implementation Configuration File (ICF) section.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.You can also check the retry policy using the TA_RTPOLICY attribute added to the MIB(5) T_IFQUEUE and T_INTERFACE classes. The TA_RTPOLICY attribute value is either never or always.To initiate IIOP client failover support, ISL servers must be specified using the -C warn|none option in the *SERVERS section of the UBBCONFIG fileThis option allows ISL to accept unofficial connection directly from the client orb. ISL servers that are not specified using the -C warn|none option will not be placed in candidate IIOP gateway pools. Consequently, the client will not failover to those ISL servers.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 CORBA C++ client supports failover to WebLogic clustering servers and also supports load balancing. For more information, see WebLogic documentation - Failover and Replication in a Cluster and Load Balancing in a Cluster.For more information on parallel objects, see Scaling, Distributing, and Tuning CORBA Applications.In release 8.0 of the Oracle Tuxedo software, the Implementation Configuration File (ICF) was modified to support user-controlled concurrency. In Listing 3‑2, the changes to add this support are highlighted in bold type. For a description of the ICF syntax, see ICF Syntax.Listing 3‑2 ICF Syntax[#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);]
};
[};]The TP Framework handles active user-controlled concurrency objects in the same manner as system-controlled concurrency objects. The TP Framework stores information about objects in the local AOM, and calls the activate_object and deactivate_object methods at the appropriate times. However, the object will not have an entry in the AOM and the TP Framework will not call any AOM routines. For example, on shutdown, since an active object will not have an AOM handle, calls to remove the entry from the AOM will not be invoked.
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.This section describes the TP Framework API. Additional information about how to use this API can be found in Creating CORBA Server Applications.
• 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:
• Log messages to a user log (ULOG) file
• Callback methods that are written by the user and that are invoked by the TP Framework. This includes methods in the Tobj_ServantBase and Server classes. These operations are intended to be called by TP Framework code only. The application code should never call the methods of these classes. If it does, unpredictable results may occur.
• The Server class is a C++ native class.
• The Server.h file contains the declarations and definitions for the Server class.The serverBase interface allows you to take full advantage of multithreading capabilities. You can create your own Server classes that inherit from the ServerBase class. This provides you with the following:
• The create_servant_with_id() method to support implementations requiring knowledge of the target object during the creation of a servantThe 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_initialize()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.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:"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."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."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."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.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.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.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.A pointer to the newly created servant (instance) for the specified interface. Returns NULL if either of these conditions is true: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.Typically, a server application does the following tasks in Server::initialize:
• Creates references for CORBA object factories implemented in the server application and registers them with the FactoryFinder using the TP::register_factory() operation.
• 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.
• Tobj::TransactionCurrent::open_xa_rm()
A reference to the TransactionCurrent object can be obtained from the Bootstrap object. For an explanation of how to obtain a reference to the Bootstrap object, see the section TP::bootstrap(). For more information about the TransactionCurrent object, see the CORBA Bootstrapping Programming Reference section and Using CORBA Transactions.
• 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.If the return value is FALSE:
• Server::release() is not invoked.
• Any transactions that are started in the initialize() method and are not terminated will eventually time out; they are not automatically rolled back.CORBA::Boolean thread_initialize(int argc, char** argv)The number of arguments provided to the application. Initially, this count is passed to the main function.The arguments provided to the application. Initially, these arguments are passed to the main function.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:"TPFW_CAT:2: WARN: Exception in Server::release(): IDL:beasys.com/TobjS/ReleaseFailed:1.0. Reason = reason"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.
• Unregister CORBA object factories that were registered with the FactoryFinder in Server::initialize().This method is normally called in response to a tmshutdown command from the administrator or operator.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.
• Tobj::TransactionCurrent::close_xa_rm(). A reference to the TransactionCurrent object can be obtained from the Bootstrap object. For an explanation of how to obtain a reference to the Bootstrap object, see the section TP::bootstrap(). For more information about the TransactionCurrent object, see CORBA Bootstrapping Programming Reference and Using CORBA Transactions.
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.Whenever a request comes in for an inactive CORBA object, the object is activated and the activate_object() method is invoked on the servant. When the CORBA object is deactivated, the deactivate_object() method is invoked on the servant. The timing of deactivation is driven by the implementation’s activation policy. When the deactivate_object() method is invoked, the TP Framework passes in a reason code to indicate why the call was made.
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.The C++ mapping for the Tobj_servantBase interface is as follows: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.Object activation is triggered by a client invoking a method on an inactive CORBA object. This causes the Portable Object Adapter (POA) to assign a servant to the CORBA object. The activate_object() method is invoked before the method invoked by the client is invoked. If activate_object() returns successfully, that is, without raising an exception, the requested method is executed on the servant.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 the object is currently infected with a global transaction, activate_object() executes within the scope of that same global transaction.It is the responsibility of the programmer of the object to check that the stored state of the object is consistent. In other words, it is up to the application code to save a persistent flag that indicates whether or not deactivate_object() successfully saved the state of the object. That flag should be checked in activate_object().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.
• Based on the exception is raised, a message is written to the user log (ULOG) file, as follows:"TPFW_CAT:24: ERROR: Activating object - application raised TobjS::ActivateObjectFailed. 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."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."TPFW_CAT:25: 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."TPFW_CAT:26: 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.
Note: In applications written using Oracle Tuxedo release 8.0 or later, use this method instead of the TP::application_responsibility() method.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.Indicates the event that caused this method to be invoked. The reason code can be one of the following:- transaction (only if there is no transaction in effect)- process (if TP::deactivateEnable() called)- transaction (only if transaction is active)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.Indicates that the object is being deactivated because the application executed a TP::deactivateEnable(-,-,-) on this object. This can happen only for objects that have the process activation policy.Object deactivation is initiated either by the system or by the application, depending on the activation policy of the implementation for the CORBA object. The deactivate_object() method is invoked before the CORBA object is deactivated. For details of these policies and their use, see the section ICF Syntax.Deactivation may occur after an execution of a method invoked by a client if the activation policy for the CORBA object implementation is method, or as a result of the end of transactional work if the activation policy is transaction. It may also occur as the result of server shutdown if the activation policy is transaction or process.In addition, the Oracle Tuxedo software supports the use of user-controlled deactivation of CORBA objects having an activation policy of process or method via the use of the TP::deactivateEnable() and TP::deactivateEnable(-,-,-) methods. TP::deactivateEnable can be called inside a method of an object to cause the object to be deactivated at the end of the method. If TP::deactivateEnable is called in an object with the transaction activation policy, an exception is raised (TobjS::IllegalOperation) and the TP Framework takes no action. TP::deactivateEnable(-,-,-) can be called to deactivate any object that has a process activation policy. For more information, see the section TP::deactivateEnable().
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.Note that if the object is involved in a transaction when this method is invoked, there are restrictions on what type of processing can be done based on the reason the object is invoked. If the object was involved in a transaction, the activation policy is transaction and the reason code for the call is:No invocations on any CORBA objects are allowed in the method. No tpcall() is allowed. Transactions cannot be suspended or begun.No invocations on any CORBA objects are allowed in the method. No tpcall() is allowed. Transactions cannot be suspended or begun.The reason for these restrictions is that the deactivation of objects with activation policy transaction is controlled by a call to the TP Framework from the transaction manager for the transaction. When the call with reason code DR_TRANS_COMMITTING is made, the transaction manager is executing phase 1 (prepare) of the two-phase commit. At this stage, it is not possible to issue a call to suspend a transaction nor to initiate a new transaction. Since a call to a CORBA object that was in another process would require that process to join the transaction, and the transaction manager is already executing the prepare phase, this would cause an error1. Since a call to a CORBA object that had no transactional properties would require that the current transaction be suspended, this would also cause an error. The same is true of a tpcall().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.If the CORBA object method that is invoked by the client raises an exception, that exception is caught by the TP Framework and is eventually returned to the client. This is true even if deactivate_object() is invoked and raises an exception.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:
• The client is not notified of the exception that is raised in deactivate_object().
• Based on which exception is raised, a message is logged to the user log (ULOG) file, as follows:"TPFW_CAT:27: ERROR: De-activating object - application raised TobjS::DeactivateObjectFailed. 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."TPFW_CAT:28: ERROR: De-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."TPFW_CAT:29: ERROR: De-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.The Tobj_ServantBase class provides a default implementation of the _is_reentrant method that returns FALSE.Returns TRUE if the servant can support reentrancy.
Note: In applications written using Oracle Tuxedo release 8.0 or later, use this method instead of the C++ “delete” statement that you used previously with the TP::application_responsibility() method.Invoke this method when a reference to a servant is no longer needed. Invoking this method causes the reference count for the servant to be decremented by one. If the _remove_ref() method brings the reference count to zero, it also calls the C++ “delete” statement on its own this pointer and deletes the servant.The TP interface supplies a set of service methods that can be invoked by application code. This is the only interface in the TP Framework that can safely be invoked by application code. All other interfaces have callback methods that are intended to be invoked only by system code.For information about the FactoryFinder object, see the section FactoryFinder Interface. For more information about factory-based routing, see Setting Up a Oracle Tuxedo Application.
• During server application initialization, the application constructs the object reference for an application factory. It then invokes the register_factory() method, passing in the factory's object reference together with a factory id field. On server release (shutdown), the application uses the unregister_factory() method to unregister the factory.
• The TP class is a C++ native class.
• C++ Declarations (in TP.h)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);
};
Note: Do not use this method in applications written using Oracle Tuxedo release 8.0 or later; instead, use the Tobj_ServantBase::_add_ref() method.This method tells the TP Framework that the application is taking responsibility for the servant’s lifetime. As a result of this call, when the TP Framework has completed deactivating the object (that is, after invoking the servant’s deactivate_object method), the TP Framework does nothing more with the object.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.
Caution: Because the TP Framework owns the Tobj::Tobj_Bootstrap object, server application code must not dispose of the Bootstrap object.
Note: If you are using the CORBA INS bootstrap mechanism and you are not using the SecurityCurrent for security or TransactionCurrent for transactions, you do not need to use the Bootstrap object.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.There is an active transaction. The resource manager cannot be closed while a transaction is active.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 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.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.The object could not be activated explicitly because it does not have the process activation policy.
• In Server::initialize() to preactivate process objects so that they do not need activation on the first invocation.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.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.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.
1. 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.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.static CORBA::Object_ptr TP::create_object_reference (
const char* interfaceName,
const char* stroid,
CORBA::NVList_ptr criteria);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.
Note: The restriction on the length of the ObjectId has been removed in this release.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 Oracle Tuxedo system administrator configures factory-based routing by specifying routing rules in the UBBCONFIG file. See Setting Up a Oracle Tuxedo Application online document for details on this facility.The following exceptions can be raised by the create_object_reference() method:Indicates that the specified interfaceName is NULL.Indicates that the specified stroid is NULL.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.
• In Server::initialize() to create factories for the server.For examples of how and when to call the create_object_reference() method, see Creating CORBA Server Applications.Specifies the ObjectId in string format for the object to be deactivated.The following exceptions can be raised by the deactivateEnable() method:Indicates that the TP::deactivateEnable method was invoked by an object with the activation policy set to transaction.In the Any-object format, the object specified could not be deactivated because it was not active (the stroid and servant parameters did not identify an object that was in the Active Object Map).
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.To ensure the desired behavior, make sure that the object is not in a transaction or ensure that no invokes occur on the object after the TP::deactivateEnable() call until the transaction is complete.
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.When the object is deactivated, the TP Framework first removes the object from the Active Object Map. It then calls the associated servant’s deactivate_object method with a reason of DR_METHOD_END.The application can request deactivation of an object by specifying its ObjectId and the associated servant.If the object is currently executing, the TP Framework marks it for deactivation and waits until the object’s method completes before deactivating the object (as with the “current-object format”). If the object is not currently executing, the TP Framework may deactivate it immediately. No indication is given to the caller as to the status of the deactivation. When the object is deactivated, the TP Framework first removes the object from the Active Object Map. It then calls the associated servant’s deactivate_object method with a reason of DR_EXPLICIT_DEACTIVATE.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.Allows a server to retrieve the string ObjectId contained in an object reference that was created in the TP Framework.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.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 following exception can be raised by the get_object_reference() method:Indicates that the method was invoked outside the scope of an application’s CORBA object execution. The reason string contains OutOfScope.This method returns a pointer to the current object. The CORBA::Object_ptr pointer that is returned can be passed to a client.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.Returns a pointer to an ORB object.static CORBA::ORB_ptr TP::orb();Access to the ORB object allows the application to invoke ORB operations, such as string_to_object() and object_to_string().
Note: Because the TP Framework owns the ORB object, the application must not delete it.Upon successful completion, orb() returns a pointer to the ORB object that is created by the TP Framework when the server program is started.Specifies the object reference that was created for an application factory using the TP::create_object_reference() method.Specifies a string identifier that is used to identify the application factory. For some suggestions as to the composition of this string, see Creating CORBA Server Applications.The following exceptions can be raised by the register_factory() method:Indicates that the FactoryFinder encountered an internal error during the search, with the error being written to the user log (ULOG). Notify the operations staff immediately if this exception is raised. Depending on the severity of the internal error, the server running the FactoryFinder or the NameManager may have terminated. If a FactoryFinder service has terminated, start a new FactoryFinder service. If the NameManager has terminated, and there is another NameManager running, start a new one. If no NameManagers are running, restart the application.Indicates that the id string is empty. It is also raised if the field contains blank spaces or control characters.Indicates that the factory value is nil.
Note: Another possible reason that this exception might occur is that the FactoryFinder cannot participate in a transaction. Therefore, you may need to suspend the current transaction before issuing the TP::register_factory() and TP::unregister_factory() calls. For information on suspending and resuming transactions, see Using CORBA Transactions in the online documentation.Indicates that the id string is longer than 128 bytes (currently the maximum allowable length).This method locates the Oracle Tuxedo FactoryFinder object and registers an Oracle Tuxedo factory. Typically, TP::register_factory() is invoked from Server::initialize() when the server creates its factories. The register_factory() method locates the Oracle Tuxedo FactoryFinder object and registers the Oracle Tuxedo factory.Specifies the object reference that was created for an application factory using the TP::create_object_reference() method.Specifies a string identifier that is used to identify the application factory. For some suggestions as to the composition of this string, see Creating CORBA Server Applications.The following exceptions can be raised by the unregister_factory() method:Indicates that the FactoryFinder encountered an internal error during the search, with the error being written to the user log (ULOG). Notify the operations staff immediately if this exception is raised. Depending on the severity of the internal error, the server running the FactoryFinder or the NameManager may have terminated. If a FactoryFinder service has terminated, start a new FactoryFinder service. If the NameManager has terminated, and there is another NameManager running, start a new one. If no NameManagers are running, restart the application.Indicates that the id string is empty. It is also raised if the field contains blank spaces or control characters.
Note: Another possible reason that this exception might occur is that the FactoryFinder cannot participate in a transaction. Therefore, you may need to suspend the current transaction before issuing the TP::register_factory() and TP::unregister_factory() calls. For information on suspending and resuming transactions, see Using CORBA Transactions in the online documentation.Indicates that the id string is longer than 128 bytes (currently the maximum allowable length).This method locates the Oracle Tuxedo FactoryFinder object and removes a factory. Typically TP::unregister_factory() is invoked from Server::release() to unregister server factories.Writes a message to the user log (ULOG) file.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.We recommend that server applications limit their use of userlog() messages to messages that can be used to help debug application errors; flooding the ULOG file with incidental information can make it difficult to spot actual errors.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.The following example shows how to use the TP::userlog() method:Use of this interface is now deprecated. Therefore, the use of this interface is now optional and no enforcement of descent from this interface is done for objects infected with transactions. The programmer can specify that an object is not to be infected by transactions by specifying the never or ignore transaction policies. There is no interface enforcement for eligibility for transactions. The only indicator is the transaction policy.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.Exceptions that are raised in either CORBA object methods or in TP Framework callback methods will not automatically cause a transaction to be rolled back unless the TP Framework started the transaction. It is up to the application code to call Current.rollback_only() if the condition that caused the exception to be raised should also cause the transaction to be rolled back.The TP Framework will detect the fact that a second CORBA object is acting as a client to an object that is already processing a method invocation, and will return a CORBA::OBJ_ADAPTER exception to the caller.