| Using 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/xug/.
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.
For SOAP implementations:
- Copy the following files and templates to the directory specified by Tuxedo's
APPDIRenvironment variable:
For RMI/IIOP implementations:
- Copy the following files and templates to the:
SoapServices.xml
- (optional)
SoapServices.xsdif validating parser is run onSoapServices.xml
- (optional)
TuxedoServices.xsdif validating parser is run onTuxedoServices.xml- Copy the following file to the directory specified by Tuxedo's
APPDIRenvironment variable:
TuxedoServices.xml
For EJB implementations interacting directly with the business-logic EJBs:
- Copy the following files and templates to the directory specified by Tuxedo's
APPDIRenvironment variable:
EJBServices.xml
Configuring the Tuxedo Server Machine
On the Tuxedo server machine, you need to configure the following:
- XMLink Universal Gateway Tuxedo server
- XMLink Universal Gateway environment
- Tuxedo service definition file
- For SOAP implementations, the SOAP version of the service definition file
- For RMI/IIOP implementations, the deployed jar file for the Gateway Adapter EJB
- For EJB implementations, the deployed jar files for business logic EJBs
In the
ubbconfigfile (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:
- To allow for different options on the Gateway Tuxedo Servers
- Add the Gateway Tuxedo Server.
The default name of this server is
gateway(UNIX and Linux) orgateway.exe(Windows). The server executable for Tuxedo 7+ is in theInstall_Dir/util/tuxdirectory; for Tuxedo 6.5 in theInstall_Dir/util/tux6directory.- Specify the startup options for the Gateway Tuxedo Server:
CLOPT = "-A -- "Note: One method for specifying JVM settings is within the
CLOPTparameter string using the-Joption, following the--. The following example illustrates how to specify filenames for the services and properties files using this option. (For the default names, these settings are not required.)CLOPT = "-A -- -J \"-DXUG.Config=MyGateway.properties
-DXUG.SoapServices=MySoapServices.xml
-DXUG.TuxedoServices=MyTuxedoServices.xml\""Warning: Since Tuxedo limits the length of the
CLOPTstring, use the properties file to specify JVM system options as needed.- Add the Gateway Tuxedo Service.
In the
SERVICESsection ofubbconfig, you need to add the following service:GATEWAY_SERVICE
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
APPDIRdirectory.Note:
Setting the Gateway Tuxedo Server Environment
- On the Gateway Tuxedo Server, set the
PATHenvironment variable to include the directory location of the Gateway Tuxedo Servergateway(UNIX and Linux) orGateway.exe(Windows).- 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:
- For Oracle Tuxedo 6.5, the library is
tconn6n.dll.LD_LIBRARY_PATH(UNIX and Linux) orSHLIB_PATH(HP PA-RISC)- Add the location of the Oracle Tuxedo libraries from XMLink:
- For Oracle Tuxedo 6.5, the library is
libtconn6n.so.Configuring the Java Environment on the Tuxedo Server
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:
Configuring Services for the Gateway Tuxedo Server
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,FMLorFML32buffers are defined in a different section of this file. See "Sample Tuxedo Service File-Format 2."The other format, used only for
FMLandFML32buffers, specifies the fields as part of this element using thenameattribute. See page 4-9, "Sample Tuxedo Service File-Format 3."TuxedoOutputType- Specifies the Tuxedo output type:
FML,FML32,STRINGorCARRAY.For
FMLorFML32, 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 theTuxedoOutputType, or the default field name ofreturn,will be used. If an empty field list is provided, no data will be returned.Complex SOAP types may fill multiple
FMLorFML32fields. 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
FMLbuffer. It can appear within theTuxedoInputTypeorTuxedoOutputTypeelements or within thetuxedo-service-registryelement as illustrated in the following examples.FML32- Specifies the field definition of an
FML32buffer. It can appear within theTuxedoInputTypeorTuxedoOutputTypeelements or within thetuxedo-service-registryelement as illustrated in the following examples.field(
FMLorFML32elements) Uses thenameattribute 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.
<?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>
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>
<?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
The SOAP-RPC protocol is used to consume enterprise services. For SOAP-RPC configurations, service configuration is on the Gateway Tuxedo Server machine.
For RMI/IIOP configurations, service configuration is on the EIS machine for use with the Gateway Adapter EJB.
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
namespaceattribute provided forsoap:bodyelements 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-actionattribute specifies the SOAP action string to use.Note: IBM WebSphere ignores the
soap-actionattribute, 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
XugReturnbean. Note that XML schema definitions for complex types are not required for the SOAP-RPC client implementation.Configuring Services for EJB
Since EJB implementation interact with business-logic EJBs directly, you need to configure EJB access in the
EJBServices.xmlfile.Here is a sample
EJBServices.xmlfile:<?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
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
-Joption withCLOPTin theubbconfigfile. 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 theGateway.propertiesfile in theconfigdirectory.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.TuxedoServeris the default, and the only supported value at present.XUG.DeliveryAgent- Specifies the delivery agent to use. Available values are
SOAP-RPC,RMI/IIOP, orEJB.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.XslXlatorEngineXUG.TuxedoServices- (optional) Specifies the Tuxedo service definition file to use.
TuxedoServices.xmlis the default.XUG.SoapServices- (optional) Specifies the SOAP service definition file to use.
SoapServices.xmlis 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/GatewayAdapterHomeXUG.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:
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 torequest.xsdandresponse.xsdin theconfigdirectory in order to write XSL for data translation.Note: The
XUG.DataTranslatorproperty 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
SINGLEandMAP.SINGLEis the default.com.prolifics.xug.xlator.xsl.single.fileName- Specifies the XSL file to use for the
SINGLEfactory type.passthru.xslis the default.com.prolifics.xug.xlator.xsl.map.mapFile- Specifies the map file to use for the
MAPfactory type.xslmap.propertiesis the default. Property settings in the map file have the form,service_name.out=filenameorservice_name.in=filename, whereservice_nameis the reference name of a service, andfilenameis the name of an XSL file to use for data translation for that service. Use the.insetting for translation of an XML message used to invoke a service, and.outfor 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
MAPfactory 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 ispassthru.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:
com.prolifics.xug.dda.soap.SoapServiceRegistry.validation
com.prolifics.xug.server.tuxedo.TuxedoServiceRegistry.validation
They may be left unset or set to
falseif validation is not to be used. By default, validation is turned off.These properties can be set in the properties file specified by
XUG.Configor set individually in the configuration files specified byXUG.SoapServicesandXUG.TuxedoServices.
XUG.Configcan also contain a setting for the parser with the following Java system property:
javax.xml.parsers.SAXParserFactory
For the Xerces SAX2 parser, specify the following value:
org.apache.xerces.jaxp.SAXParserFactoryImplThe 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
ULOGfile; 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 implementations using WebSphere need the deployed jar file for the Gateway Adapter EJB. This must be added to the
CLASSPATHof the Tuxedo server machine, as noted in the "Configuring the Java Environment on the Tuxedo Server" section.
EJB implementations using WebSphere need the deployed jar files for the business logic EJBs in the
CLASSPATHof the Tuxedo server machine.
Configuring the Enterprise Information System Machine
For RMI/IIOP implementations, you need to configure the following on the EIS machine:
- XMLink Universal Gateway Adapter EJB
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 thelibdirectory. Note that for WebSphere Application Server, the deployed jar file must also be in theCLASSPATHof the Tuxedo server.Configuring the Java Environment on the EIS
The EIS needs the following in the Java configuration:
Configuring the EJB Properties File
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, andXUG.Interface.endpointx.URL.XUG.ConfigandXUG.SoapServicesmay be specified as EJB properties.
XUG.Configspecifies a configuration properties file that may be used for the GatewayAdapter EJB. The default value isGatewayAdapter.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.SoapServicesspecifies the SOAP service definition file. Its default value isSoapServices.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
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
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:
- SOAP endpoints (Alternative option: specify in the SOAP service definition file.)