Managing ATMI Java Server

This topic contains the following sections:

•

Overview

•	Tuxedo Java Server Configuration File

•	Transaction Management

•	Setting Up the JVM Library Environment

•	Limitations

•	Java Server Configuration File Schema

Overview

The ATMI Java server TMJAVASVR, is a new Oracle Tuxedo system server acting as a bridge between the Tuxedo system and Java-implemented services. As a multithread server, Tuxedo Java server mainly performs the following tasks:

•	Reading the Tuxedo Java server configuration file

•	Advertising the services implemented with Java code according to the configuration file

•	Launching JVM

•	Forwarding requests to the Java world

•	Getting and executing the results from java-implemented services

•	Returning results to the Java world

Tuxedo Java Server Configuration File

Tuxedo Java server configuration file is an XML file that defines the parameters necessary to run the Java-implemented services in JVM.

Table 18‑1 lists available properties in a Java server configuration file. Please see the corresponding Java Server Configuration File Schema, which checks the validation of the configuration XML file for more precise information.

 

Table 18‑1 Tuxedo Java Server Configuration File Properties

Property Name	Type	Range	Description
ClassPath	String	Length:0..1024	Specifies the packages used to run the configured classes methods.
DriverClass	String	Length:1..512	Specifies the JDBC DataSource class name.
ConnectionUrl	String	Length:1..512	Specifies the JDBC connection URL string, which should be in accordance with the format required by the corresponding JDBC driver. It should not contain user name and password.
name (For TuxedoServerClass)	String	Length:1..512	Specifies the Tuxedo Java server class name. Mandatory in configuration.
name(For Service)	String	Length:1..127	Specifies the service name that will be advertised on Bulletin Board related with the method. In a configuration file, each "svcname" attribute value must be unique. If this property is not specified, the method name is used as service name.
target	String	Length:1.. 127	Specifies the class method for the corresponding service.
fieldTable16Class	String	Length:0..1024	A comma-separated list of fully qualified FML classes. Any of FML16 field table classes should be defined here or else the Fldid()/ Fname() of the FML will not work.
fieldTable32class	String	Length:0..1024	A comma-separated list of fully qualified FML classes. All the FML32 field table classes should be defined here or else the Fldid()/ Fname() of the FML32 will not work.
viewFile16Class	String	Length:0..1024	A comma-separated list of fully qualified FML classes. All the view classes that are used by programming must be defined here.
viewFile32Class	String	Length:0..1024	A comma-separated list of fully qualified FML classes. All the view32 classes that are used by programming must be defined here.

Setting the Class Path Element

Following <ClassPath> element settings are supported in Tuxedo Java configuration file:

<ClassPath>customer_lib_path/*.jar</ClassPath> or <ClassPath>customer_lib_path/*.zip</ClassPath>

Adds all the .jar or .zip archives under customer_lib_path to JVM classpath.

<ClassPath>customer_lib_path</ClassPath>

Adds all the classes under customer_lib_path to JVM classpath.

<ClassPath>customer_lib_path/*</ClassPath>

Adds all the .jar files, .zip files, and classes under customer_lib_path to JVM classpath.

<ClassPath>customer_lib_path/lib1.jar</ClassPath> or <ClassPath>customer_lib_path/lib2.zip</ClassPath>

Adds customer_lib_path/lib1.jar or customer_lib_path/lib2.zip to JVM classpath.

Notes:

•	All the file searches in customer_lib_path are non-recursive.

•	The customer_lib_path to $APPDIR can be either absolute path or relative path.

•	The $APPDIR is added into classpath by default.

Setting the FML/View Field Table Class

To use the View/View32, you need to specify the View class in <Resources></Resources> element. To use the Fldid()/Fname() properly, you need to specify the FML/FML32 field table class in <Resources></Resources> element.

Configuration Rules

You need to follow the following rules when creating Java server configuration file:

•	Only <TuxedoServerClasses> is mandatory in Java server configuration file, and at least one TuxedoServerClass should be configured.

•	Currently, only one <DataSource> element is allowed to be configured in <DataSources> in configuration file. The name property for <DataSource> does not take effect for the present.

•	Only <ClassPath>, <fieldTable16Class>, <fieldTable32class>, <viewFile16Class>, <viewFile32Class>, and <Service> element can have multiple entities.

•	In <Resources> section, you should configure <fieldTable16Class> first and then <fieldTable32class>, <viewFile16Class>, and <viewFile32Class> in sequence.

Note:

The configuration file (e.g. TJSconfig.xml) will be checked against the Schema file TJSconfig.xsd which is located in $TUXDIR/udataobj/tuxj/TJSconfig.xsd (Unix) or $TUXDIR\udataobj\tuxj/TJSconfig.xsd (Windows). Oracle recommends you refer to TJSconfig.xsd for more information about configuration rules.

Advertising Services

Each Tuxedo Java server class that implements services must implement a set of methods, of which input argument parameter is the TPSVCINFO interface. The methods that are advertised as services must be the public method and have the return type set to void.

Tuxedo Java server advertises all of public methods as services into bulletin board. If Services is specified in configuration file, Tuxedo Java server uses the value of name property as the service name, otherwise, the method name is used as the service name.

Configuration File Example

Listing 18‑1 shows a Tuxedo Java server configuration file example.

Suppose the MyTuxedoServerClass1 Java class defines JAVASTRINGSVC, JAVAFML32SVC, and svc3 methods, and the MyTuxedoServerClass2 Java class defines svc4 method, this example initiates the connection to Oracle database with JDBC connection and exports the services: svc1, svc2, svc3, and svc4.

Note that the method name svc3 and svc4 are exported as the service name because there is no <Service> property specified for them in the configuration file.

Listing 18‑1 Tuxedo Java Server Configuration Example

<?xml version="1.0" encoding="UTF-8"?>

<TJSconfig>

<ClassPaths>

<ClassPath>/home/oracle/app/javaserver/MyTuxedoServerClass.jar</ClassPath>

<ClassPath>/home/oracle/app/oracle/product/11.2.0/dbhome_2/ucp/lib/ucp.jar</ClassPath>

<ClassPath>/home/oracle/app/oracle/product/11.2.0/dbhome_2/jdbc/lib/ojdbc6.jar</ClassPath>

</ClassPaths>

<Resources>

<FieldTable16Classes>test1.FML16TBL, test2.FML16TBL</FieldTable16Classes>

<FieldTable16Classes>test3.FML16TBL, test4.FML16TBL</FieldTable16Classes>

<FieldTable32Classes>test1.FML32TBL1, test2.FML32TBL</FieldTable32Classes>

<FieldTable32Classes>test3.FML32TBL1, test4.FML32TBL</FieldTable32Classes>

<ViewFile16Classes>test1.VIEW16, test2.VIEW16</ViewFile16Classes>

<ViewFile16Classes>test3.VIEW16, test4.VIEW16</ViewFile16Classes>

<ViewFile32Classes>test1.VIEW32, test2.VIEW32</ViewFile32Classes>

<ViewFile32Classes>test3.VIEW32, test4.VIEW32</ViewFile32Classes>

</Resources>

<DataSources>

<DataSource name="oracle">

<DriverClass>oracle.jdbc.xa.client.OracleXADataSource</DriverClass>

<JdbcDriverParams>

<ConnectionUrl>jdbc:oracle:thin:@//10.182.54.144:1521/javaorcl</ConnectionUrl>

</JdbcDriverParams>

</DataSource>

</DataSources>

<TuxedoServerClasses>

<TuxedoServerClass name="MyTuxedoServerClass1">

<Services>

<Service name="svc1" target="JAVASTRINGSVC"></Service>

<Service name="svc2" target="JAVAFML32SVC"></Service>

</Services>

</TuxedoServerClass>

<TuxedoServerClass name="MyTuxedoServerClass2"></TuxedoServerClass>

</TuxedoServerClasses>

</TJSconfig>

 

Notes:

•	Because a service name is used to map to specified class + method in the configuration file, it must be unique in one Tuxedo Java server and among the different Java classes in it.

•	You need to provide all the libraries (except standard JRE library) used by your Java applications, such as user-defined classes and DataSource driver library.

Transaction Management

The Tuxedo Java-based transaction is implemented based on the existing Tuxedo transaction management framework. As before, the configuration you need to make in the UBB configuration file for transaction is, define the attributes of transaction manager servers (TMSs) and resource managers (RMs) for a particular group. The Tuxedo Java Server (TMJAVASVR) should belong to this group.

Listing 18‑2 UBB Configurations for Java-Based Transaction

*GROUP

ORASVRGRP LMID=simple GRPNO=1

OPENINFO="Oracle_XA:Oracle_XA+Acc=P/system/oracle+SesTm=120+MaxCur=5+LogDir=.+SqlNet=orcl"

TMSNAME=TMSORA TMSCOUNT=2

*SERVERS

TMJAVASVR SRVGRP=ORASVRGRP SRVID=3 CLOPT="-- -c TJSconfig_ORA.xml"

MINDISPATCHTHREADS=2 MAXDISPATCHTHREADS=2

 

For more information about how to configure the transaction in UBB config file, see Configuring Your ATMI Application to Use Transactions.

Since the Java-implemented services need to connect the data source in Java world, it is necessary to provide parameters that define how to connect the data source in Tuxedo Java server configuration file.

In this release, the Java-implemented services can only connect the database with JDBC connection, so you need to specify JDBC parameters in Tuxedo Java server configuration file using ConnectionUrl property.

Because the Java server retrieves user name and password from OPENINFO, you should provide the user name and password in OPENINFO in UBB configuration file. This way encrypts the password and ensures the high security.

Different DataSource have different ConnectionURL format.

For Oracle database, the format is:

jdbc:oracle:thin:@//hostname:portnumber/servicename

For DB2 database, the format is:

jdbc:db2://hostname:portnumber/DatabaseName

Listing 18‑3 is a configuration example of Oracle database.

Listing 18‑3 Oracle Database Configuration Example

<DataSources>

<DataSource name="oracle">

<DriverClass>oracle.jdbc.xa.client.OracleXADataSource</DriverClass>

<JdbcDriverParams>

<ConnectionUrl>jdbc:oracle:thin:@//10.182.54.144:1521/javaorcl</ConnectionUrl>

</JdbcDriverParams>

</DataSource>

</DataSources>

 

AUTOTRAN

The AUTOTRAN can also be configured on the services advertised by Tuxedo Java server. When the Tuxedo Java server service is configured in *SERVICES section and its AUTOTRAN attribute is specified as Y, the service starts a transaction automatically.

Setting Up the JVM Library Environment

The TMJAVASVR server depends on the libjvm.so (Unix)/jvm.dll (Windows) which is in the JRE package.

Before running TMJAVASVR, you must make sure the libjvm.so (Unix) or jvm.dll (Windows) is located in the library loading path of your platform.

On Unix, set LD_LIBRARY_PATH or SHLIB_PATH (HP-UX only) or LIBPATH (AIX only) accordingly.

Do one of the following according to the platform you are using:

•	On Oracle Enterprise Linux (64 bit) and Java SE, make sure $JRE_HOME/lib/amd64/server is included in $LD_LIBRARY_PATH.

•	On Oracle Enterprise Linux (64 bit) and Oracle JRockit JVM, make sure $JRE_HOME/lib/amd64/jrockit and $JRE_HOME/lib/amd64 are included in $LD_LIBRARY_PATH.

•	On AIX PPC64, we suggest that you include both $JRE_HOME/lib/ppc64/classic and $JRE_HOME/lib/ppc64 in $LIBPATH.

•	On Solaris sparc 64-bit, make sure $JRE_HOME/lib/sparcv9/server is included in $LD_LIBRARY_PATH

•	On Solaris x64, make sure $JRE_HOME/lib/amd64/server is included in $LD_LIBRARY_PATH

•	On Windows, make sure the PATH environment variable includes %JRE_HOME%\bin\server.

Note:

The $JRE_HOME points to the JRE home directory. You can also refer to $TUXDIR/tux.env for the setting.

Limitations

•	In Oracle Tuxedo 12c Release 1 (12.1.1), the user cannot launch a new Java thread in the service of Java server.

•	The Java Server is a multithreaded process that dispatches the services in multiple threads. It cannot run in the single thread mode.

•	Oracle Tuxedo 12c Release 1 (12.1.1) only supports the connection to database through JDBC driver. For DB2, only the Type 4 JDBC driver is supported.

•	Conversation is not supported by Oracle Tuxedo Java server.

•	MSSQ is not supported by Oracle Tuxedo Java server.

Java Server Configuration File Schema

Listing 18‑4 shows the XML schema of the Java server configuration file:

Listing 18‑4 Java Server Configuration Schema File

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">

<xs:element name="TJSconfig">

<xs:complexType>

<xs:all>

<xs:element minOccurs="0" maxOccurs="1" ref="ClassPaths"/>

<xs:element minOccurs="0" maxOccurs="1" ref="DataSources"/>

<xs:element minOccurs="0" maxOccurs="1" ref="Resources"/>

<xs:element minOccurs="1" maxOccurs="1" ref="TuxedoServerClasses"/>

</xs:all>

</xs:complexType>

</xs:element>

<xs:element name="ClassPaths">

<xs:complexType>

<xs:sequence>

<xs:element minOccurs="0" maxOccurs="unbounded" ref="ClassPath"/>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element name="ClassPath" type="xs:string"/>

<xs:element name="DataSources">

<xs:complexType>

<xs:sequence>

<xs:element minOccurs="0" maxOccurs="1" ref="DataSource"/>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element name="DataSource">

<xs:complexType>

<xs:all>

<xs:element minOccurs="1" maxOccurs="1" ref="DriverClass"/>

<xs:element minOccurs="1" maxOccurs="1" ref="JdbcDriverParams"/>

</xs:all>

<xs:attribute name="name" use="required" type="xs:string"/>

</xs:complexType>

</xs:element>

<xs:element name="DriverClass" type="xs:string"/>

<xs:element name="JdbcDriverParams">

<xs:complexType>

<xs:sequence>

<xs:element minOccurs="1" maxOccurs="1" ref="ConnectionUrl"/>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element name="ConnectionUrl" type="xs:string"/>

<xs:element name="Resources">

<xs:complexType>

<xs:sequence>

<xs:element minOccurs="0" maxOccurs="unbounded" ref="FieldTable16Classes"/>

<xs:element minOccurs="0" maxOccurs="unbounded" ref="FieldTable32Classes"/>

<xs:element minOccurs="0" maxOccurs="unbounded" ref="ViewFile16Classes"/>

<xs:element minOccurs="0" maxOccurs="unbounded" ref="ViewFile32Classes"/>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element name="FieldTable16Classes" type="xs:string"/>

<xs:element name="FieldTable32Classes" type="xs:string"/>

<xs:element name="ViewFile16Classes" type="xs:string"/>

<xs:element name="ViewFile32Classes" type="xs:string"/>

<xs:element name="TuxedoServerClasses">

<xs:complexType>

<xs:sequence>

<xs:element minOccurs="1" maxOccurs="unbounded" ref="TuxedoServerClass"/>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element name="TuxedoServerClass">

<xs:complexType>

<xs:sequence>

<xs:element minOccurs="0" maxOccurs="unbounded" ref="Services"/>

</xs:sequence>

<xs:attribute name="name" use="required" type="xs:string"/>

</xs:complexType>

</xs:element>

<xs:element name="Services">

<xs:complexType>

<xs:sequence>

<xs:element minOccurs="0" maxOccurs="unbounded" ref="Service"/>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element name="Service">

<xs:complexType mixed="true">

<xs:attribute name="name" use="required" type="xs:string"/>

<xs:attribute name="target" use="required" type="xs:string"/>

</xs:complexType>

</xs:element>

</xs:schema>