com.beasys.Tobj
Class TP

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

public class TP

extends java.lang.Object

implements com.beasys.weblogic.Constants

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_active_object_reference(java.lang.String interfaceName, java.lang.String stroid, Tobj_Servant servant) Creates an object reference and pre-activates an object.
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 java.lang.String	get_object_id(org.omg.CORBA.Object objp) Allows a server to retrieve the string object id contained in an object reference that was created by the TP Framework.
static org.omg.CORBA.Object	get_object_reference() Returns a reference 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 WLE FactoryFinder object and registers an WLE factory.
static void	unregister_factory(org.omg.CORBA.Object objp, java.lang.String id) Locates the WLE FactoryFinder object and removes an WLE 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 WLE software cannot guarantee any uniqueness in object references, since object references may be legitimately copied and shared outside the WLE 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 interfaceName is null.

InvalidObjectId - Indicates that the specified stroid is null.

create_active_object_reference

public static org.omg.CORBA.Object create_active_object_reference(java.lang.String interfaceName,
                                                                  java.lang.String stroid,
                                                                  Tobj_Servant servant)
                                                           throws IllegalOperation,
                                                                  InvalidInterface,
                                                                  InvalidObjectId,
                                                                  InvalidServant,
                                                                  ObjectAlreadyActive,
                                                                  ServantAlreadyActive

Creates an object reference and pre-activates an object. The resulting object reference may be passed to clients who will use it to access the object.

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

• In 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.

This method allows an application to activate an object explicitly before its first invocation. (For reasons you might do this, see the section "Explicit Activation" in the Java TP Framework Reference.) The user first creates a servant and sets its state before calling create_active_object_reference. The TP Framework then puts the object into the Active Object Map (that is, associates 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 call to the servant’s activate_object method (just as if this were the second or later invocation on the object).

The object so activated must be for an interface that was declared with the process activation policy; otherwise an exception is raised.

If the object is deactivated, the use of an object reference held by a client might cause the object to be activated again in some other process. For a discussion of situations in which this might be a problem and what to do about it, see the section "Explicit Activation" in the Java TP Framework Reference.

Caution: When you preactivate objects in an interface, it can lead to the following problem.

Problem Statement:

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.

2. SERVER2 also implements objects of interface A. However, instead of preactivating the objects, SERVER2 lets the TP Framework activate them on demand.

3. If the administrator configures SERVER1 and SERVER2 in the same group, then a client can get an interface A object reference from SERVER2 and invoke on it. Then, due to load balancing, SERVER1 could be asked to activate an object on interface A. However, SERVER1 is not able to activate an object on interface A on demand because its activate_object method throws the ActivateObjectFailed exception.

Workaround: 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.

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 WLE software cannot guarantee any uniqueness in object references, since object references may be legitimately copied and shared outside the WLE domain (for example, by passing the object reference as a string).

servant - A pointer to a servant that the application has already created and initialized.

Returns:

The newly created object reference.

Throws:

InvalidInterface - Indicates that the specified interfaceName is null.

InvalidObjectId - Indicates that the specified stroid is null.

InvalidSearvant - Indicates that the specified servant is null.

ServantAlreadyActive - The object could not be activated explicitly because the servant is already being used with another Object Id. A servant can be used only with a single ObjectId. To pre-activate objects containing different ObjectIds, the application must create multiple servants and pre-activate them separately, one per ObjectId.

ObjectAlreadyActive - 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.

IllegalOperation - The object could not be activated explicitly because it does not have the process activation policy, or the specified interface is not known in the server.

get_object_reference

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

Returns a reference to the current object.

Returns:

A reference to 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.

get_object_id

public static java.lang.String get_object_id(org.omg.CORBA.Object objp)
                                      throws InvalidObject

Allows a server to retrieve the string object id contained in an object reference that was created by the TP Framework. If the object reference was not created by the framework (for example, it was created by a client ORB), an exception is raised.

Returns:

The string object id that was passed to TP.create_object_reference or TP.create_active_object_reference when the object reference was created.

Throws:

InvalidObject - Indicates that the object is nil or was not created by the TP Framework.

register_factory

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

Locates the WLE FactoryFinder object and registers an WLE 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 WLE FactoryFinder object and removes an WLE 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 underlying 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 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 underlying tx_close() 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 deactivation behavior of CORBA objects with the process activation policy.

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 WLE 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());