Table of Contents Previous Next PDF

Web Service Client Programming

Web Service Client Programming
This chapter contains the following topics:
SALT is a configuration-driven product that publishes existing Oracle Tuxedo application services as industry-standard Web services. From a Web services client-side programming perspective, SALT (used in conjunction with the Oracle Tuxedo framework), is a standard Web service provider. You only need to use the SALT WSDL file to develop a Web service client program.
To develop a Web service client program, do the following steps:
REpresentational State Transfer (REST) Support
With REST enabled, requests received on a REST port are processed as follows by GWWS.
URIs must comply with the following pattern:
<REST service name>
Where the Oracle Tuxedo service name is the name of the REST service invoked (for example, TOUPPER).
Data format and input Oracle Tuxedo buffer types are specified using the following HTTP header:
Set to application/json:indicates that JSON is used to transfer data to/from HTTP client.
Set to application/xml:indicates that XML is used to transfer data to/from HTTP client.
application/json and application/xml will only apply to structured buffer types (VIEW, VIEW32, FML, FML32, X_C_TYPE and X_COMMON. To use simple buffers and POST or PUT, you must set Content-type to appropriate values ("text/plain" for STRING, "application/octet-stream" for CARRAY, etc.).
Oneway (in and out)
If no data is input, the Oracle Tuxedo service is invoked with a NULL Oracle Tuxedo buffer. Similarly, if the Oracle Tuxedo service does not return any data, the response also contains no data (which is a valid use-case).
ATMI and SCA Support
There is no restriction in the type of Oracle Tuxedo service being exposed as REST (whether ATMI or SCA). To use SCA components, you must conform to SCA data mapping conventions as found in SCA Data Type Mapping. Name mapping may apply, as outlined in SCA and Oracle Tuxedo Interoperability.
Example 1: .h interface
Listing 3‑1 .h interface
#include <string>
* Tuxedo service business interface
class TuxService
virtual std::string TOUPPER(const std::string inputString) = 0;
Example 2: SCDL Descriptor
Listing 3‑2 SCDL Descriptor
<composite xmlns="" name="myComponent">
<service name="TuxService">
<interface.cpp header="TuxService.h"/>
<component name="MYComponent">
<implementation.cpp library="TuxService" header="TuxServiceImpl.h"/>
Example 3: SALTDEPLOY REST Service Definition
Listing 3‑3 SALTDEPLOY REST Service Definition
<Network http="myhost:1234"/>
<Service name="testSCA">
<Method name="GET"
Example 4: URL used to invoke service
Example 5: Response
HTTP/1.1 200 OK
Content-Type: text/xmlTESTSTRING
SALT Web Service Client Programming Tips
This section provides some useful client-side programming tips for developing Web service client programs using the following SALT-tested programming toolkits:
For more information, see Interoperability Considerations in the SALT Administration Guide.
The sample directories for the listed toolkits can be found after SALT is installed.
Oracle WebLogic Web Service Client Programming Toolkit
WebLogic Server provides the clientgen utility which is a built-in application server component used to develop Web service client-side java programs. The invocation can be issued from standalone java programs and server instances. For more information, see Developing JAX-WS Web Services for Oracle WebLogic Server.
Besides traditional synchronous message exchange mode, SALT also supports asynchronous and reliable Web service invocation using WebLogic Server. Asynchronous communication is defined by the WS-Addressing specification. Reliable message exchange conforms to the WS-ReliableMessaging specification.
Use the WebLogic specific WSDL document for HTTP MIME attachment support.

SALT can map Oracle Tuxedo
CARRAY data to SOAP request MIME attachments. This is beneficial when the binary data stream is large since MIME binding does not need additional encoding wrapping. This can help save CPU cycles and network bandwidth.

Another consideration, in an enterprise service oriented environment is that binary data might be used to guide high-level data routing and transformation work. Encoded data can be problematic. To enable the MIME data binding for Oracle Tuxedo CARRAY data, a special flag must be specified in the WSDL document generation options (both for online downloading and using the tmwsdlgen command utility).

Online Download:

tmwsdlgen Utility
tmwsdlgen -c WSDF_FILE -m raw -t wls
Apache Axis for Java Web Service Client Programming Toolkit
SALT supports the AXIS wsdl2java utility which generates java stub code from the WSDL document. The AXIS Web service programming model is similar to WebLogic.
1. Use the AXIS specific WSDL document for HTTP MIME attachment support.

SALT supports HTTP MIME transportation for Oracle Tuxedo CARRAY data. A special option must be specified for WSDL online downloading and the tmwsdlgen utility.

Online Download:

tmwsdlgen Utility
tmwsdlgen -c WSDF_FILE -m raw -t axis
2. Disable multiple-reference format in AXIS when RPC/encoded style is used.

AXIS may send a multi-reference format SOAP message when RPC/encoded style is specified for the WSDL document. SALT does not support multiple-reference format. You can disable AXIS multiple-reference format as shown in Listing 3‑4:
Listing 3‑4 Disabling AXIS Multiple-Reference Format
TuxedoWebServiceLocator service = new TuxedoWebServiceLocator();
service.getEngine().setOption("sendMultiRefs", false);
3. Use Apache Sandensha project with SALT for WS-ReliableMessaging communication.

Interoperability has been tested for WS-ReliableMessaging between SALT and the Apache Sandensha project. The Sandensha asynchronous mode and send offer must be set in the code.

A sample Apache Sandensha asynchronous mode and send offer code example is shown in Listing 3‑5:
Listing 3‑5 Sample Apache Sandensha Asynchronous Mode and “send offer” Code Example
/* Call the service */
           TuxedoWebService service = new TuxedoWebServiceLocator();

       Call call = (Call) service.createCall();
           SandeshaContext ctx = new SandeshaContext();

           ctx.setAcksToURL("" + defaultClientPort + "/axis/services/RMService");
       ctx.setReplyToURL("" + defaultClientPort + "/axis/services/RMService");
       ctx.initCall(call, targetURL, "urn:wsrm:simpapp", Constants.ClientProperties.IN_OUT);

       call.setOperationName(new javax.xml.namespace.QName("urn:pack.simpappsimpapp_typedef.salt11", "ToUpperWS"));
       call.addParameter("inbuf", XMLType.XSD_STRING, ParameterMode.IN);

           String input = new String();
           String output = new String();
       int i;
           for (i = 0; i < 3; i++ ) {
                      input = "request" + "_" + String.valueOf(i);

                   output = (String) call.invoke(new Object[]{input});
                   System.out.println("Reply:" + output);

       input = "request" + "_" + String.valueOf(i);
           output = (String) call.invoke(new Object[]{input});
Microsoft .NET Web Service Client Programming Toolkit
Microsoft .Net 1.1/2.0 provides wsdl.exe in the .Net SDK package. It is a free development Microsoft toolkit. In the SALT simpapp sample, a .Net program is provided in the simpapp/dnetclient directory.
.Net Web service programming is easy and straightforward. Use the wsdl.exe utility and the SALT WSDL document to generate the stub code, and then reference the .Net object contained in the stub code/binary in business logic implementations.
1. Do not use .Net program MIME attachment binding for CARRAY.

Microsoft does not support SOAP communication MIME binding. Avoid using the WSDL document with MIME binding for CARRAY in .Net development.

SALT supports base64Binary encoding for CARRAY data (the default WSDL document generation.)
2. Some RPC/encoded style SOAP messages are not understood by the GWWS server.

When the SALT WSDL document is generated using RPC/encoded style, .Net sends out SOAP messages containing soapenc:arrayType. SALT does not support soapenc:arrayType using RPC/encoded style. A sample RPC/encoded style-generated WSDL document is shown in Listing 3‑6.
Listing 3‑6 Sample RPC/encoded Style-Generated WSDL Document
                     <xsd:schema attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="urn:pack.TuxAll_typedef.salt11">
                            <xsd:complexType name="fml_TFML_In">
                                          <xsd:element maxOccurs="60" minOccurs="60" name="tflong" type="xsd:long"></xsd:element>
                                          <xsd:element maxOccurs="80" minOccurs="80" name="tffloat" type="xsd:float"></xsd:element>
                            <xsd:complexType name="fml_TFML_Out">
Workaround: Use Document/literal encoded style for .Net client as recommended by Microsoft.
3. Error message regarding xsd:base64Binary in RPC/encoded style.

If xsd:base64Binary is used in the SALT WSDL document using RPC/encoded style, wsdl.exe can generate stub code;however, the client program might report a runtime error as follows:

is an invalid value for the SoapElementAttribute.DataType property. The property may only be specified for primitive types.
Workaround: This is a .Net framework issue.
Use Document/literal encoded style for .Net client as recommended by Microsoft.
Web Service Client Programming References
Online References
Oracle WebLogic 10.0 Documentation
Consuming Web Services with Axis
Using WSDL with Axis
Building Web Services

Copyright © 1994, 2017, Oracle and/or its affiliates. All rights reserved.