TP Framework

This chapter contains the following topics:

• TP Framework Interfaces. This section describes the following interfaces:

  • Tobj_Servant Interface

  • Server Interface

  • TP Interface

• Transactions Usage Notes. This section describes the following topics:

  • Transaction Termination

  • Transaction Suspend and Resume

  • Restrictions

  • Voting on Transaction Outcome

The WebLogic Enterprise TP Framework provides a programming framework that enables users to create servers for high-performance TP applications. This chapter describes the architecture of and interfaces in the TP Framework. Information about the TP Framework API is in the Java API Reference. Information about how to use this API can be found in Creating Java Server Applications.

The TP Framework consists of:

• The com.beasys.Tobj_Servant class, which has virtual methods for object state management

• The com.beasys.Tobj.Server class, which has virtual methods for application-specific server initialization and termination logic

• The com.beasys.Tobj.TP class, which provides methods to:

  • Create object references for CORBA objects

  • Register (and unregister) factories with the FactoryFinder object

  • Initiate user-controlled deactivation of the CORBA object currently being invoked

  • Obtain an object reference to the CORBA object currently being invoked

  • Open and close XA resource managers

  • Log messages to a user log (ULOG) file

  • Obtain object references to the ORB and to Bootstrap objects

• Header files for these classes

• A library to be link-edited with server applications

TP Framework Interfaces

The TP Framework supports the following interfaces:

• com.beasys.Tobj_Servant

• com.beasys.Tobj.Server

• com.beasys.Tobj.TP

• org.omg.CosTransactions.TransactionalObject (deprecated in the previous release)

Tobj_Servant Interface

The com.beasys.Tobj_Servant interface defines operations that allow a CORBA object to assist in the management of its state. Every implementation skeleton generated by the IDL compiler automatically inherits from the com.beasys.Tobj_Servant class. The com.beasys.Tobj_Servant class contains two virtual methods, activate_object and deactivate_object, that can be redefined 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 deactivate_object is invoked, the TP Framework passes in a reason code to indicate why the call was made.

Note: The activate_object and deactivate_object methods 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. Therefore, the server-application code must not do any state handling for CORBA objects in either the constructor or destructor of the servant class.

Server Interface

The com.beasys.Tobj.Server interface provides callback methods that can be used for application-specific server initialization and termination logic. The com.beasys.Tobj.Server class is a Java class.

Note: Unlike implementing C++ server applications with the WebLogic Enterprise system, when you are implementing Java server applications with the WebLogic Enterprise system, you must provide definitions for the com.beasys.Tobj.Server.initialize and com.beasys.Tobj.Server.release methods. The TP Framework provides default versions of these methods.

TP Interface

The com.beasys.Tobj.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.

The purpose of this interface is to provide high-level calls that application code can call, instead of calls to underlying APIs provided by the Portable Object Adapter (POA), the CORBAservices Naming Service, and the BEA TUXEDO system. By using these calls, programmers can learn a simpler API and are spared the complexity of the underlying APIs.

The com.beasys.Tobj.TP interface implicitly uses two features of the WebLogic Enterprise software that extend the CORBA APIs:

• Factories and the FactoryFinder object

• Factory-based routing

Usage Notes

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.

TransactionalObject Interface Not Enforced

The org.omg.CosTransactions.TransactionalObject interface was formerly used to indicate that an object was transactional. In the previous version of the WebLogic Enterprise software, if a transactional invocation was done on an object that did not descend from the org.omg.CosTransactions.TransactionalObject interface, an exception was raised. Therefore, in the previous version, an object had to descend from the org.omg.CosTransactions.TransactionalObject interface to be eligible to participate in transactions. This behavior was enforced by the TP Framework.

However, in version 2.1 of the WebLogic Enterprise software, this interface is 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. By specifying the never or ignore transaction policies, the programmer can specify that an object is not to be infected by transactions. There is no interface enforcement for eligibility for transactions. The only indicator is the transaction policy.

Note: The CORBAservices Object Transaction Service does not require that all requests be performed within the scope of a transaction. It is up to each object to determine its behavior when invoked outside the scope of a transaction; an object that requires a transaction context can raise a standard exception.

Transactions Usage Notes

The following sections provide some information about how to use transactions.

Transaction Termination

In general, the handling of the outcome of a transaction is the responsibility of the initiator. Therefore, the following is true:

• If the client or server application code initiates transactions, the TP Framework never commits a transaction. The WebLogic Enterprise system may roll back the transaction if server processing tries to return to the client with the transaction in an illegal state.

• If the system initiates a transaction, the commit or rollback will always be handled by the WebLogic Enterprise system.

The following behavior is enforced by the WebLogic Enterprise system:

• 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 org.omg.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.

Transaction Suspend and Resume

The CORBA object must follow strict rules with respect to suspending and resuming a transaction within a method invocation. These rules and the error conditions that result from their violation are described in this section.

When a CORBA object method begins execution, it can be in one of the following three states with respect to transactions:

• The client application began the transaction.

  • Valid server application behavior: Suspend and resume the transaction within the method execution.

  • Invalid 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 invalid behavior occurs, the TP Framework raises the org.omg.CORBA.TRANSACTION_ROLLEDBACK exception to the client application and the transaction is rolled back by the WebLogic Enterprise system.

• The system began a transaction to provide AUTOTRAN or transaction policy always behavior.

  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, refer to the Administration Guide.

  • Valid server behavior: Suspend and resume the transaction within the method execution.

    Note: Not recommended. The transaction may be timed out and aborted before another request causes the transaction to be resumed.

  • Invalid 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 invalid behavior occurs, the TP Framework raises the org.omg.CORBA.OBJ_ADAPTER exception to the client and the transaction is rolled back by the system. The org.omg.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.

• The CORBA object is not involved in a transaction when it starts executing.

  • Valid server behavior:
    • Begin and commit a transaction within the method execution.
    • Begin and roll back a transaction within the method execution.
    • Begin and suspend a transaction within the method execution.

  • Invalid server behavior: Begin a transaction and return from the method with the transaction active.

  • Error Processing: If invalid behavior occurs, the TP Framework raises the org.omg.CORBA.OBJ_ADAPTER exception to the client application and the transaction is rolled back by the WebLogic Enterprise system. The org.omg.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.

Restrictions

The following restrictions apply to WebLogic Enterprise transactions:

• A CORBA object in the WebLogic Enterprise system must have the same transaction context when it returns from a method invocation that it had when the method was invoked.

• A CORBA object can be infected by only one transaction at a time. If an invocation tries to infect an already infected object, an org.omg.CORBA.INVALID_TRANSACTION exception is returned.

• If a CORBA object is infected with a transaction and a nontransactional request is made on it, an org.omg.CORBA.OBJ_ADAPTER exception is raised.

• If the application begins a transaction in the com.beasys.Tobj.Server.initialize method, it must either commit or roll back the transaction before returning from the method. If it does not, the TP Framework shuts down the server. This is because the application has no predictable way of regaining control after completing the 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 com.beasys.Tobj_Servant.deactivate_object method. Such an invocation results in an org.omg.CORBA.BAD_INV_ORDER exception.

• If an object generates a user exception within a system-generated transaction (that is, the client did not begin a transaction explicitly), the client application receives the org.omg.CORBA.OBJ_ADAPTER system exception and not the user exception.

Voting on Transaction Outcome

CORBA objects can affect transaction outcome during two stages of transaction processing:

• During transactional work

  The org.omg.CORBA.Current.rollback_only method can be used to ensure that the only possible outcome is to roll back the current transaction. The rollback_only method can be invoked from any CORBA object method.

• After completion of transactional work

  CORBA objects that have the transaction activation policy are given a chance to vote whether the transaction should commit or roll back after transactional work is completed. These objects are notified of the completion of transactional work prior to the start of the two-phase commit algorithm when the TP Framework invokes its deactivate_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 invoke the org.omg.CORBA.Current.rollback_only method. 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: CORBA objects that have the transaction activation policy are, by definition, notified when a transaction completes, as described above. However, CORBA objects that have a method or process activation policy do not receive any notification. This is something that programmers need to be aware of. For example, consider a CORBA object with activation policy set to process that opens an SQL cursor within a client-initiated transaction. Typically, once the client application commits the transaction, all cursors that were opened within that transaction are automatically closed; however, the object does not receive any notification that its cursor has been closed.