11 Consuming Web Services in J2EE Applications

11.1.3.1 RPC and Document Style with Simple Types Example

This example uses a simple WSDL document that shows a couple of operations: Add and Multiply. Add is using the document-style operation using literal parts, while Multiply is RPC-style and uses encoded parts.

To generate the EJB stub, use the following command:

On UNIX
cd $ORACLE_HOME/webservices/demo/basic/wsdl2ejb
java -jar ../../../lib/wsdl2ejb.jar -conf rpc_doc/rpc_doc_conf.xml

On Windows
cd %ORACLE_HOME%\webservices\demo\basic\wsdl2ejb
java -jar ..\..\..\lib\wsdl2ejb.jar -conf rpc_doc\rpc_doc_conf.xml

The utility generates the TestApp.ear file containing the definition of a stateless EJB, which can be used as a proxy for the Web Service. The EAR file can be deployed in OC4J as any standard EJB. Refer to Oracle Application Server Containers for J2EE User's Guide for information on how to deploy an EJB.

By looking at the generated EJB Remote Interface, you can see how the WSDL portType DocAndRpc.wsdl file has been mapped to Java.

WSDL PortType:

  <types>
    <s:schema elementFormDefault="qualified" targetNamespace="http://soapinterop.org">
      <s:element name="Add">
        <s:complexType>
          <s:sequence>
            <s:element minOccurs="1" maxOccurs="1" name="a" type="s:int" />
            <s:element minOccurs="1" maxOccurs="1" name="b" type="s:int" />
          </s:sequence>
        </s:complexType>
      </s:element>
      <s:element name="AddResponse">
        <s:complexType>
          <s:sequence>
            <s:element minOccurs="1" maxOccurs="1" name="AddResult" type="s:int" />
          </s:sequence>
        </s:complexType>
      </s:element>
    </s:schema>
  </types>
  <message name="AddSoapIn">
    <part name="parameters" element="s0:Add" /> 
  </message>
  <message name="AddSoapOut">
    <part name="parameters" element="s0:AddResponse" /> 
  </message>
  <message name="MultiplySoapIn">
    <part name="a" type="xsd:int" /> 
    <part name="b" type="xsd:int" /> 
  </message>
  <message name="MultiplySoapOut">
    <part name="MultiplyResult" type="s:int" /> 
  </message>
  <portType name="TestSoap">
    <operation name="Add">
      <input message="s0:AddSoapIn" /> 
      <output message="s0:AddSoapOut" /> 
    </operation>
    <operation name="Multiply">
      <input message="s0:MultiplySoapIn" /> 
      <output message="s0:MultiplySoapOut" /> 
    </operation>
  </portType>

From the Test.java file, the EJB Remote Interface is:

  public org.w3c.dom.Element add(org.w3c.dom.Element parameters)
    throws RemoteException;
 
  public int multiply(int a, int b)
    throws RemoteException;

When the WSDL operation is using RPC style and its parts are encoded, the parts XML schema type is mapped to a corresponding Java native type. In this example, xsd:int is mapped to Java int. In a document style using literal parts, each part is simply mapped to an org.w3c.dom.Element.

The following client code in the TestRpcDocClient.java file can be used to invoke the Add and Multiply Web Service operations. The code has been produced by modifying the client code stub generated by the wsdl2ejb utility.

import java.io.*;
import java.util.*;
import javax.naming.*;

import org.w3c.dom.*;
import oracle.xml.parser.v2.*;

import org.mssoapinterop.asmx.Test;
import org.mssoapinterop.asmx.TestHome;


/**
 * This is a simple client template. To compile it, 
 * please include the generated EJB jar file as well as
 * EJB and JNDI libraries in classpath.
 */
public class TestRpcDocClient
{
  // replace the values
  private static String RMI_HOST  = "localhost";
  private static String RMI_PORT  = "23791";
  private static String RMI_ADMIN = "admin";
  private static String RMI_PWD   = "welcome";

  public TestRpcDocClient () {}

  public static void main(String args[]) {

    TestRpcDocClient client = new TestRpcDocClient();

    try {

      RMI_HOST  = args[0];
      RMI_PORT  = args[1];
      RMI_ADMIN = args[2];
      RMI_PWD   = args[3];

      Hashtable env = new Hashtable();
      env.put(Context.INITIAL_CONTEXT_FACTORY, "com.evermind.server.rmi.RMIInitialContextFactory");
      env.put(Context.SECURITY_PRINCIPAL, RMI_ADMIN);
      env.put(Context.SECURITY_CREDENTIALS, RMI_PWD);
      env.put(Context.PROVIDER_URL, "ormi://" + RMI_HOST + ":" + RMI_PORT + "/Wsdl2EjbTestApp1");
      Context ctx = new InitialContext(env);
      TestHome home = (TestHome) ctx.lookup("mssoapinterop.org/asmx/DocAndRpc.asmx");
      
      Test service = home.create();
      
      // call any of the Remote methods that follow to access the EJB
      
      //
      // Add test
      //
      Document  doc = new XMLDocument();
      Element elAdd = doc.createElementNS("http://soapinterop.org", "s:Add");
      Element   elA = doc.createElementNS("http://soapinterop.org", "s:a");
      Element   elB = doc.createElementNS("http://soapinterop.org", "s:b");
      elA.appendChild(doc.createTextNode("4"));
      elB.appendChild(doc.createTextNode("3"));
      elAdd.appendChild(elA);
      elAdd.appendChild(elB);
      doc.appendChild(elAdd);
      
      Element elAddResponse = service.add(elAdd);
      Node tNode = elAddResponse.getFirstChild().getFirstChild();
      System.out.println("AddResponse: "+tNode.getNodeValue());

      //
      // Multiply Test
      //
      int a = 4;
      int b = 3;
      int iMultiplyResponse = service.multiply(a, b);
      System.out.println("MultiplyResponse: "+iMultiplyResponse);
      
      
    } 
    catch (Throwable ex) {
      ex.printStackTrace();
    }
  }
} 

The result of the execution of the client is the following:

AddResponse: 7
MultiplyResponse: 12

11.1.3.2 Round 2 Interop Services: Base Test Suite Example

This example starts from a subset of the WSDL document defined by the base test suite of the second round of SOAP interoperability tests. The purpose of this demo example is to show the usage of built-in types in the SOAP Mapping Registry as well as how to add custom types mapping.

Start by looking at the WSDL portType in the InteropTest.wsdl file.

<types>
   <schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="http://soapinterop.org/xsd">
      <complexType name="ArrayOfstring">
         <complexContent>
            <restriction base="SOAP-ENC:Array">
               <attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="string[]"/>
            </restriction>
         </complexContent>
       </complexType>
       <complexType name="ArrayOfint">
          <complexContent>
            <restriction base="SOAP-ENC:Array">
               <attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="int[]"/>
            </restriction>
          </complexContent>
       </complexType>
       <complexType name="ArrayOffloat">
          <complexContent>
             <restriction base="SOAP-ENC:Array">
                <attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="float[]"/>
             </restriction>
          </complexContent>
       </complexType>
       <complexType name="ArrayOfSOAPStruct">
          <complexContent>
             <restriction base="SOAP-ENC:Array">
                <attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="s:SOAPStruct[]"/>
             </restriction>
         </complexContent>
      </complexType>
      <complexType name="SOAPStruct">
            <all>
                <element name="varString" type="string"/>
                <element name="varInt" type="int"/>
                <element name="varFloat" type="float"/>
            </all>
      </complexType>
   </schema>
</types>

<message name="echoStringRequest">
   <part name="inputString" type="xsd:string"/>
</message>
<message name="echoStringResponse">
   <part name="return" type="xsd:string"/>
</message>
<message name="echoStringArrayRequest">
   <part name="inputStringArray" type="s:ArrayOfstring"/>
</message>
<message name="echoStringArrayResponse">
   <part name="return" type="s:ArrayOfstring"/>
</message>
<message name="echoIntegerRequest">
   <part name="inputInteger" type="xsd:int"/>
</message>
<message name="echoIntegerResponse">
   <part name="return" type="xsd:int"/>
</message>
<message name="echoIntegerArrayRequest">
   <part name="inputIntegerArray" type="s:ArrayOfint"/>
</message>
<message name="echoIntegerArrayResponse">
   <part name="return" type="s:ArrayOfint"/>
</message>
<message name="echoFloatRequest">
   <part name="inputFloat" type="xsd:float"/>
</message>
<message name="echoFloatResponse">
   <part name="return" type="xsd:float"/>
</message>
<message name="echoFloatArrayRequest">
   <part name="inputFloatArray" type="s:ArrayOffloat"/>
</message>
<message name="echoFloatArrayResponse">
   <part name="return" type="s:ArrayOffloat"/>
</message>
<message name="echoStructRequest">
   <part name="inputStruct" type="s:SOAPStruct"/>
</message>
<message name="echoStructResponse">
   <part name="return" type="s:SOAPStruct"/>
</message>
<message name="echoStructArrayRequest">
   <part name="inputStructArray" type="s:ArrayOfSOAPStruct"/>
</message>
<message name="echoStructArrayResponse">
   <part name="return" type="s:ArrayOfSOAPStruct"/>
</message>
<message name="echoVoidRequest"/>
<message name="echoVoidResponse"/>
<message name="echoBase64Request">
   <part name="inputBase64" type="xsd:base64Binary"/>
</message>
<message name="echoBase64Response">
   <part name="return" type="xsd:base64Binary"/>
</message>
<message name="echoDateRequest">
   <part name="inputDate" type="xsd:dateTime"/>
</message>
<message name="echoDateResponse">
   <part name="return" type="xsd:dateTime"/>
</message>
<message name="echoDecimalRequest">
   <part name="inputDecimal" type="xsd:decimal"/>
</message>
<message name="echoDecimalResponse">
   <part name="return" type="xsd:decimal"/>
</message>
<message name="echoBooleanRequest">
   <part name="inputBoolean" type="xsd:boolean"/>
</message>
<message name="echoBooleanResponse">
   <part name="return" type="xsd:boolean"/>
</message>

<portType name="InteropTestPortType">
   <operation name="echoString" parameterOrder="inputString">
      <input message="tns:echoStringRequest"/>
      <output message="tns:echoStringResponse"/>
   </operation>
   <operation name="echoStringArray" parameterOrder="inputStringArray">
      <input message="tns:echoStringArrayRequest"/>
      <output message="tns:echoStringArrayResponse"/>
   </operation>
   <operation name="echoInteger" parameterOrder="inputInteger">
      <input message="tns:echoIntegerRequest"/>
      <output message="tns:echoIntegerResponse"/>
   </operation>
   <operation name="echoIntegerArray" parameterOrder="inputIntegerArray">
      <input message="tns:echoIntegerArrayRequest"/>
   <output message="tns:echoIntegerArrayResponse"/>
   </operation>
   <operation name="echoFloat" parameterOrder="inputFloat">
      <input message="tns:echoFloatRequest"/>
   <output message="tns:echoFloatResponse"/>
   </operation>
   <operation name="echoFloatArray" parameterOrder="inputFloatArray">
      <input message="tns:echoFloatArrayRequest"/>
      <output message="tns:echoFloatArrayResponse"/>
   </operation>
   <operation name="echoStruct" parameterOrder="inputStruct">
      <input message="tns:echoStructRequest"/>
      <output message="tns:echoStructResponse"/>
   </operation>
   <operation name="echoStructArray" parameterOrder="inputStructArray">
      <input message="tns:echoStructArrayRequest"/>
      <output message="tns:echoStructArrayResponse"/>
   </operation>
   <operation name="echoVoid">
      <input message="tns:echoVoidRequest"/>
      <output message="tns:echoVoidResponse"/>
   </operation>
   <operation name="echoBase64" parameterOrder="inputBase64">
      <input message="tns:echoBase64Request"/>
      <output message="tns:echoBase64Response"/>
   </operation>
   <operation name="echoDate" parameterOrder="inputDate">
      <input message="tns:echoDateRequest"/>
      <output message="tns:echoDateResponse"/>
   </operation>
   <operation name="echoDecimal" parameterOrder="inputDecimal">
      <input message="tns:echoDecimalRequest"/>
      <output message="tns:echoDecimalResponse"/>
   </operation>
   <operation name="echoBoolean" parameterOrder="inputBoolean">
      <input message="tns:echoBooleanRequest"/>
      <output message="tns:echoBooleanResponse"/>
   </operation>
</portType>

Notice that the WSDL document contains more complex types than the previous demo. Array of primitives types are now used as well as the struct primitive types. With the exception of the SOAPStruct complex type, every other type is supported as built-in type in the SOAP Mapping Registry. You then need to add a new complex type definition to the SOAP Mapping Registry to handle the SOAPStruct complex type.

The SOAPStruct schema definition is the following:

<complexType name="SOAPStruct">
      <all>
            <element name="varString" type="string"/>
            <element name="varInt" type="int"/>
            <element name="varFloat" type="float"/>
      </all>
</complexType>

In the MySoapStructBean.java file, this SOAPStruct complex type can be mapped to a simple JavaBean class such as the following, and have the marshalling and unmarshalling actions handled by the BeanSerializer.

public class MySoapStructBean implements java.io.Serializable 
{
  private String m_varString = null;
  private int m_varInt = 0;
  private float m_varFloat = 0;

  public MySoapStructBean() {}
  public MySoapStructBean(String s, int i, float f) {
    m_varString = s;
    m_varInt    = i;
    m_varFloat  = f;
  }

  public String getVarString () { return m_varString; }
  public int getVarInt() { return m_varInt; }
  public float getVarFloat() { return m_varFloat; }

  public void setVarString (String s) { m_varString = s; }
  public void setVarInt(int i) { m_varInt = i; }
  public void setVarFloat(float f) { m_varFloat = f; }
}

With the mapping JavaBean class ready, and having identified what serializer and deserializer to use, you can now configure the wsdl2ejb utility so that a new schema to Java map is added. This can be achieved by adding the following to the wsdl2ejb configuration file, base_conf.xml:

<mapTypes jar="base/MySoapStructBean.jar" >
  <map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
       local-name="SOAPStruct"
       namespace-uri="http://soapinterop.org/xsd"
       java-type="MySoapStructBean"
       java2xml-class-name="org.apache.soap.encoding.soapenc.BeanSerializer"
       xml2java-class-name="org.apache.soap.encoding.soapenc.BeanSerializer" />
</mapTypes>

The MySoapStructBean.jar file contains the definition of the MySoapStructBean class. With this map, the SOAPStruct complex type, belonging to the http://soapinterop.org/xsd namespace, will be mapped to the MySoapStructBean JavaBean class and the converse is true as well. For more information about SOAP serializers and deserializers, see the Oracle SOAP documentation.

With this additional configuration, you can now run the wsdl2ejb utility with the following command:

On UNIX
cd $ORACLE_HOME/webservices/demo/basic/wsdl2ejb
java -jar ../../../lib/wsdl2ejb.jar -conf base/base_conf.xml
On Windows
cd %ORACLE_HOME%/webservices/demo/basic/wsdl2ejb
java -jar ..\..\..\lib\wsdl2ejb.jar -conf base\base_conf.xml

The wsdl2ejb utility generates the InteropLabApp.ear file that contains the definition of a stateless EJB, which can be used as a proxy for the Web Service. The EAR file can be deployed in OC4J as any standard EJB. See Oracle Application Server Containers for J2EE User's Guide for information on how to deploy an EJB.

The TestInteropBaseClient.java class file, saved in the base directory, can be used to test the generated EJB after it has been deployed. The result of the execution of the client is the following:

echoString: Hello World!
echoStringArray[0]: Hello World!
echoStringArray[1]: Seems to work!
echoStringArray[2]: Fine!
echoStringArray[3]: WOW
echoInteger: 7
echoIntegerArray[0]: 1
echoIntegerArray[1]: 2
echoIntegerArray[2]: 3
echoIntegerArray[3]: 4
echoFloat: 1.7777
echoFloatArray[0]: 1.1
echoFloatArray[1]: 1.2
echoFloatArray[2]: 1.3
echoFloatArray[3]: 1.4
echoStruct: varString=Hello World , varInt=1 , varFloat=1.777
echoStructArray: varString[0]=Hello World , varInt[0]=0 , varFloat=[0]=1.7771
echoStructArray: varString[1]=Hello World 1 , varInt[1]=1 , varFloat=[1]=1.7772
echoStructArray: varString[2]=Hello World 2 , varInt[2]=2 , varFloat=[2]=1.7773
echoStructArray: varString[3]=Hello World 3 , varInt[3]=3 , varFloat=[3]=1.7774
echoVoid.
echoDecimal: 1.77709999999999990194510246510617434978485107421875
echoBoolean: true
echoBase64[0]: 1
echoBase64[1]: 2
echoBase64[2]: 3
echoBase64[3]: 4
echoDate: Sat Nov 10 12:30:00 EST 2001