com.beasys.Tobj
Class TP

java.lang.Object
  |
  +--com.beasys.Tobj.TP

public class TP

extends java.lang.Object

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.

Constructor Summary

TP()

Method Summary

static Tobj_Bootstrap	bootstrap() Returns a com.beasys.Tobj_Bootstrap object.
static void	close_xa_rm() Closes the XA resource manager to which the invoking process is linked.
static org.omg.CORBA.Object	create_object_reference(java.lang.String interfaceName, java.lang.String stroid, org.omg.CORBA.NVList criteria) Creates an object reference.
static void	deactivateEnable() Enables application-controlled deactivation of CORBA objects.
static org.omg.CORBA.Object	get_object_reference() Returns a pointer to the current object.
static int	open_xa_rm() Opens the XA resource manager to which the invoking process is linked.
static org.omg.CORBA.ORB	orb() Returns an ORB object.
static void	register_factory(org.omg.CORBA.Object objp, java.lang.String id) Locates the M3 FactoryFinder object and registers an M3 factory.
static void	unregister_factory(org.omg.CORBA.Object objp, java.lang.String id) Locates the M3 FactoryFinder object and removes an M3 factory.
static int	userlog(java.lang.String str) Writes a message to the user log (ULOG) file.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TP

public TP()

Method Detail

create_object_reference

public static org.omg.CORBA.Object create_object_reference(java.lang.String interfaceName,
                                                           java.lang.String stroid,
                                                           org.omg.CORBA.NVList criteria)
                                                    throws InvalidInterface,
                                                           InvalidObjectId

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

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

• In the com.beasys.Tobj.Server.initialize method to create factories for the server.

• In factory methods to create object references to be returned to clients.

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

Parameters:

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

stroid - Specifies the object ID in string format. The object ID uniquely identifies this instance of the class. It is up to the programmer to decide what information to place in the object ID. One possibility would be to use the object ID to hold a database key. Choosing the value of an object identifier, and the degree of uniqueness, is part of the application design. The M3 software cannot guarantee any uniqueness in object references, since object references may be legitimately copied and shared outside the M3 domain (for example, by passing the object reference as a string).

criteria - Specifies a list of named values that can be used to provide factory-based routing for the object reference. 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.

Returns:

The newly created object reference.

Throws:

InvalidInterface - Indicates that the specified interface_name is null.

InvalidObjectId - Indicates that the specified stroid is null.

get_object_reference

public static org.omg.CORBA.Object get_object_reference()
                                                 throws NilObject

Returns a pointer to the current object.

Returns:

The current object when invoked within the scope of a CORBA object execution. Otherwise, the com.beasys.TobjS.NilObject exception is raised.

Note: If the get_object_reference method is invoked from within either the com.beasys.com.Tobj.Server.initialize or com.beasys.com.Tobj.Server.release methods, it is considered to be invoked outside the scope of an application's CORBA object execution.

Throws:

NilObject - Indicates that the method was invoked outside the scope of an application's CORBA object execution. The reason string contains OutOfScope.

register_factory

public static void register_factory(org.omg.CORBA.Object objp,
                                    java.lang.String id)
                             throws InvalidObject,
                                    InvalidName,
                                    RegistrarNotAvailable,
                                    CannotProceed,
                                    OverFlow

Locates the M3 FactoryFinder object and registers an M3 factory. Typically, the register_factory method is invoked from the com.beasys.Tobj.Server.initialize method when the server creates its factories.

Parameters:

objp - Specifies the object reference that was created for an application factory using the com.beasys.Tobj.TP.create_object_reference method.

id - Specifies a string identifier that is used to identify the application factory. For some suggestions as to the composition of this string, see Creating Java Server Applications.

Throws:

InvalidObject - Indicates that the factory value is null.

InvalidName - Indicates that the id string is empty. It is also raised if the field contains blank spaces or control characters.

RegistrarNotAvailable - Indicates that the FactoryFinder Registrar object cannot locate the CORBAservices Naming Service object. Notify the operations staff immediately if this exception is raised. If no naming services servers are running, restart the application.

CannotProceed - Indicates that the FactoryFinder Registrar object encountered an internal error during the registration process. The operations staff should be notified immediately if this exception is raised. A possible situation is that the Registrar object's internal tables have been corrupted. The FactoryFinder server should be restarted using the backup file.

OverFlow - Indicates that the id string is longer than 128 bytes (currently the maximum allowable length).

unregister_factory

public static void unregister_factory(org.omg.CORBA.Object objp,
                                      java.lang.String id)
                               throws InvalidObject,
                                      InvalidName,
                                      RegistrarNotAvailable,
                                      CannotProceed,
                                      OverFlow

Locates the M3 FactoryFinder object and removes an M3 factory. Typically, the unregister_factory method is invoked from the com.beasys.Tobj.Server.release method to unregister server factories.

Parameters:

objp - Specifies the object reference that was created for an application factory using the com.beasys.Tobj.TP.create_object_reference method.

id - Specifies a string identifier that is used to identify the application factory. For some suggestions as to the composition of this string, see Creating Java Server Applications.

Throws:

InvalidObject - Indicates that the factory value is null.

InvalidName - Indicates that the id string is empty. It is also raised if the field contains blank spaces or control characters.

RegistrarNotAvailable - Indicates that the FactoryFinder Registrar object cannot locate the CORBAservices Naming Service object. Notify the operations staff immediately if this exception is raised. If no naming services servers are running, restart the application.

CannotProceed - Indicates that the FactoryFinder Registrar object encountered an internal error during the registration process. The operations staff should be notified immediately if this exception is raised. A possible situation is that the Registrar object's internal tables have been corrupted. The FactoryFinder server should be restarted using the backup file.

OverFlow - Indicates that the id string is longer than 128 bytes (currently the maximum allowable length).

open_xa_rm

public static int open_xa_rm()
                      throws RMfailed

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 the com.beasys.Tobj.TransactionCurrent.open_xa_rm method. However, the open_xa_rm method provides a more convenient way for a server application to open 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.

This method should be invoked once from the com.beasys.Tobj.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 OPENINFO parameter, see the ubbconfig(5) reference page in the BEA TUXEDO Reference and the Administration Guide. Also, refer to database vendor documentation for information about how to develop and install applications that use the XA libraries.

Note: Only one resource manager can be linked to the invoking process.

Returns:

Upon successful completion, the open_xa_rm method returns 0 (zero).

Throws:

RMfailed - The tx_open() call failed.

close_xa_rm

public static void close_xa_rm()
                        throws RMfailed,
                               org.omg.CORBA.BAD_INV_ORDER

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 the com.beasys.Tobj.TransactionCurrent.close_xa_rm method. The com.beasys.Tobj.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.

This method should be invoked once from the com.beasys.Tobj.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 com.beasys.Tobj.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 termination semantics, the specific information needed to close a particular resource manager is placed in the CLOSEINFO parameter in the GROUPS section of the M3 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 the ubbconfig(5) reference page in the BEA TUXEDO Reference online document and the Administration Guide. Also, refer to database vendor documentation for information about how to develop and install applications that use the XA libraries.

Throws:

RMfailed - The tx_open() call failed.

org.omg.CORBA.BAD_INV_ORDER - There is an active transaction. The resource manager cannot be closed while a transaction is active.

deactivateEnable

public static void deactivateEnable()
                             throws IllegalOperation

Enables application-controlled deactivation of CORBA objects. This method can be used to cause deactivation of an object upon completion of the method in which it is invoked. The deactivateEnable method enables application-controlled deactivation of CORBA objects. It provides greater flexibility than can be obtained by the system-controlled behavior of the method, transaction, and process activation policies.

The following usage guidelines apply:

• The deactivateEnable method must be invoked within a method of a CORBA object. If you call this method from inside the com.beasys.Tobj.Server.initialize or com.beasys.Tobj.Server.release method, an appropriate exception is thrown.

• Only the object in which the deactivateEnable method is invoked is affected.

• The deactivateEnable method should be used only in conjunction with the process activation policy.

  Note: When it is invoked from within the method of an object that has its activation policy set to method, the effect is the same as the normal behavior of such objects (effectively, a NO-OP). When it is invoked within the method of an object that has its activation policy set to transaction, an IllegalOperation exception is raised. This is because deactivation of such objects may interfere with their correct notification of transaction completion by the M3 transaction manager.

  Throws:

  IllegalOperation - Indicates that the deactivateEnable method was invoked by an object with the activation policy set to transaction.

orb

public static org.omg.CORBA.ORB orb()

Returns an ORB object. Access to the ORB object allows the application to invoke ORB operations, such as the org.omg.CORBA.ORB.string_to_object and org.omg.CORBA.ORB.object_to_string methods. Because the ORB object is owned by the TP Framework, the invoker of the orb method should not dispose of the ORB object.

Returns:

The ORB object that is created by the TP Framework when the server application is started.

bootstrap

public static Tobj_Bootstrap bootstrap()

Returns a com.beasys.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. The TP Framework creates a com.beasys.Tobj_Bootstrap object as part of initialization; it is not necessary for the application code to create any other com.beasys.Tobj_Bootstrap objects in the server.

Caution: Because the TP Framework owns the com.beasys.Tobj_Bootstrap object, server application code must not dispose of the Bootstrap object.

Returns:

The com.beasys.Tobj_Bootstrap object that is created by the TP Framework when the server application is started.

userlog

public static int userlog(java.lang.String str)

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.

It is recommended that the 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.

Parameters:

str - The message to be written to the ULOG.

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.

Example:

The following example shows how to use the userlog method:

 userlog ("System exception caught: %s", e.get_id());