Using XMLink

Chapter 3. Configuring XMLink

This chapter primarily focuses on how to configure XMLink to run in IBM WebSphere, but since XMLink can be used with any J2C 1.5-compliant application server, the environment section can be referenced by all XMLink configurations. If there is additional information on configuring XMLink on other application servers, you can find it in the Release Notes section at http://docs.prolifics.com/docs/tconn/.

Configuration Notes

Before configuring your installation of XMLink, check to see if any of the following information applies to your system.

Libraries for Oracle Tuxedo interaction
There are native and workstation versions in both UNIX and Windows:

Tuxedo Variables
If a Tuxedo variable is set in the environment, it affects all connections and connection factories if not overridden by a corresponding connection factory property.

Managed and Non-Managed Environments

With J2C-compliant resource adapters like XMLink, you have the option of running them in a managed environment or non-managed environment.

A managed environment would be in a J2EE-compliant application server, such as WebSphere, which supports component-based applications and associated technologies (like EJB, servlets, and JSPs). The application server also provides other services that can be used in conjunction with the resource adapter, such as security, transaction support, and connection pooling. Figure 3-1(which is also found in Chapter 1) illustrates the use of XMLink in a managed environment.

Figure 3-1 Running XMLink in a Managed Environment

A non-managed environment is like a two-tier application where the application client uses the resource adapter to directly access the EIS, as illustrated in Figure 3-2.

Figure 3-2 Running XMLink in a Non-managed Environment

Managed Environment Settings

For WebSphere application server, there are options for installing your resource adapter archives so that your resource adapters are readily available to your applications. However, problems can occur if local environment settings override the WebSphere application server defaults.

In a managed environment, it is recommended that you use the application servers's settings for any installed resource adapters, such as XMLink. This means that the XMLink class files and libraries will not need to be added to CLASSPATH or PATH (for UNIX and AIX, LD_LIBRARY_PATH or LIBPATH)

Installing Resource Adapter Archives

To install resource adapter archives in a WebSphere managed environment, refer to your WebSphere documentation.

Deploying in a Non-Managed Environment

XMLink contains a utility, TConnTool, to facilitate deployment in non-managed environments. It supports a set of methods that can be used to build a customized deployment tool. It also includes a main() that supports a rudimentary command line interface.

The following describes the command line usage of TConnTool: 

java com.prolifics.tconn.TConnTool [-deploy] [-remove] [-info] JndiName
java com.prolifics.tconn.TConnTool [-list]

-deploy
Deploys a Connection Factory with the JNDI name, JndiName, using the properties provided in the file, JndiName.properties.

-remove
Removes a Connection Factory previously deployed by this tool, whose JNDI name is JndiName.

-info
Displays the property settings for a Connection Factory previously deployed by this tool, whose JNDI name is JndiName.

-list
Lists the JNDI names of Connection Factories previously deployed by this tool.

For the -deploy option, it is expected that the properties file is located in the current directory. This file should contain entries of the form name=value, such as WSNADDR=//mymachine:12345. If the first character on a line is '#', it is a comment. It is expected that components of any path given in JndiName for -deploy are pre-existent. If a path is not given, the root of the context tree is used. For WebSphere 4.0, the eis subcontext is recommended.

Note that when the -list option is used, TConnTool may take several seconds to complete the search. TConnTool performs an exhaustive search of the JNDI name space on the local machine.

The following are public methods provided by TConnTool, which offer the same functionality as the command line interface: 

public void deploy(Context ctx, HashMap p, String JNDIname)
public void remove(Context ctx, String JNDIname) throws NamingException
 
public HashMap info(Context ctx, String JNDIname) throws NamingException, Exception
 
public String[] list(Context ctx, String ctxname)

For deploy(), the second parameter should contain valid connection factory properties and their settings. Similarly, info() returns a HashMap which contains connection factory properties and their settings.

For list(), the second parameter is the path for the Context at which to begin the search for deployed connection factories. To begin at the root, pass in an empty string. list() returns a String array containing the names of any deployed connection factories that are found.

Configuring the Environment

The following environment variables need to be set in order to use XMLink. In WebSphere, you have the option of specifying some of the environment variables either as a property setting or in the environment.

Note: The configuration settings may differ if you are using Java on the command line with XMLink vs. deploying XMLink in an application server.

Table 3-1 Environment Variables for XMLink with IBM WebSphere 6
Variable Description How to Configure

CLASSPATH

Specify the location of the following Java files:

environment

XMLink classes

needs to be set for applications using XMLink

From the J2EE distribution. Needed for compiling user code. Contains necessary classes for JNDI lookup and J2C reference implementation.

For Connection Factory lookup.

This jar is required by WebSphere and contains the following:

For the XML interface in XMLink, you need a XML parser, such as Xerces. You can set this as a -d option when using command-line Java.

WebSphere installs xerces.jar in the WAS_HOME/lib directory

JAVA_HOME

Specify the location of your Java JDK or JRE installation.

environment

LD_LIBRARY_PATH
or
LIBPATH

On UNIX, specify the location of the following shared libraries for non-managed environments:

environment

PATH

On Windows, specify the location of the following DLLs for non-managed environments:

environment

Set the following Tuxedo variables:

Table 3-2 Tuxedo Variables
Variable Description How to Configure

TUXCONFIG

Specify the full path name of the binary TUXCONFIG file for native clients.

TUXDIR

Specify the location of the Oracle Tuxedo installation.

WSNADDR

If your Oracle Tuxedo client is a workstation client (not native), specify the list of one or more network addresses of the workstation listeners the client wants to contact, matching the addresses specified in the application configuration file. The setting contains the host machine and port number, for example:

//myhost:3445

Setting XMLink Properties

In WebSphere, you set properties in the Administrative Console. Some of these properties correspond to settings in an Oracle Tuxedo configuration.

Setting JVM Properties

XMLink.tconn
For XMLink 3.0, this JVM property has been supplanted by the ConnectionType property on the resource adapter. However, this property can still be specified either on the JVM or on the command line; however, there is no longer a default setting.

Specify the version of the XMLink Tuxedo libraries. There are native and workstation versions for Tuxedo 6.5 and Tuxedo 7.1+ in both UNIX and Windows. Set the property to one of the following values:

Setting Properties on a Resource Adapter

Among the properties in this section, FIELDTBLS, FIELDTBLS32, FLDTBLDIR, FLDTBLDIR32 and ConnectionType may only be set here, since the values for these properties must remain the same for all XMLink Connection Factories of the current JVM process. The other Resource Adapter properties may act as defaults for multiple connection factories, and may be overridden for individual connection factories.

ClientName
Authentication information. See Tuxedo docs for tpinit(). Overridden by ClientName connection factory property.

ConnectionRetries
The number of additional times XMLink will try to establish a connection to the Tuxedo server after a failed initial attempt. Also, the number of times XMLink will try to reestablish a lost connection to the Tuxedo server during an attempted service call. Overridden by ConnectionRetries connection factory property. Default is 0.

ConnectionRetryInterval
The delay in milliseconds between attempts to establish or reestablish a connection to the Tuxedo server. Overridden by ConnectionRetryInterval connection factory property. Default is 0, or as brief a delay as possible.

ConnectionType
Either native or workstation are allowed values. Selects which of two DLLs or shared libraries to use when the resource adapter is started, where one is provided for a Tuxedo native connection and another is provided for a Tuxedo workstation connection. Overridden by the setting for the XMLink.tconn System property for the JVM, which may be assigned to a specific shared library or DLL by name.

Data
Authentication information. See Tuxedo docs for tpinit(). Overridden by
Data connection factory property.

FIELDTBLS
Overrides FIELDTBLS Tuxedo environment variable. Must be unchanged for all XMLink resource adapters running in the same JVM.

FIELDTBLS32
Overrides FIELDTBLS32 Tuxedo environment variable. Must be unchanged for all XMLink resource adapters running in the same JVM.

FLDTBLDIR
Overrides FLDTBLDIR Tuxedo environment variable. Must be unchanged for all XMLink resource adapters running in the same JVM.

FLDTBLDIR32
Overrides FLDTBLDIR32 Tuxedo environment variable. Must be unchanged for all XMLink resource adapters running in the same JVM.

GroupName
Authentication information. See Tuxedo docs for tpinit(). Overridden by GroupName connection factory property.

InteractionRetries
The number of additional times XMLink will try a Tuxedo service call during Interaction.execute(), following an attempt that fails due to a connection error or Tuxedo server system error. Overridden by InteractionRetries connection factory property. Default is 0.

InteractionRetryInterval
The delay in milliseconds between Tuxedo service call attempts during Interaction.execute(). Overridden by InteractionRetryInterval connection factory property. Default is 0, or as brief a delay as possible.

Password
Authentication information. See Tuxedo docs for tpinit(). Overridden by Password connection factory property.

TUXCONFIG
Overrides TUXCONFIG Tuxedo environment variable. Overridden by TUXCONFIG connection factory property.

ULOGPFX
Overrides ULOGPFX Tuxedo environment variable. Overridden by ULOGPFX connection factory property, when logging takes place after a connection is established.

UserName
Authentication information. See Tuxedo docs for tpinit(). Overridden
by UserName connection factory property.

WSENVFILE
Overrides WSENVFILE Tuxedo environment variable. Overridden by WSENVFILE connection factory property.

WSNADDR
Overrides WSNADDR Tuxedo environment variable. Overridden by WSNADDR connection factory property.

Setting Properties on a Connection Factory

The following list of properties can be configured as needed for each connection factory that is created.

ClientName
Authentication information. See Tuxedo docs for tpinit(). Overrides ClientName property of resource adapter.

ConnectionRetries
The number of additional times XMLink will try to establish a connection to the Tuxedo server after a failed initial attempt. Also, the number of times XMLink will try to reestablish a lost connection to the Tuxedo server during an attempted service call. Overrides ConnectionRetries property of resource adapter. Default is 0.

ConnectionRetryInterval
The delay in milliseconds between attempts to establish or reestablish a connection to the Tuxedo server. Overrides ConnectionRetryInterval property of resource adapter. Default is 0, or as brief a delay as possible.

Data
Authentication information. See Tuxedo docs for tpinit(). Overrides Data property of resource adapter.

GroupName
Authentication information. See Tuxedo docs for tpinit(). Overrides GroupName property of resource adapter.

InteractionRetries
The number of additional times XMLink will try a Tuxedo service call during Interaction.execute(), following an attempt that fails due to a connection error or Tuxedo server system error. Overrides InteractionRetries property of resource adapter. Default is 0.

InteractionRetryInterval
The delay in milliseconds between Tuxedo service call attempts during Interaction.execute(). Overrides InteractionRetryInterval property of resource adapter. Default is 0, or as brief a delay as possible.

Password
Authentication information. See Tuxedo docs for tpinit(). Overrides Password property of resource adapter.

TUXCONFIG
Overrides TUXCONFIG Tuxedo environment variable and TUXCONFIG property of resource adapter.

ULOGPFX
Overrides ULOGPFX Tuxedo environment variable and ULOGPFX property of resource adapter, when logging takes place after a connection is established.

UserName
Authentication information. See Tuxedo docs for tpinit(). Overrides UserName property of resource adapter.

WSENVFILE
Overrides WSENVFILE Tuxedo environment variable and overrides WSENVFILE property of resource adapter.

WSNADDR
Overrides WSNADDR Tuxedo environment variable and overrides WSNADDR property of resource adapter.

Sample Configuration

The following screens from the WebSphere Administrative Console illustrate a sample configuration. For more information about using the WebSphere Administrative Console, refer to the IBM WebSphere documentation.

First, the resource adapter was installed and its properties set.

Note: When configuring an XMLink resource adapter in WebSphere 6, make sure that the native path is set to the same location as the archive path. The Class Path should contain the path to tconn.jar. For TConn.rar, this would typically be ${CONNECTOR_INSTALL_ROOT}/TConn.rar/tconn.jar.

Next, shared library settings were configured that can later be associated with an application.

Then, the application and its libraries and other settings were configured.