Using XMLink Universal Gateway


Chapter 4. Configuring XMLink Universal Gateway

This chapter primarily focuses on how to configure XMLink Universal Gateway on both the Tuxedo server machine and the EIS machines. Information from this chapter is summarized in Appendix A, "Setup Checklist."

If there is additional information on configuring XMLink Universal Gateway, you can find it in the Release Notes section at http://docs.prolifics.com/docs/xug/index.htm.

Before configuring XMLink Universal Gateway, you need to know which Delivery Agent will be used:

In this manual, configurations using SOAP-RPC are called SOAP implementations and configurations using RMI/IIOP are called RMI/IIOP implementations. Configurations interacting directly with the business logic EJBs are called EJB implementations. Steps needed for each delivery agent are indicated at the beginning of each section.


Distributing Program Files

After XMLink Universal Gateway is installed, new installations will need to copy certain files and templates from the installation location in order to make them available to the program.

SOAP-RPC

For SOAP implementations:

RMI/IIOP

For RMI/IIOP implementations:

EJB

For EJB implementations interacting directly with the business-logic EJBs:

For EJB implementations using XMLink Universal Gateway's Adapter EJB to interact with the business-logic EJBs, refer to the list for RMI/IIOP. In addition, add the following file to the Web services working directory on the EIS machine:


Configuring the Tuxedo Server Machine

On the Tuxedo server machine, you need to configure the following:

Configuring the Gateway Tuxedo Server

SOAP-RPC
RMI/IIOP
EJB

In the ubbconfig file (or its equivalent), you need to set the Gateway Tuxedo Server to be part of the Tuxedo configuration. You will need to configure multiple servers:

On the Tuxedo Server:

Configuring the Environment

Setting the Tuxedo Environment

SOAP-RPC
RMI/IIOP
EJB

The environment must already be configured to access Oracle Tuxedo libraries. In addition, Tuxedo applications typically already have the following variables set in the environment:

TUXDIR
Specifies the location of the Tuxedo installation.

TUXCONFIG
Specifies the location of the Tuxdeo configuration file.

APPDIR
Specifies the location of the Tuxedo application files.

FIELDTBLS
FIELDTBLS32
Specifies the names of the files containing the field table information for FML and FML32 typed records.

FLDTBLDIR
FLDTBLDIR32
Specifies the directories to search for the field tables if those files are not located in the APPDIR directory.

Note:

Setting the Gateway Tuxedo Server Environment

SOAP-RPC
RMI/IIOP
EJB
  1. On the Gateway Tuxedo Server, set the PATH environment variable to include the directory location of the Gateway Tuxedo Server gateway (UNIX and Linux) or Gateway.exe (Windows).
  2. Configure the environment to contain the location of the Java native libraries for accessing Oracle Tuxedo.

PATH (Windows only)
Add the location of the Oracle Tuxedo libraries from XMLink:

LD_LIBRARY_PATH (UNIX and Linux) or SHLIB_PATH (HP PA-RISC)
Add the location of the Oracle Tuxedo libraries from XMLink:

Configuring the Java Environment on the Tuxedo Server

SOAP-RPC
RMI/IIOP
EJB

The Gateway Tuxedo server requires certain settings as part of the Java environment. The following table describes the environment variables for use with IBM WebSphere 5:

Table 4-1 Java Environment for Tuxedo Server

Variable Description

JAVA_HOME

Specify the location of the Java installation.

CLASSPATH

Specify the location of the Gateway Adapter's Java files.

Specify the location of J2EE Connector Architecture classes and JNDI services.

For SOAP implementations, specify the location of the SOAP RPC class files.

For SOAP implementations, specify the location of this XML parser. Must be version 1.4.2 or greater.

For RMI/IIOP implementations using WebSphere, specify the location of the deployed Gateway Adapter EJB's jar file.

For EJB implementations using WebSphere, specify the location of the deployed business logic EJB jar files.

Specify location of classes used for XSL data translator.

For com.sun.mail.util.*

Configuring Services for the Gateway Tuxedo Server

SOAP-RPC
RMI/IIOP
EJB

Each enterprise service is listed in XML format in the Tuxedo service definition file. The default name of this file is TuxedoServices.xml, but you can specify a different name with the JVM property, XUG.TuxedoServices. This file maps the Tuxedo service name to a reference name, which is then mapped to an enterprise service name in the SOAP service definition file.

If a path is not specified, this file is located in the working directory of the Tuxedo server.

The Tuxedo service definition file also specifies input and output buffer types for each service. By specifying names for each FML and FML32 buffer that is used, each buffer may be defined in terms of the fields it may contain. The buffer names may be chosen arbitrarily, and the same buffer can be used for both input and output, as well as for multiple service definitions.

This file contains the following settings:

ServiceName
Specifies the reference service name.

TuxedoAdvertise
Specifies the name to be advertised as a Tuxedo service.

TuxedoInputType
Specifies the Tuxedo input type element using one of two possible formats.

One format sets this element to one of the following values: FML, FML32, STRING, CARRAY, or character data. If you use this format, FML or FML32 buffers are defined in a different section of this file. See "Sample Tuxedo Service File-Format 2."

The other format, used only for FML and FML32 buffers, specifies the fields as part of this element using the name attribute. See page 4-9, "Sample Tuxedo Service File-Format 3."

TuxedoOutputType
Specifies the Tuxedo output type: FML, FML32, STRING or CARRAY.

For FML or FML32, if the output data contains named parameters, XMLink Universal Gateway uses those names as the Tuxedo field names for the output data. If the output data does not contain named parameters, the first field name listed for the TuxedoOutputType, or the default field name of return, will be used. If an empty field list is provided, no data will be returned.

Complex SOAP types may fill multiple FML or FML32 fields. In that case, the elements of the complex type are mapped by name to Tuxedo fields with corresponding names, assuming there is no data translation.

FML
Specifies the field definition of an FML buffer. It can appear within the TuxedoInputType or TuxedoOutputType elements or within the tuxedo-service-registry element as illustrated in the following examples.

FML32
Specifies the field definition of an FML32 buffer. It can appear within the TuxedoInputType or TuxedoOutputType elements or within the tuxedo-service-registry element as illustrated in the following examples.

field

(FML or FML32 elements) Uses the name attribute to specify the Tuxedo field name. This name must match the SOAP-RPC parameter name used for input or an element name within a complex type returned by SOAP-RPC.

Sample Tuxedo Service File-Format 1
<?xml version="1.0" encoding="utf-8"?>
<!-- EJB Methods to be advertised as Tuxedo services -->
<tuxedo-service-registry>
<Service>
<ServiceName>addsvcshort</ServiceName>
<TuxedoAdvertise>addsvcshort</TuxedoAdvertise>
<TuxedoInputType>FML</TuxedoInputType>
<TuxedoOutputType><FML></TuxedoOutputType>
</Service>
</tuxedo-service-registry>
Sample Tuxedo Service File-Format 2

Use Format 2 or Format 3 to restrict the amount of data being processed to the named fields specified in the file.

<?xml version="1.0" encoding="utf-8"?>
<!-- EJB Methods to be advertised as Tuxedo services -->
<tuxedo-service-registry>
<Service>
<ServiceName>addsvcshort</ServiceName>
<TuxedoAdvertise>addsvcshort</TuxedoAdvertise>
<TuxedoInputType>FML</TuxedoInputType>
<TuxedoOutputType>
<FML>
<field name="Short3"/>
</FML>
</TuxedoOutputType>
</Service>
<FML>
<field name="Short1"/>
<field name="Short2"/>
</FML>
</tuxedo-service-registry>
Sample Tuxedo Service File-Format 3
<?xml version="1.0" encoding="utf-8"?>
<!-- EJB Methods to be advertised as Tuxedo services -->
<tuxedo-service-registry>
<Service>
<ServiceName>addsvcshort</ServiceName>
<TuxedoAdvertise>addsvcshort</TuxedoAdvertise>
<TuxedoInputType>
<FML>
<field name="Short1"/>
<field name="Short2"/>
</FML>
</TuxedoInputType>
<TuxedoOutputType>
<FML>
<field name="Short3"/>
</FML>
</TuxedoOutputType>
</Service>
</tuxedo-service-registry>

Configuring Services for SOAP-RPC

SOAP-RPC

The SOAP-RPC protocol is used to consume enterprise services. For SOAP-RPC configurations, service configuration is on the Gateway Tuxedo Server machine.

RMI/IIOP

For RMI/IIOP configurations, service configuration is on the EIS machine for use with the Gateway Adapter EJB.

SOAP-RPC
RMI/IIOP

Define the services in Gateway's SOAP service definition file. The default filename is SoapServices.xml, but another name can be specified using the JVM property, XUG.SoapServices, or the EJB property of the same name for the GatewayAdapter EJB.

If the path is not specified, its location depends on the delivery agent used. For the SOAP-RPC delivery agent, this file is located in the working directory of the Tuxedo server. (For the RMI/IIOP delivery agent, this file is located in the working directory for the GatewayAdapter EJB.)

Here is an example of a SOAP service definition file:

<?xml version="1.0" encoding="UTF-8"?>
<soap-service-registry
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xsi:noNamespaceSchemaLocation="SoapRegistry.xsd">
<endpoint ID="ep1">
<URL>http://localhost:9080/WebServiceWeatherWeb/servlet/rpcrouter
</URL>
<targetObjectURI>http://tempuri.org/com.prolifics.poc.Weather
</targetObjectURI>
</endpoint>
	<service alias="getWeather" soap-action="weatherAction"
IDREF="ep1">
<method-name>getWeather</method-name>
<message-in>
<param name="latitude" type="xsd:int"></param>
<param name="longtitude" type="xsd:int"></param>
</message-in>
		<message-out namespace="" typename="">
<param name="" type="xsd:string"/>
</message-out>
</service>
</soap-service-registry>

This file contains the following settings:

endpoint
Specifies the SOAP endpoint to connect to. The ID attribute specifies the name by which a service may be associated with a particular endpoint. Multiple endpoints may be used within a SOAP service description file. These endpoint definitions override any corresponding Interface properties specified in the properties file.

URL
Specifies the URL for a SOAP endpoint.

targetObjectURI
Specifies the targetObjectURI for a SOAP endpoint. This typically corresponds to the value of the namespace attribute provided for soap:body elements in the SOAP binding WSDL for the enterprise service.

service
Specifies the description of an enterprise service. The alias attribute specifies the reference service name. The soap-action attribute specifies the SOAP action string to use.

Note: IBM WebSphere ignores the soap-action attribute, but some SOAP servers, such as .NET, make use of it.

method-name
Specifies the name of the enterprise service.

message-in
Specifies the input message for the enterprise service.

message-out
Specifies the output message for the enterprise service.

param
Specifies a parameter used for input or output. For input, these correspond to message parts in the WSDL for an enterprise service. The name attribute should be the same as the message part name for the WSDL. The type attribute may have values that correspond to the names of simple SOAP types. Arrays of simple SOAP types may also be used, such as ArrayOfShort, ArrayOfString, etc. Only these canonical type names for arrays may be used. Namespaces prepended to these type names are ignored.

For output, type and name attributes are ignored, as these are determined from the XML that is returned. XMLink Universal Gateway can work with enterprise services which return complex types, but only complex types whose elements have simple types, except for the special case of the XugReturn bean. Note that XML schema definitions for complex types are not required for the SOAP-RPC client implementation.

Configuring Services for EJB

EJB

Since EJB implementation interact with business-logic EJBs directly, you need to configure EJB access in the EJBServices.xml file.

Here is a sample EJBServices.xml file:

<?xml version="1.0"?>
<ejb-service-registry xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:noNamespaceSchemaLocation="EJBRegistry.xsd"
xmlns:xsd1=
"http://www.testservice.com/schemas/TestServiceRemoteInterface">
	<endpoint ID="ep1">
<JNDIName>ejb/ejb/TestServiceHome</JNDIName>
</endpoint>
<endpoint ID="ep2">
<JNDIName>ejb/com/prolifics/xug/test/PerformanceHome</JNDIName>
</endpoint>
	<service alias="TCStrWait" IDREF="ep2">
<method-name>TCStrWait</method-name>
<method-in>
<param name="s1" type="Ljava.lang.String;"/>
<param name="wait" type="J"/>
</method-in>
<method-out>
<param name="s1" type="Ljava.lang.String;"/>
</method-out>
</service>
	<service alias="toupperString" IDREF="ep1">
<method-name>toupperString</method-name>
<method-in>
<param name="s1" type="[Ljava.lang.String;"/>
</method-in>
<method-out>
<param name="s1" type="Ljava.lang.String;"/>
</method-out>
</service>
	<service alias="addsvclong" IDREF="ep1">
<method-name>addsvclong</method-name>
<method-in>
<param name="l1" type="[J"/>
<param name="l2" type="[J"/>
</method-in>
<method-out>
<param name="l1" type="J"/>
</method-out>
</service>
	<service alias="getPerson" IDREF="ep1">
<method-name>getPerson</method-name>
<method-in>
</method-in>
<method-out>
<param name="lastName" type="Ljava.lang.String;"/>
<param name="firstName" type="Ljava.lang.String;"/>
<param name="address" type="[Ljava.lang.String;"/>
<param name="phone" type="Ljava.lang.String;"/>
</method-out>
</service>
	<service alias="setPerson" IDREF="ep1">
<method-name>setPerson</method-name>
<method-in>
<param name="person" type="Lmyclasses.person.Person;"/>
</method-in>
<method-out>
<param name="lastName" type="Ljava.lang.String;"/>
<param name="firstName" type="Ljava.lang.String;"/>
<param name="address" type="[Ljava.lang.String;"/>
<param name="phone" type="Ljava.lang.String;"/>
</method-out>
</service>
</ejb-service-registry>

Configuring Properties for the Gateway Tuxedo Server

SOAP-RPC
RMI/IIOP

Java system properties may be specified in a configuration properties file or as command line options for the JVM. Command line options for the JVM are specified using the -J option with CLOPT in the ubbconfig file. An example of this usage is in the section "Configuring the Gateway Tuxedo Server". A template for the configuration properties file is provided as part of the XMLink Universal Gateway installation. Look for the Gateway.properties file in the config directory.

The following properties are available.

XUG.Config
(optional) Specifies the name of the configuration properties file. The default name is Gateway.properties. This file is optional, but if used, you must specify the name in the JVM option string.

XUG.Server
(optional) Specifies the Gateway Tuxedo Server component to use. com.prolifics.xug.server.tuxedo.TuxedoServer is the default, and the only supported value at present.

XUG.DeliveryAgent
Specifies the delivery agent to use. Available values are SOAP-RPC, RMI/IIOP, or EJB.

XUG.DataTranslator
(optional) Specifies the data translator to use. By default, data translation is turned off and this property is set to none. To use data translation, set the property to the following value:
com.prolifics.xug.xlator.XslXlatorEngine

XUG.TuxedoServices
(optional) Specifies the Tuxedo service definition file to use. TuxedoServices.xml is the default.

XUG.SoapServices
(optional) Specifies the SOAP service definition file to use. SoapServices.xml is the default.

XUG.GatewayAdapter.JNDIName
(optional) For RMI/IIOP configurations, specifies the JNDI lookup name for the Gateway Adapter EJB. The default value is:
 com/prolifics/xug/dda/adapter/GatewayAdapterHome

XUG.Interface.endpointx.URL
XUG.Interface.
endpointx.TargetObjectURI
(optional) Specifies the URL and Target Object URI for each SOAP endpoint. May be overridden by an endpoint definition within the SOAP service definition file.
MyJavaProperty.xxx
(optional) Specifies any Java properties needed.

Java System Properties for XSL-based Data Translation

XMLink Universal Gateway allows you to write XSL (eXtensible Stylesheet Language) to transform the Tuxedo service's XML document to the enterprise application's XML format and vice versa. Three template files are included in your XMLink Gateway Adapter installation:

SOAP-RPC
RMI/IIOP

The following JVM system properties are used by the default XSL based data translator. Data translator files, such as passthru.xsl, should be located in the working directory for the Tuxedo server, and if the Gateway Adapter EJB is used, in its working directory also. Refer to request.xsd and response.xsd in the config directory in order to write XSL for data translation.

Note: The XUG.DataTranslator property must also be set. See "XUG.DataTranslator" for more information.

com.prolifics.xug.xlator.xsl.factory
Specifies the type of XSL factory to use. Possible values are SINGLE and MAP. SINGLE is the default.

com.prolifics.xug.xlator.xsl.single.fileName
Specifies the XSL file to use for the SINGLE factory type. passthru.xsl is the default.

com.prolifics.xug.xlator.xsl.map.mapFile
Specifies the map file to use for the MAP factory type. xslmap.properties is the default. Property settings in the map file have the form, service_name.out=filename or service_name.in=filename, where service_name is the reference name of a service, and filename is the name of an XSL file to use for data translation for that service. Use the .in setting for translation of an XML message used to invoke a service, and .out for translation of the XML message returned from a service call.

com.prolifics.xug.xlator.xsl.map.fallback
Specifies the default XSL file to use for translation of a service request or response, for the MAP factory type. This file is used when a specific XSL file is not specified in the map file for input or output for a service. The default is passthru.xsl.

Java System Properties for Data Validation

You can have XMLink Universal Gateway validate the XML data using a SAX2 parser by setting the following properties to true:

They may be left unset or set to false if validation is not to be used. By default, validation is turned off.

These properties can be set in the properties file specified by XUG.Config or set individually in the configuration files specified by XUG.SoapServices and XUG.TuxedoServices.

XUG.Config can also contain a setting for the parser with the following Java system property:

For the Xerces SAX2 parser, specify the following value:

org.apache.xerces.jaxp.SAXParserFactoryImpl

The warnings and errors generated during XML validation are written to different locations depending on the delivery agent. For SOAP-RPC implementations, validation warnings, recoverable errors, and fatal errors are written to the Gateway Tuxedo Server's ULOG file; however, fatal errors also cause an exception to be thrown.

For RMI/IIOP implementations, recoverable errors and fatal errors are written to System.err. Again, fatal errors cause an exception to be thrown.

Warning: Many light-weight parsers do not support validation.

Configuring the Deployed EJB Jar File

RMI/IIOP

RMI/IIOP implementations using WebSphere need the deployed jar file for the Gateway Adapter EJB. This must be added to the CLASSPATH of the Tuxedo server machine, as noted in the "Configuring the Java Environment on the Tuxedo Server" section.

EJB

EJB implementations using WebSphere need the deployed jar files for the business logic EJBs in the CLASSPATH of the Tuxedo server machine.


Configuring the Enterprise Information System Machine

For RMI/IIOP implementations, you need to configure the following on the EIS machine:

Deploying the Gateway Adapter EJB

RMI/IIOP

The Gateway Adapter EJB must be deployed on the EIS machine. Follow the instructions provided by your J2EE application server. A deployable jar file, GatewayAdapter.jar, is provided in the lib directory. Note that for WebSphere Application Server, the deployed jar file must also be in the CLASSPATH of the Tuxedo server.

Configuring the Java Environment on the EIS

RMI/IIOP

The EIS needs the following in the Java configuration:

Table 4-2 Java Environment for EIS

Variable Description

JAVA_HOME

Specify the location of the Java installation.

CLASSPATH

Specify the location of the Gateway Adapter's Java files.

Specify the location of SOAP-RPC classes.

Specify the location of this XML parser. Must be version 1.4.2 or greater.

Specify the location of classes used for XSL data translator.

Specify the location of J2EE Connector Architecture classes and JNDI services.

For com.sun.mail.util.*

Configuring the EJB Properties File

RMI/IIOP

The GatewayAdapter EJB uses some of the same properties as for the Gateway Tuxedo Server. Most implementations can use the default property values so that these properties often need not be explicitly set. Applicable properties include XUG.Config, XUG.SoapServices, XUG.Interface.endpointx.TargetObjectURI, and XUG.Interface.endpointx.URL. XUG.Config and XUG.SoapServices may be specified as EJB properties.

XUG.Config specifies a configuration properties file that may be used for the GatewayAdapter EJB. The default value is GatewayAdapter.properties. This file is optional unless you deploy multiple EJBs with different configurations. Place this file in the working directory of the application server.

XUG.SoapServices specifies the SOAP service definition file. Its default value is SoapServices.xml. This file should be located in the working directory of the application server.

The GatewayAdapter EJB makes use of the default XSL based data translator; therefore, XSL files and Java system properties for the data translator are also applicable. These properties, as well as other Java system properties, may be specified as JVM properties for the application server. See "Java System Properties for XSL-based Data Translation" for details about the properties used by the default data translator.

Note: In IBM WebSphere, EJB properties can be configured in the Application Assembly Tool.

Configuring the Enterprise Services on the EIS

RMI/IIOP

As covered in an earlier section, each enterprise service is listed in XML format in SoapServices.xml. This file maps the reference service name to the enterprise service name. For RMI/IIOP implementations, this file is located in the working directory for the EJB. For more information about this file, see "Configuring Services for the Gateway Tuxedo Server."

Place this file in the working directory of your application server.

Configuring the Gateway Adapter Properties File on the EIS

RMI/IIOP

SOAP endpoint properties can be configured in the configuration properties file for the Gateway Adapter EJB, or in its SOAP service description file. The configuration is the same as for the Tuxedo server's SOAP-RPC delivery agent. See "Configuring Services for the Gateway Tuxedo Server."

This includes properties for: