Web Service Client Programming

This chapter contains the following topics:

•

Overview

•	SALT Web Service Client Programming Tips

•	Web Service Client Programming References

Overview

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:

1.	Generate or download the SALT WSDL file. For more information, see Configuring SALT.

2.	Use a Web service client-side toolkit to parse the SALT WSDL document, and generate client stub code. For more information, see SALT Web Service Client Programming Tips.

3.	Write client-side application code to invoke a SALT Web service using the functions defined in the client-generated stub code.

4.	Compile and run your client application.

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:

•	content-type:

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.

Note:

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.

Examples

Example 1: .h interface

Listing 3‑1 .h interface

#include <string>

/**

* Tuxedo service business interface

*/

class TuxService

{

public:

virtual std::string TOUPPER(const std::string inputString) = 0;

};

 

Example 2: SCDL Descriptor

Listing 3‑2 SCDL Descriptor

<composite xmlns="http://www.osoa.org/xmlns/sca/1.0" name="myComponent">

<service name="TuxService">

<interface.cpp header="TuxService.h"/>

<binding.atmi/>

<inputBufferType>STRING</inputBufferType>

<outputBufferType>STRING</outputBufferType>

<reference>MYComponent</reference>

</service>

 

<component name="MYComponent">

<implementation.cpp library="TuxService" header="TuxServiceImpl.h"/>

</component>

</composite>

 

Example 3: SALTDEPLOY REST Service Definition

Listing 3‑3 SALTDEPLOY REST Service Definition

<REST>

<Network http="myhost:1234"/>

<Service name="testSCA">

<Method name="GET"

reposservice=""

service="TuxService/TOUPPER"

inputbuffer="STRING"/>

</Service>

...

</REST>

 

Example 4: URL used to invoke service

http://myhost:1234/testSCA?teststring

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:

•	Oracle WebLogic Web Service Client Programming Toolkit

•	Apache Axis for Java Web Service Client Programming Toolkit

•	Microsoft .NET Web Service Client Programming Toolkit

For more information, see Interoperability Considerations in the SALT Administration Guide.

Notes:

You can use any SOAP toolkit to develop client software.

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.

Tip:

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: http://salt.host:portnumber//wsdl?mappolicy=raw&toolkit=wls 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.

Tip:

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: http://salt.host:portnumber//wsdl?mappolicy=raw&toolkit=axis tmwsdlgen Utility tmwsdlgen -c WSDF_FILE -m raw -t axis

Tip:

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);¦

Tip:

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("http://127.0.0.1:" + defaultClientPort + "/axis/services/RMService");
       ctx.setReplyToURL("http://127.0.0.1:" + defaultClientPort + "/axis/services/RMService");
       ctx.setSendOffer(true);
       ctx.initCall(call, targetURL, "urn:wsrm:simpapp", Constants.ClientProperties.IN_OUT);

       call.setUseSOAPAction(true);
       call.setSOAPActionURI("ToUpperWS");
       call.setOperationName(new javax.xml.namespace.QName("urn:pack.simpappsimpapp_typedef.salt11", "ToUpperWS"));
       call.addParameter("inbuf", XMLType.XSD_STRING, ParameterMode.IN);
       call.setReturnType(org.apache.axis.encoding.XMLType.XSD_STRING);

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

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

            }

ctx.setLastMessage(call);
       input = "request" + "_" + String.valueOf(i);
       System.out.println("Request:"+input);
           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.

Tip:	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.)

Tip:

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

<wsdl:types>

                     <xsd:schema attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="urn:pack.TuxAll_typedef.salt11">
                            <xsd:complexType name="fml_TFML_In">
                                   <xsd:sequence>
                                          <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:sequence>
                            </xsd:complexType>
                            <xsd:complexType name="fml_TFML_Out">
                                   …

</xsd:complexType>

                     </xsd:schema>

              </wsdl:types>

 

Workaround: Use Document/literal encoded style for .Net client as recommended by Microsoft.

Tip:

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: System.InvalidOperationException:'base64Binary' 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 Web Service Client Programming References

Oracle WebLogic 10.0 Documentation

•	Apache Axis 1.3 Web Service Client Programming References

Consuming Web Services with Axis

Using WSDL with Axis

•	Microsoft .NET Web Service Programming References

Building Web Services