Web Service Client Programming

This section contains the following topics:

•

Overview

•	Oracle SALT Web Service Client Programming Tips

•	Web Service Client Programming References

Overview

Oracle 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, Oracle SALT used in conjunction with the Oracle Tuxedo framework is a standard Web service provider. You only need to use the Oracle 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 Oracle SALT WSDL file. For more information, see Configuring Oracle SALT in the Oracle SALT Administration Guide.

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

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

4.	Compile and run your client application.

Oracle SALT Web Service Client Programming Tips

This section provides some useful client-side programming tips for developing Web service client programs using the following Oracle 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 Oracle 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 Oracle 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 program and server instances. For more information, see http://edocs.bea.com/wls/docs91/webserv/client.html#standalone_invoke.

Besides traditional synchronous message exchange mode, Oracle 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. Oracle 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

Oracle 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. Oracle 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. Oracle SALT does not support multiple-reference format. You can disable AXIS multiple-reference format as shown in Listing 3‑1:

Listing 3‑1 Disabling AXIS Multiple-Reference Format

TuxedoWebServiceLocator service = new TuxedoWebServiceLocator();
service.getEngine().setOption("sendMultiRefs", false);¦

Tip:

3. Use Apache Sandensha project with Oracle SALT for WS-ReliableMessaging communication. Interoperability was tested for WS-ReliableMessaging between Oracle 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‑2:

Listing 3‑2 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 Oracle 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 Oracle 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. Oracle 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 Oracle SALT WSDL document is generated using RPC/encoded style, .Net sends out SOAP messages containing soapenc:arrayType. Oracle SALT does not support soapenc:arrayType using RPC/encoded style. A sample RPC/encoded style-generated WSDL document is shown in Listing 3‑3.

Listing 3‑3 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 Oracle SALT WSDL document in RPC/encoded style, wsdl.exe can generate stub code, but 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

Invoking a Web service from a Stand-alone Client: Main Steps

•	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