ATMI Java Server User Interfaces

This topic includes the following sections:

•	TuxedoJavaServer

•	Oracle Tuxedo Java Context

•	TJATMI Primitives for Tuxedo Java Applications

•	TypedBuffers for Tuxedo Java Applications

•	Get/Set Service Information

•

Exception

•

Trace

•	Newly Added Java APIs from Tuxedo 12c Release 2 (12.1.3)

TuxedoJavaServer

TuxedoJavaServer is an abstract class, which should be inherited by all the user-defined classes that implement the services.

 

Table 2‑1 TuxedoJavaServer Interfaces

Function	Description
tpsvrinit	An abstract method, which should be implemented by child class to do some initialization works
tpsvrdone	An abstract method, which should be implemented by child class to do some cleanup works
getTuxAppContext	Use to retrieve the current attached Tuxedo application Java context.

Oracle Tuxedo Java Context

To access the TJATMI primitives provided by Oracle Tuxedo Java server, you need to get a TuxAppContext object that implements all the TJATMI primitives.

Because the service class inherits from TuxedoJavaServer, you can call getTuxAppContext() in the service to get the context object. However, you cannot get TuxAppContext in tpsvrinit() because the TuxAppContext is not ready at this time. If you try to get the TuxAppContext object in tpsvrinit(), tpsvrinit() will fail and throw an exception.

TJATMI Primitives for Tuxedo Java Applications

TJATMI is a set of primitives that provides communication between clients and servers, such as calling the services, starting and ending transactions, getting the connection to DataSource, logging, and etc.

For more information, please refer to Java Server Javadoc.

 

Table 2‑2 TJATMI Primitives

Name	Operation
tpcall	Use for synchronous invocation of an Oracle Tuxedo service during request/response communication.
tpreturn	Use to set the return value and data in Tuxedo Java Server.
tpbegin	Use to begin a transaction.
tpcommit	Use to commit the current transaction
tpabort	Use to abort the current transaction
tpgetlev	Use to check if a transaction is in progress
getConnection	Use to get a connection to the configured DataSource
userlog	Use to print the user log in Tuxedo user log file

Note:

The service continues running after tpreturn ends execution. It is recommended put tpreturn() as the last executive statement in the service.

TypedBuffers for Tuxedo Java Applications

ATMI Java server reuses the Oracle WebLogic Tuxedo Connector TypedBuffers that corresponds to Oracle Tuxedo typed buffers. Messages are passed to servers in typed buffers. The ATMI Java server provides the following buffer types in Table 2‑3:

 

Table 2‑3 TypedBuffers

Buffer Type	Description
TypedString	Buffer type used when the data is an array of characters that terminates with the null character. Oracle Tuxedo equivalent: STRING.
TypedCArray	Buffer type used when the data is an undefined array of characters (byte array), any of which can be null. Oracle Tuxedo equivalent: CARRAY.
TypedFML	Buffer type used when the data is self-defined. Each data field carries its own identifier, an occurrence number, and possibly a length indicator. Oracle Tuxedo equivalent: FML.
TypedFML32	Buffer type similar to TypeFML but allows for larger character fields, more fields, and larger overall buffers. Oracle Tuxedo equivalent: FML32.
TypedXML	Buffer type used when data is an XML based message. Oracle Tuxedo equivalent: XML for Tuxedo Release 7.1 and higher.
TypedView	Buffer type used when the application uses a Java structure to define the buffer structure using a view description file. Oracle Tuxedo equivalent: VIEW
TypedView32	Buffer type similar to View but allows for larger character fields, more fields, and larger overall buffers. Oracle Tuxedo equivalent: VIEW32.

For more information about TypedBuffers, please see the Package of "weblogic.wtc.jatmi".

Additionally, "Using FML with Oracle Tuxedo Java Server" and "Using VIEW with Oracle Tuxedo Java Server" in Reference are useful for you to use TypedFML/TypedFML32 and/or TypedView/TypedView32 in Java server class.

Limitations for Typedbuffer Support

•	Fldid()/Fname() for the TypedFML32 which is embedded in another TypedFML32 cannot work. To work around this issue, you can use the fieldtable class instead for name/id transferring.

•	The weblogic.wtc.gwt.XmlViewCnv/XmlFmlCnv class is not available for the present.

Get/Set Service Information

Use the TPSVCINFO class to get/set service information sent by the Oracle Tuxedo client.

 

Table 2‑4 Getter Functions

Function	Description
getServiceData	Use to return the service data sent from the Oracle Tuxedo Client.
getServiceFlags	Use to return the service flags sent from the Oracle Tuxedo Client.
getServiceName	Use to return the service name that was called.
getAppKey	Use to get the application authentication client key.
getClientID	Use to get the client identifier for originating client.

Use TuxATMIReply to get the reply data and meta-data from a service invocation.

 

Table 2‑5 Getter Functions for Reply

Function	Description
getReplyBuffer	Return the (possibly null) typed buffer returned from a service
gettpurcode	Return the tpurcode returned from a service

Exception

You need to catch the exception thrown by JATMI primitives in the service, such as tpcall(). There are two types of exceptions that JATMI can throw:

•	TuxATMITPException: Exception thrown that represents a TJATMI failure.

•	TuxATMITPReplyException: Exception thrown if there was a service failure (TPESVCFAIL or TPSVCERROR) and user data may be associated with the exception.

For more information, please refer to Java Server Javadoc.

Trace

You also need to export TMTRACE=atmi:ulog as you have done for traditional Tuxedo ATMI. The TJATMI API traces are written into ULOG as other ATMI traces.

Newly Added Java APIs from Tuxedo 12c Release 2 (12.1.3)

•	Newly Added Java APIs

•	Examples for Programming with Newly Java APIs

Newly Added Java APIs

From Tuxedo 12c Release 2 (12.1.3), Tuxedo Java server adds a bunch of Java APIs in terms of event, unsolicited message, /Q, asynchronous call, block time control, and server service forward. For detailed information about all newly added Java APIs, please refer to Javadoc.

Note:

Except for tpappthrinit() and tpappthrterm(), all APIs must be invoked only after the TuxAppContext object is successfully created and acquired by the caller.

Examples for Programming with Newly Java APIs

Most Tuxedo Java APIs must be invoked in a valid Tuxedo context. Before invoking these APIs, a valid Tuxedo context must be acquired.

The following examples present the ways to program with Java APIs.

•	Example for Invoking APIs in Server Initialization and Termination Stage

•	Example for Invoking APIs in Service Routine

•	Example for Forwarding Service Requests

•	Example for Invoking APIs in an Application Server Thread

Listing 2‑1 Example for Invoking APIs in Server Initialization and Termination Stage

public int tpsvrinit()

{

TuxAppContext myAppCtxt = null;

try {

int cd;

TypedString rqstData = new TypedString("hello”);

TuxATMIReply rply = null;

myAppCtxt = getTuxAppContext();

cd = myAppCtxt.tpacall("data_process", rqstData, 0);

rply = myAppCtxt.tpgetrply(cd, 0);

...

} catch (TuxATMITPException ex) {

} catch (Throwable ex) {

}

return 0;

}

public void tpsvrdone()

{

TuxAppContext myAppCtxt = null;

try {

TypedString rqstData = new TypedString("hello”);

TuxATMIReply rply = null;

myAppCtxt = getTuxAppContext();

rply = myAppCtxt.tpcall("data_process", rqstData, 0);

...

} catch (TuxATMITPException ex) {

} catch (Throwable ex) {

}

return;

}

 

Listing 2‑2 Example for Invoking APIs in Service Routine

public void MYSERVICE(TPSVCINFO rqst)

{

TuxAppContext myAppCtxt = null;

try {

TypedFML32 rqstData = (TypedFML32)rqst.getServiceData();

TuxATMIReply rply = null;

TypedFML32 rplyData = null;

myAppCtxt = getTuxAppContext();

rply = myAppCtxt.tpcall("data_process", rqstData, 0);

rplyData = (TypedFML32)rply.getReplyBuffer();

myAppCtxt.tpreturn(TPSUCCESS, 0, rplyData, 0);

} catch (TuxATMITPException ex) {

} catch (Throwable ex) {

}

return;

}

 

Listing 2‑3 Example for Forwarding Service Requests

public void MYSERVICE(TPSVCINFO rqst)

{

TuxAppContext myAppCtxt = null;

try {

TypedFML32 rqstData = (TypedFML32)rqst.getServiceData();

TuxATMIReply rply = null;

TypedFML32 rplyData = null;

myAppCtxt = getTuxAppContext();

rply = myAppCtxt.tpcall("data_process", rqstData, 0);

rplyData = (TypedFML32)rply.getReplyBuffer();

myAppCtxt.tpforward("FWD_SVC", rplyData, 0);

} catch (TuxATMITPException ex) {

} catch (Throwable ex) {

}

return;

}

 

Listing 2‑4 Example for Invoking APIs in an Application Server Thread

public class SimpServTuxAppThread implements Runnable, TuxATMIConstants {

public void run() {

try {

TPINIT tpinfo = null;

int rtn = 0;

rtn = TuxAppContextUtil.tpappthrinit(tpinfo);

TuxAppContext myAppCtxt = null;

myAppCtxt = TuxAppContextUtil.getTuxAppContext();

TuxATMIReply rply = null;

TypedString rqStr = new TypedString("Is_is_simple_appThread_test");

rply = myAppCtxt.tpcall("SVC", rqStr, TPNOTIME|TPSIGRSTRT);

rtn = TuxAppContextUtil.tpappthrterm();

} catch (TuxATMITPException ex) {

} catch (Throwable ex) {

}

}

}

 

In the above example, a valid Tuxedo application context can be created by invoking TuxAppContextUtil.tpappthrinit() in an application created Java server thread. After the invocation of TuxAppContextUtil.tpappthrinit() is successfully completed, you can get a valid Tuxedo application context by invoking TuxAppContextUtil.getTuxAppContext() method and then Tuxedo Java APIs can be called in the context.