SALT leverages the Oracle Tuxedo Service Metadata Repository to define service contract information for both existing Oracle Tuxedo services and SALT proxy services. Service contract information for all listed Oracle Tuxedo services is obtained by accessing the Oracle Tuxedo Service Metadata Repository system service provided by the local Oracle Tuxedo domain. Typically, SALT calls the
TMMETADATA system as follows:
Table 1 lists Oracle Tuxedo Service Metadata Repository service-level keywords used and interpreted by SALT.
|
|
|
|
|
|
|
|
Do not use “webservice” to define a native Oracle Tuxedo service. This value is always used to define services converted from external Web services.
|
|
|
|
|
|
|
|
|
STRING, CARRAY, XML, MBSTRING, VIEW, VIEW32, FML, FML32, X_C_TYPE, X_COMMON, X_OCTET, NULL (input buffer is empty)
|
|
|
STRING, CARRAY, XML, MBSTRING, VIEW, VIEW32, FML, FML32, X_C_TYPE, X_COMMON, X_OCTET, NULL (input buffer is empty)
|
Note:
|
The value is case sensitive, if outbuf specifies any buffer type other than the above mentioned buffer types, the buffer is treated as a custom buffer type.
|
|
|
|
STRING, CARRAY, XML, MBSTRING, VIEW, VIEW32, FML, FML32, X_C_TYPE, X_COMMON, X_OCTET, NULL (input buffer is empty).
|
Note:
|
The value is case sensitive, if errbuf specifies any buffer type other than the above mentioned buffer types, the buffer is treated as a custom buffer type.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Oracle Tuxedo RECORD typed buffers can describe COBOL copybook information.
|
|
|
Specifies the record name used by the service for the following input buffer types: RECORD.Oracle SALT requires that you specify the record name rather than accept the default inrecord setting. This keyword is for native Tuxedo services only.
|
|
|
Specifies the record name used by the service for the following output buffer types: RECORD. Oracle SALT requires that you specify the record name rather than accept the default outrecord setting. This keyword is for native Tuxedo services only.
|
|
|
Specifies the record name used by the service for the following error buffer types: RECORD.Oracle SALT requires that you specify the record name rather than accept the default errrecord setting.
|
|
•
|
VIEW, VIEW32, X_C_TYPE, or X_COMMON typed buffers
|
|
•
|
FML or FML32 typed buffers
|
|
•
|
STRING, CARRAY, XML, MBSTRING, and X_OCTET typed buffers
|
|
•
|
FML32 typed buffersthat support embedded VIEW32 and FML32 buffers
|
|
•
|
View32 typed buffers that support embedded VIEW32 buffers
|
Table 2 lists the Oracle Tuxedo Service Metadata Repository parameter-level keywords used and interpreted by SALT.
|
|
|
|
|
|
•
|
VIEW, VIEW32, X_C_TYPE, or X_COMMON
|
|
•
|
STRING, CARRAY, XML, MBSTRING, or X_OCTET
|
|
|
|
|
|
|
Specifies the view structure name if the parameter type is view32. For any other typed parameter, SALT ignores this value.
|
|
|
Original values: in, out, inout, noaccess.
New added values: err, inerr, outerr, inouterr.
|
|
|
|
|
|
The general definition applies for this parameter. The default is 1. For SALT, the value for the count parameter must be greater than or equal to requiredcount.
|
|
|
|
|
|
|
|
|
|
|
|
Oracle Tuxedo RECORD typed buffers can describe COBOL copybook information.
|
|
|
|
|
|
|
|
|
Combination of inheader and outheader.This parameter is both added to and retrieved from the SOAP header portion of the SOAP message.
|
Each native WSDF must be defined with a unique
WSDF name. A
WSDF can define one or more <
WSBinding> elements for more Web service application details (such as SOAP protocol details, the Oracle Tuxedo service list to be exposed as web service operations, and so on).
The mapsoapheader attribute is used to configure SOAP headers. It defines an FML32 field that represents the SOAP header. It is
TA_WS_SOAP_HEADER STRING type.
|
Note:
|
The mapsoapheader attribute It is defined in wssoapflds.h file shipped with SALT.
|
Listing 1 shows a SOAP header definition example.
<Property name="mapsoapheader" value="true" />
The mapsoapheader attribute default value is "
false" which indicates the GWWS does not execute mapping between the SOAP header and FML fields.
If mapsoapheader is set to
true, the mapping behavior is as follows for inbound and outbound services:
Each WSBinding object is defined using the <WSBinding> element. Each WSBinding object must be defined with a unique WSBinding id within the
WSDF. The WSBinding id is a required indicator for the
SALTDEPLOY file reference used by the
GWWS.
Listing 4 shows how SOAP protocol details are redefined using the <
SOAP> sub-element.
Within the <SOAP> element, a set of access endpoints can be specified. The URL value of these access endpoints are used by corresponding
GWWS servers to create the listen HTTP/S protocol port. It is recommended to specify one HTTP and HTTPS endpoint (at most), for each
GWWS server for an
inbound WSBinding object.
Each service object is defined using the <Service> element. Each service must be specified with the “
name” attribute to indicate which Oracle Tuxedo service is exposed. Usually, the “
name” value is used as the key value for obtaining Oracle Tuxedo service contract information from the Oracle Tuxedo Service Metadata Repository.
Listing 5 shows how a group of services are defined for WSBinding.
<Definition ...>
<WSBinding id="simpapp_binding">
<Servicegroup id="simpapp">
<Service name="toupper" />
<Service name="tolower" />
</Servicegroup>
...
</WSBinding>
</Definition>
Listing 6 shows a service that uses the “
MBCONV” custom plug-in to convert input and “
XMLCONV” custom plug-in to convert output.
<Definition ...>
<WSBinding id="simpapp_binding">
<Servicegroup id="simpapp">
<Service name="toupper" >
<Input>
<Msghandler>MBCONV</Msghandler>
</Input>
<Output>
<Msghandler>XMLCONV</Msghandler>
</Output>
</Service>
</Servicegroup>
...
</WSBinding>
</Definition>
To use WS-Policy files, the <Policy> element should be defined in the WSDF to incorporate these separate WS-Policy files. The
location attribute is used to specify the policy file path; both abstract and relative file path are allowed. The
use attribute is optionally used by message-level assertion policy files to specify the applied messages, request (input) message, response (output) message, fault message, or the combination of the three.
Listing 7 shows a sample of using WS-Policy Files in the native
WSDF file.
<Definition ...>
<WSBinding id="simpapp_binding">
<Servicegroup id="simpapp">
<Policy location=”./endpoint_policy.xml” />
<Policy location=”/usr/resc/all_input_msg_policy.xml” use=”input” />
<Service name="toupper">
<Policy location=”service_policy.xml” />
<Policy location=”/usr/resc/input_message_policy.xml”
use=”input” />
</Service>
<Service name="tolower" />
</Servicegroup>
....
</WSBinding>
</Definition>
|
Note:
|
Before executing tmwsdlgen, the TUXCONFIG environment variable must be set correctly and the relevant Oracle Tuxedo application using TMMETADATA must be booted.
|
|
•
|
GWWS gets REQUEST_VERSION and VERSION_RANGE from the UBBCONFIG file.
|
Listing 8 shows an example where GWWS inherits a request version "
1" from its
UBBCONFIG settings, and therefore exposes services that are advertised by Oracle Tuxedo application servers which include "
1" in their
VERSION_RANGE settings (such as
GROUP1 here). If a service exposed by GWWS is actually performed by a server in
GROUP2, the result is a
TPENOENT error forwarded to the remote Web Services client.
MIF - Metadata repository file.
FML32 - FML32 field table file.
WSDF - Non-native WSDF file.
Table 3 lists the Oracle Tuxedo definition files generated by SALT WSDL Converter.
|
|
|
|
|
SALT WSDL Converter converts each wsdl:operation to a Oracle Tuxedo service metadata syntax compliant service called SALT proxy service. SALT proxy services are advertised by GWWS servers to accept ATMI calls from Oracle Tuxedo applications.
|
|
|
SALT maps each wsdl:message to an Oracle Tuxedo FML32 typed buffer. The SALT WSDL Converter decomposes XML Schema of each message and maps each basic XML snippet as an FML32 field. The generated FML32 fields are defined in a definition table file, and the field name equals to the XML element local name by default.
|
|
|
|
|
|
WSDL embedded XML Schema and imported XML Schema (XML Schema content referenced with <xsd:import>) are saved locally as .xsd files. These files are used by GWWS servers and need to be saved under the same directory.
|
Table 4 lists WSDL Element-to-Tuxedo Service Metadata Definition Keyword mapping rules.
Table 5 lists WSDL Element-to-WSDF Element mapping rules.
|
|
|
|
|
|
|
|
|
|
|
Each wsdl:binding object maps to a WSDF WSBinding element.
|
|
|
|
Each wsdl:binding referenced wsdl:portType object maps to the Servicegroup element of the corresponding WSBinding element.
|
|
|
|
If namespace prefix “soap” refers to URI “ http://schemas.xmlsoap.org/wsdl/soap/”, the SOAP version attribute value is “ 1.1”;
If namespace prefix “soap” refers to URI “ http://schemas.xmlsoap.org/wsdl/soap12/”, the SOAP version attribute value is “ 1.2”.
|
|
|
|
|
|
|
|
Each wsdl:operation object maps to a Service element of the corresponding WSBinding element.
|
|
|
|
Each soap:address endpoint defined for a wsdl:binding object maps to a Endpoint element of the corresponding WSBinding element.
|
The keyword tuxservice in the SALT proxy service metadata definition is the truncated value of the original Web Service operation local name if the operation name is more than 15 characters.
The truncated tuxservice value may be duplicated for multiple SALT proxy service entries. Since GWWS server uses
tuxservice values as the advertised service names, you must manually resolve the naming conflict among multiple SALT proxy services to avoid uncertain service request delivery. To resolve the naming conflict, you should assign a unique and meaningful name to
tuxservice.
|
•
|
Update FLDTBLDIR32 and FIELDTBLS32 environment variables to add the generated FML32 field table files.
|
|
•
|
The XSDDIR and XSDFILES environment variables, are introduced in the SALT 2.0 release. They are used by the GWWS server to load all external XML Schema files at run time. Multiple XML Schema file names should be delimited with comma ‘ ,’. For instance, if you placed XML Schema files: a.xsd, b.xsd and c.xsd in directory /home/user/myxsd, you must set environment variable XSDDIR and XSDFILES as follows before booting the GWWS server:
|
Listing shows an example where Oracle Tuxedo programs (client or server) call an external Web service exposed by both GWWS in groups
GROUP2 and
GROUP3. Programs using version
1 or
2 are routed to the service exposed by GWWS in
GROUP2 which may connect to endpoint
1, and programs using version
3 or
4 are routed to the service exposed by GWWS in
GROUP3 which may connect to a different endpoint than GWWS in
GROUP2.
The SALT Deployment file (SALTDEPLOY) defines a SALT Web service application. The
SALTDEPLOY file is the major input for Web service application in the binary
SALTCONFIG file.
Listing 10 shows how to import WSDF files in the
SALTDEPLOY file.
Each GWWS server can be deployed with a group of inbound WSBinding objects and a group of outbound WSBinding objects defined in the imported WSDF files. Each WSBinding object is referenced using attribute “
ref=<wsdf_name>:<WSBinding id>”. For inbound WSBinding objects, each
GWWS server must specify at least one access endpoint as an inbound endpoint from the endpoint list in the WSBinding object. For outbound WSBinding objects, each GWWS server can specify zero or more access endpoints as outbound endpoints from the endpoint list in the WSBinding object.
Listing 11 shows how to configure GWWS servers with both inbound and outbound endpoints.
Properties are configured in the <GWInstance> child element
<Properties>. Each individual property is defined by using the
<Property> element which contains a “
name” attribute and a “
value” attribute). Different “
name” attributes represent different property elements that contain a value.
Table 6 lists GWWS server-level properties.
Listing 12 shows an example of how GWWS properties are configured.
<Deployment ..>
...
<WSGateway>
<GWInstance id="GWWS1">
.......
<Properties>
<Property name="thread_pool_size" value="20"/>
<Property name="enableMultiEncoding" value="true"/>
<Property name="timeout" value="600"/>
</Properties>
</GWInstance>
</WSGateway>
...
</ Deployment>
ASCII, BIG5, CP1250, CP1251, CP1252, CP1253, CP1254, CP1255, CP1256, CP1257, CP1258, CP850, CP862, CP866, CP874, EUC-CN, EUC-JP, EUC-KR, GB18030, GB2312, GBK, ISO-2022-JP, ISO-8859-1, ISO-8859-13, ISO-8859-15, ISO-8859-2, ISO-8859-3, ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8, ISO-8859-9, JOHAB, KOI8-R, SHIFT_JIS, TIS-620, UTF-16, UTF-16BE, UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7, UTF-8
<Deployment ..>
...
<WSGateway>
<GWInstance id="GWWS1">
.......
<Properties>
<Property name="enableMultiEncoding" value="
true"/>
</Properties>
</GWInstance>
</WSGateway>
...
</ Deployment>
Table 7 explains the detailed SOAP message and Oracle Tuxedo buffer encoding mapping rules if the GWWS server level multiple encoding switch is turned on.
Certificate information must be configured in order for the GWWS server to create an SSL listen endpoint, or to use X.509 certificates for authentication and/or message signature. All
GWWS servers defined in the same deployment file shares the same certificate settings, including the private key file, trusted certificate directory, and so on.
The private key file is configured using the <Certificate>/<PrivateKey> sub-element. The private key file must be in PEM file format and stored locally. SSL clients can optionally be verified if the
<Certificate>/<VerifyClient> sub-element is set to
true.
|
Note:
|
The "cn" attribute of a distinguished name is used as a key for certificate lookup. Wildcards used in a name are not supported. Empty subject fields are not allowed. This limitation is also found in Oracle Tuxedo.
|
Listing 14 shows a
SALTDEPLOY file segment configuring
GWWS server certificates.
<Deployment ..>
...
<System>
<Certificates>
<PrivateKey>/home/user/gwws_cert.pem</PrivateKey>
<VerifyClient>true</VerifyClient>
<CertPath>/home/user/trusted_cert</CertPath>
</Certificates>
</System>
</Deployment
A plug-in is a set of functions that are called when the GWWS server is running. SALT provides a plug-in framework as a common interface for defining and implementing plug-ins. Plug-in implementation is carried out through a dynamic library that contains the actual function code. The implementation library can be loaded dynamically during
GWWS server start up. The functions are registered as the implementation of the plug-in interface.
In order for the GWWS server to load the library, the library must be specified using the
<Plugin>/<Interface> element in the
SALTDEPLOY file.
Listing 15 shows a
SALTDEPLOY file segment configuring multiple customized plug-in libraries to be loaded by the
GWWS servers.
<Deployment ..>
...
<System>
<Plugin>
<Interface lib=”plugin_1.so” />
<Interface lib=”plugin_2.so” />
</Plugin>
</System>
</Deployment
Listing 16 shows a
SALTDEPLOY file segment enabling WS-Addressing for a referenced outbound Web service binding.
<Deployment ..>
...
<WSGateway>
<GWInstance id="GWWS1">
...
<Outbound>
<Binding ref="app1:app1_binding">
<WSAddressing>
<Endpoint address=”https://myhost:8801/app1_async_point” tlsversion=TLSv1.2>
</WSAddressing>
<Endpoint use=" simpapp_GWWS1_HTTPPort" />
<Endpoint use=" simpapp_GWWS1_HTTPSPort" />
</Binding>
<Binding ref="app2:app2_binding">
<WSAddressing>
<Endpoint address=”https://myhost:8802/app2_async_point” tlsversion=TLSv1.2>
</WSAddressing>
<Endpoint use=" simpapp_GWWS1_HTTPPort" />
<Endpoint use=" simpapp_GWWS1_HTTPSPort" />
</Binding>
</Outbound>
...
</GWInstance>
</WSGateway>
...
</ Deployment>
|
Notes:
|
In a GWWS server, each outbound Web Service binding can be associated with a particular WS-Addressing endpoint address. These endpoints can be defined with the same hostname and port number, but the context path portion of the endpoint addresses must be different.
|
The attribute tlsversion specifies the TLS version used in an SSL network connection. GWWS endpoint uses TLS 1.2 by default. When it connects to an ealier release Tuxedo application which supports TLS 1.0 only, you need to configure the attribute to TLS 1.0. For more information, refer to
TLS Version Negotiation and Configuration.
If you create a WS-Addressing endpoint in the SALTDEPLOY file or not, you can explicitly disable the Addressing capability for particular outbound services in the WSDF. To disable the Addressing capability for a particular outbound service, you should use the property name “
disableWSAddressing” with a value set to “
true” in the corresponding
<Service> definition in the WSDF file. This property has no impact on any inbound services.
Listing 17 shows WSDF file segment disabling Addressing capability.
<Definition ...>
<WSBinding id="simpapp_binding">
<Servicegroup id="simpapp">
<Service name="toupper">
<Property name="disableWSAddressing" value=”true” />
</Service>
<Service name="tolower" />
</Servicegroup>
....
</WSBinding>
</Definition>
Listing 18 shows a Reliable Messaging policy file example.
<Definition ...>
<WSBinding ...>
<Servicegroup ...>
<Policy location=”RMPolicy.xml” />
<Service ... />
<Service ... />
...
</Servicegroup ...>
</WSBinding>
</Definition>
<WSBinding id="simpapp_binding">
<Servicegroup id="simpapp">
<Service name="tolower" />
The GWWS gateway supports Oracle Tuxedo domain security configuration for the following two authentication patterns:
The GWWS server passes the following string from the HTTP header of the client SOAP request for Oracle Tuxedo authentication.
If Oracle Tuxedo uses APP_PW, then the HTTP username value is ignored and the
GWWS server only uses the password string as the Oracle Tuxedo application password to check the authentication.
If Oracle Tuxedo uses USER_AUTH, then both the HTTP username and password value are used. In this case, the
GWWS server does not check the Oracle Tuxedo application password.
Listing 21 shows how to enable HTTP Basic Authentication for the outbound endpoints.
<Definition ...>
<WSBinding id="simpapp_binding">
<SOAP>
<AccessingPoints>
<Endpoint id=”...” address=”...”>
<Realm>SIMP_REALM</Realm>
</Endpoint>
</AccessingPoints>
</SOAP>
<Servicegroup id="simpapp">
....
</Servicegroup>
....
</WSBinding>
......
</Definition>
Once a service request is sent to an outbound endpoint using <Realm> element, the
GWWS server passes the Oracle Tuxedo client
uid and
gid to the authentication plug-in function, so that the plug-in can determine HTTP Basic Authentication
username/password according to the Oracle Tuxedo client information. To obtain Oracle Tuxedo client
uid / gid for HTTP basic authentication
username/password mapping, Oracle Tuxedo security level may also need to be configured in the
UBBCONFIG file. For more information, see
?$paratext>? and “Programming Outbound Authentication Plug-ins” in the SALT
Programming Web Services.
Table 8 lists the default WS-Security Policy files bundled by SALT.
Listing 22 shows a combination of policy assignment making that the service
“TOUPPER” requires client send a
UsernameToken (in plain text format) and an X509v3Token in request, and also requires the
SOAP:Body part of message to be signed with the X.509 token. The sample
“wsseapp” shows how to clip the WSSP 1.2
UserToken file used in the
<Service> element
.
<Definition ...>
<WSBinding id="simpapp_binding">
<Servicegroup id="simpapp">
<Policy location="salt:wssp1.2-Wss1.1-X509V3-auth.xml"/>
<Service name="TOUPPER" >
<Policy location="D:/wsseapp/wssp1.2-UsernameToken-Plain.xml"/>
<Policy location="salt:wssp1.2-signbody.xml" use="input"/>
</Service>
</Servicegroup>
....
</WSBinding>
......
</Definition>
Policy is referred using the “location” attribute of the
<Policy> element. A prefix “
salt:” means an SALT default bundled policy file is used. User-defined policy file can be used by directly specifying the file path.
The key file name is fixed to "saml_key.meta". It should be located in the same file folder specified by
"CertPath". This file should be protected by the file system and is in XML format.
A new command is added to wsadmin to manage the key file. This new command is used to generate new key file, add new record, delete existing record, and modify record. The name of the file it managed is "
saml_key.meta" in the current working directory.
Where the "-p password" is for the administrative password to access the newly created key file. A key file with name "
saml_key.meta" is created in the current working directory.
Where "-i" tells it to add an issuer with name
"authority.abc.com" with short local reference name
"abc" and the access password to access the key file. The key file
saml_key.meta" must exist in current working directory. Since
"-c" option is given, a public key certificate named
"abc.pem" must exist in the
"CertPath".
|
2.
|
Use "saml create" command to create the key file.
|
|
3.
|
Use "saml add -g" command to add GWWS record.
|
|
4.
|
Use "saml add -i" command to add trusted assertion issuer record for every trusted assertion issuer.
|
|
5.
|
Copy the file "saml_key.meta" to the directory described in the SALT deployment descriptor file "CertPath" element under "Certificate".
|
|
2.
|
Use "saml delete -g" to delete existing GWWS record.
|
|
3.
|
Use "saml add -g" to add a different GWWS record.
|
<?xml version="1.0"?>
<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
<sp:AsymmetricBinding>
<wsp:Policy>
<sp:InitiatorToken>
<wsp:Policy>
<sp:X509Tokensp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200512/IncludeToken/Always">
<wsp:Policy>
<sp:WssX509V3Token10/>
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:InitiatorToken>
<sp:RecipientToken>
<wsp:Policy>
<sp:X509Token sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200512/IncludeToken/Never">
<wsp:Policy>
<sp:WssX509V3Token10/>
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:RecipientToken>
<sp:AlgorithmSuite>
<wsp:Policy>
<sp:Basic256/>
</wsp:Policy>
</sp:AlgorithmSuite>
<sp:Layout>
<wsp:Policy>
<sp:Lax/>
</wsp:Policy>
</sp:Layout>
<sp:IncludeTimestamp/>
<sp:ProtectTokens/>
</wsp:Policy>
</sp:AsymmetricBinding>
<sp:SignedSupportingTokens>
<wsp:Policy>
<sp:SamlToken
sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
<wsp:Policy>
<sp:WssSamlV11Token10/>
</wsp:Policy>
</sp:SamlToken>
</wsp:Policy>
</sp:SignedSupportingTokens>
</wsp:Policy>
Table 10 lists what optional SAML assertion elements must present.
In NONE and
APP_PW cases, if the optional element
"Subject" exists, then
"NameID" is used to access Oracle Tuxedo. If the optional element
"Subject" does not exist, then the client assumes anonymous user identity to access Oracle Tuxedo. If the anonymous access is not allowed (i.e. no credential mapping for anonymous), then the request fails.
If the SAML assertion does not contain a
"Subject" element and Tuxedo
SECURITY level is configured at
USER_PW, ACL, or
MANDATORY_ACL, then the request is rejected.
Currently Tuxedo SALT only support single certificate which is configured through the "System" element in the deployment descriptor, with this limitation all the requests going through different instances of GWWS gateway
1 will use same certificate to establish SSL/TLS connection. Invariably, in the eyes of the Web Service they all come from the same user; thus same access privilege. This new feature will remove this constraint and make it possible to use different certificate to represent different client or gateway.
wsloadcf reads a deployment file and all imported WSDF files and WS-Policy files referenced in the deployment file, checks the syntax according to the XML schema of each file format, and optionally loads a binary configuration file called
SALTCONFIG. The
SALTCONFIG and (optionally)
SALTOFFSET environment variables point to the
SALTCONFIG file and (optional) offset where the information should be stored.
wsloadcf validates the given SALT configuration files according to the predefined XML Schema files. XML Schema files needed by SALT can be found at directory:
$TUXDIR/udataobj/salt.
wsloadcf can execute for validating purpose only without generating the binary version
SALTCONFIG once option “
-n” is specified.
SALT requires at least one TMMETADATA server defined in the
UBBCONFIG file. Multiple
TMMETADATA servers are also allowed to increase the throughput of accessing the Oracle Tuxedo service definitions.
Listing 31 lists a segment of the
UBBCONFIG file that shows how to define
TMMETADATA servers in an Oracle Tuxedo application.
To boot GWWS instances defined in the SALTDEPLOY file, the
GWWS servers must be defined in the *
SERVERS section of the
UBBCONFIG file. You can define one or more
GWWS server instances concurrently in the
UBBCONFIG file. Each
GWWS server must be assigned with a unique instance id with the option “
-i” within the Oracle Tuxedo domain. The instance id must be present in the XML version
SALTDEPLOY file and the generated binary version
SALTCONFIG file.
Listing 32 lists a segment of the
UBBCONFIG file that shows how to define
GWWS servers in an Oracle Tuxedo application.
|
Notes:
|
Be sure that the TMMETADATA system server is set up in the UBBCONFIG file to start before the GWWS server boots. Because the GWWS server calls services provided by TMMETADATA, it must boot after TMMETADATA.
|
To ensure TMMETADATA is started prior to being called by the
GWWS server, put
TMMETADATA before
GWWS in the
UBBCONFIG file or use
SEQUENCE parameters in *
SERVERS definition in the
UBBCONFIG file.
SALT configuration information is pre-compiled with wsloadcf to generate the
SALTCONFIG file binary.
GWWS server reads the
SALTCONFIG file at start up.The
SALTCONFIG environment variable must be set correctly with the
SALTCONFIG file entity before booting
GWWS servers.
Option “-c” is deprecated in the current version SALT. In SALT 1.1 release, option “
-c” is used to specify SALT 1.1 configuration file for the
GWWS server. In SALT 2.0,
GWWS server reads
SALTCONFIG file at start up.
GWWS server specified with this option can be booted with a warning message to indicate this deprecation. The specified file can be arbitrary and is not read by the
GWWS server.
When the GWWS server working in the outbound direction, external wsdl operations are mapped with Oracle Tuxedo services and advertised via the
GWWS servers. The number of the advertised services by all
GWWS servers must be accounted for in the
MAXSERVICES value.
The MAXACCESSERS value is used to specify the default maximum number of clients and servers that can be simultaneously connected to the Oracle Tuxedo bulletin board on any particular machine in this application. The number of
TMMETADATA and
GWWS server, maximum concurrent Web Service client requests must be accounted for in the
MAXACCESSERS value.
When the GWWS server operating in the inbound direction, each Web Service client is deemed a workstation client in the Oracle Tuxedo system; therefore,
MAXWSCLIENTS must be configured with a valid number in the
UBBCONFIG file for the machine where the
GWWS server is deployed. The number is shared.
When GWWS servers are specified with certificate-related features, they are required to read the private key file and decrypt it using the password phrase. To configure a password phrase for each
GWWS server, the keywords
SEC_PRINCIPAL_NAME and
SEC_PRINCIPAL_PASSVAR must be specified under each desired
GWWS server entry in the *
SERVERS section. During compiling the
UBBCONFIG file with
tmloadcf, the administrator must type the password phrase, which can be used to decrypt the private key file correctly.
Listing 33 shows a segment of the
UBBCONFIG file that defines a security password phrase for the
GWWS servers.
SALT GWWS servers rely on Oracle Tuxedo authentication framework to check the validity of the Web Service clients. If your existing Oracle Tuxedo application is already applied, Web Service clients must send user credentials using one of the following:
To obtain Oracle Tuxedo client uid/gid for outbound HTTP Basic Authentication
username /password mapping, you must configure the Oracle Tuxedo Security level as
USER_AUTH,
ACL or
MANDATORY_ACL in the
UBBCONFIG file.
Listing 34 shows a segment of the
UBBCONFIG file that defines security-level ACL in the
UBBCONFIG file.
To set up GWWS servers running on multiple machines within an MP mode Oracle Tuxedo domain, each Oracle Tuxedo machine must be defined with a separate
SALTDEPLOY file and a set of separate other components.
You may define two GWWS servers running on different machine with the same functionality by associating the same WSDF files. But it requires manual propagation of the following artifacts:
To run SALT 2.0 GWWS servers with SALT 1.1 configuration file, you must perform the following steps:
|
2.
|
Set the SALTCONFIG environment variable before booting the GWWS servers.
|
|
3.
|
Boot the GWWS servers associated with this SALT 1.1 configuration file.
|
When wsloadcf loads a binary
SALTCONFIG from a SALT 1.1 configuration file, it also converts this SALT 1.1 configuration file into one
WSDF file and one
SALTDEPLOY file.
Listing 35 shows the converted
SALTDEPLOY file and
WSDF file from a given SALT 1.1 configuration file.
The TMMETADATA server summarizes the collected data and generates a service contract. The contract information can either can be stored in the metadata repository, or output to a text file (which is then loaded to the metadata repository using
tmloadrepos). SALT uses the
tmscd command to control the service contract runtime collection. For more information, see
tmscd in the SALT
Command Reference Guide.
If the same autodiscovery pattern already exists in the metatdata repository, then the newer pattern is ignored.
If a service issues tpforward() instead of
tpreturn(), its reply buffer information is the same as the reply buffer of the service which it forwards to. For example:
The output complies with the format imposed by tmloadrepos if a file is used as storage instead of the metadata repository. The file contains a service header section and a parameter section for each parameter. Service header contains items listed in
Table 14. The "
service" field format is
<TuxedoServiceName>+'_'+<SequenceNo>. The suffix
<SequenceNo> is used to avoid name conflict when multiple patterns are recognized for an Oracle Tuxedo service.
|
Note:
|
<SequenceNo> starts from the last <SequenceNo> number already stored in the metadata repository.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
one way if TPNOREPLY is set.
|
|
|
|
FML, FML32, VIEW, VIEW32, STRING, CARRAY, XML, X_OCTET, X_COMMON, X_C_TYPE, MBSTRING or other arbitrary string representing an application defined custom buffer type.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
byte, short, integer, float, double, string, carray, dec_t, xml, ptr, fml32, view32, mbstring.
|
|
|
|
|
|
|
|
|
|
|
|
|
Input: service=SVC, request=STRING, reply = TPSUCCESS + STRING
Input: service=SVC, request=STRING, reply = TPFAIL+ STRING
Input: service=FMLS,request=FML32(name,pwd),reply=TPSUCCESS+FML32(id)
A TLOGName element is also added to allow sharing the same TLog device across GWWS instances.
Figure 2 illustrates the application and protocol flows of a typical WS-AT context service invocation.
The MaxTran element allows you to configure the size of the internal transaction table as shown in
Listing 1. The default is
MAXGTT.
|
Note:
|
The MaxTran value is optional. If the configured value is greater than MAXGTT, it is ignored and MAXGTT is used instead
|
The policy.xml file includes WS-AT policy elements. WS-AT defines the
ATAssertion element, with an
Optional attribute, as follows:
/wsat:ATAssertion/@wsp:Optional="true" as shown in
Listing 2.
|
Note:
|
In order to correctly import external WSDL files, the wsdlcvt command is modified to generate a policy.xml file containing the ATAssertion element when one is present in the WSDL. For outbound requests, a policy.xml file containing an ATAssertion element must be created and properly pointed to in the SALTDEPLOY source.
|
|
•
|
When an ATAssertion with no "Optional=true" is configured, the call must be made in a transaction. If no corresponding XA transaction exists, the WS-TX transaction is initiated but not associated with any Oracle Tuxedo XA transaction. If an XA transaction exists, there is no change in behavior.
|
|
•
|
When an ATAssertion with "Optional=true" is configured, an outbound transaction context is requested only if a corresponding Oracle Tuxedo XA transaction exists in the context of the call.
|
|
•
|
When no ATAssertion is configured for this service, the corresponding service call is made outside of any transaction. If a call is made to an external Web service in the context of an Oracle Tuxedo XA transaction, the Web service call will not propagate the transaction.
|
For outbound requests, the WSDL conversion tool, wsdlcvt, generates a
policy.xml file containing the
ATAssertion element when one is present in the processed WSDL.You must properly configure the location of the
policy.xml file in the
SALTDEPLOY source.
The wsdlcvt command adds the capability of generating a COBOL copybook based on the structure of the schema contained in the imported WSDL.
In this mode, wsdlcvt also generate
servicetype=sna (as opposed to webservice), so that the corresponding Tuxedo service can be invoked by GWSNAX. The service maps to an external web service and functions the same as
servicetype=webservice.
The wscobolcvt command converts COBOL copybook to service metadata (MIF) with record type buffers. It parses COBOL and generates service metadata in the MIF format as shown in
Figure 3.
|
1.
|
wscobolcvt takes the COBOL source and the following additional information as arguments:
|
|
2.
|
wscobolcvt generates service metadata and WSDF file.
|
|
3.
|
Optionally, wscobolcvt automatically configures DMCONFIG file entries with domain IDs and CRM address as shown in Listing 1
|
|
•
|
the wsdf file is not required.
|
The wsdlcvt command is used to generate COBOL copybook from WSDL/schema. Outbound services are invoked using
RECORD payloads and are automatically detected and converted using GWWS.
You can invoke wsdlcvt using the
-C argument to generate MIF with
RECORD type definitions,
WSDF,
XSD,
RECORD files and COBOL copybook source files.
wsdlcvt has the
-D option to specify a string length to use when
xsd:string types are not constrained by size. Otherwise the default for strings is
256(PIC X(256)).
