To see how these tests work, we need an Internet connection. Let’s run the Apache SOAP 2.2 EchoTestClient against the Iona XMLBus echo test service, which Iona has hosted as part of their participation in the SB Round 2 effort:

java samples.interop.EchoTestClient http://interop.xmlbus.com:7002/xmlbus/container/
InteropTest/BaseService/BasePort

The command must be typed on a single line. If you use the EchoTestClient straight from the Apache SOAP distribution, you should see the following errors as output:

echoInteger generated fault:
  Fault Code   = SOAP-ENV:Server
  Fault String = xsi:type doesn't match.  Expected http://www.w3.org/2001/
XMLSchema:int but found http://www.w3.org/1999/XMLSchema:int
echoFloat generated fault:
  Fault Code   = SOAP-ENV:Server
  Fault String = xsi:type doesn't match.  Expected http://www.w3.org/2001/
XMLSchema:float but found http://www.w3.org/1999/XMLSchema:float
soapAction: http://soapinterop.org/
echoString generated fault:
  Fault Code   = SOAP-ENV:Server
  Fault String = xsi:type doesn't match.  Expected http://www.w3.org/2001/
XMLSchema:string but found http://www.w3.org/1999/XMLSchema:string
soapAction: http://soapinterop.org/
...

This result illustrates one of the most basic interoperability problems. The receiving service expected the schema definition http://www.w3.org/2001/XMLSchema, but the sending client generated a SOAP envelope based on http://www.w3.org/1999/XMLSchema. We will show how simple it is to fix this problem in a moment, when we get to the code. In the meantime, when the EchoTestClient works correctly, its output looks like this:

echoInteger      OK
echoFloat        OK
echoString       OK
echoStruct       OK
echoIntegerArray OK
echoFloatArray   OK
echoStringArray  OK
echoStructArray  OK

This test may look simple, but quite a bit is going on internally. At the highest level, this test makes eight RPC calls,^[15] each with its own unique datatype as a parameter. The receiving method simply takes that parameter and returns it as the method’s return value. The sending client then compares the returned data with the sent data to verify that it is the same. If the data are equal, we know that:

The next exercise directs the EchoTestClient at our simple servlet from Chapter 3:

java samples.interop.EchoTestClient http://localhost:8080/examples/servlet/
SimpleHTTPReceive

You will see several errors in the sending client’s console because the simple servlet is not set up to accommodate RPC calls—but that’s not important for this discussion. What’s important is that you should see the following output in the Tomcat console window. The raw SOAP envelopes that were generated by the EchoTestClient are shown here:

____________________________
Received request.
-----------------------
  SOAPAction = "http://soapinterop.org/"
  Host = localhost
  Content-Type = text/xml; charset=utf-8
  Content-Length = 469
-----------------------
<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body>
<ns1:echoInteger xmlns:ns1="http://soapinterop.org/" 
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<inputInteger xsi:type="xsd:int">5</inputInteger>
</ns1:echoInteger>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
____________________________
____________________________
Received request.
-----------------------
  SOAPAction = "http://soapinterop.org/"
  Host = localhost
  Content-Type = text/xml; charset=utf-8
  Content-Length = 466
-----------------------
<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body>
<ns1:echoFloat xmlns:ns1="http://soapinterop.org/" 
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<inputFloat xsi:type="xsd:float">55.5</inputFloat>
</ns1:echoFloat>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
____________________________
____________________________
Received request.
-----------------------
  SOAPAction = "http://soapinterop.org/"
  Host = localhost
  Content-Type = text/xml; charset=utf-8
  Content-Length = 476
-----------------------
<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body>
<ns1:echoString xmlns:ns1="http://soapinterop.org/" 
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<inputString xsi:type="xsd:string">Hi there!</inputString>
</ns1:echoString>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
____________________________
____________________________
Received request.
-----------------------
  SOAPAction = "http://soapinterop.org/"
  Host = localhost
  Content-Type = text/xml; charset=utf-8
  Content-Length = 656
-----------------------
<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body>
<ns1:echoStruct xmlns:ns1="http://soapinterop.org/" 
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<inputStruct xmlns:ns2="http://soapinterop.org/xsd" xsi:type="ns2:SOAPStruct">
<varInt xsi:type="xsd:int">5</varInt>
<varFloat xsi:type="xsd:float">10.0</varFloat>
<varString xsi:type="xsd:string">Hola, baby</varString>
</inputStruct>
</ns1:echoStruct>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
____________________________
____________________________
Received request.
-----------------------
  SOAPAction = "http://soapinterop.org/"
  Host = localhost
  Content-Type = text/xml; charset=utf-8
  Content-Length = 748
-----------------------
<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body>
<ns1:echoIntegerArray xmlns:ns1="http://soapinterop.org/" 
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<inputIntegerArray xmlns:ns2="http://schemas.xmlsoap.org/soap/encoding/" 
xsi:type="ns2:Array" ns2:arrayType="xsd:int[5]">
<item xsi:type="xsd:int">5</item>
<item xsi:type="xsd:int">4</item>
<item xsi:type="xsd:int">3</item>
<item xsi:type="xsd:int">2</item>
<item xsi:type="xsd:int">1</item>
</inputIntegerArray>
</ns1:echoIntegerArray>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
____________________________
____________________________
Received request.
-----------------------
  SOAPAction = "http://soapinterop.org/"
  Host = localhost
  Content-Type = text/xml; charset=utf-8
  Content-Length = 762
-----------------------
<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body>
<ns1:echoFloatArray xmlns:ns1="http://soapinterop.org/" 
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<inputFloatArray xmlns:ns2="http://schemas.xmlsoap.org/soap/encoding/" 
xsi:type="ns2:Array" ns2:arrayType="xsd:float[5]">
<item xsi:type="xsd:float">5.5</item>
<item xsi:type="xsd:float">4.4</item>
<item xsi:type="xsd:float">3.3</item>
<item xsi:type="xsd:float">2.2</item>
<item xsi:type="xsd:float">1.1</item>
</inputFloatArray>
</ns1:echoFloatArray>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
____________________________
____________________________
Received request.
-----------------------
  SOAPAction = "http://soapinterop.org/"
  Host = localhost
  Content-Type = text/xml; charset=utf-8
  Content-Length = 801
-----------------------
<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body>
<ns1:echoStringArray xmlns:ns1="http://soapinterop.org/" 
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<inputStringArray xmlns:ns2="http://schemas.xmlsoap.org/soap/encoding/" 
xsi:type="ns2:Array" ns2:arrayType="xsd:string[5]">
<item xsi:type="xsd:string">First</item>
<item xsi:type="xsd:string">Second</item>
<item xsi:type="xsd:string">Fifth (just kidding :))</item>
<item xsi:type="xsd:string">Fourth</item>
<item xsi:type="xsd:string">Last</item>
</inputStringArray>
</ns1:echoStringArray>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
____________________________
____________________________
Received request.
-----------------------
  SOAPAction = "http://soapinterop.org/"
  Host = localhost
  Content-Type = text/xml; charset=utf-8
  Content-Length = 1527
-----------------------
<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body>
<ns1:echoStructArray xmlns:ns1="http://soapinterop.org/" 
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<inputStructArray xmlns:ns2="http://schemas.xmlsoap.org/soap/encoding/" 
xsi:type="ns2:Array" xmlns:ns3="http://soapinterop.org/xsd" 
ns2:arrayType="ns3:SOAPStruct[5]"><item xsi:type="ns3:SOAPStruct">
<varInt xsi:type="xsd:int">5</varInt>
<varFloat xsi:type="xsd:float">5.55555</varFloat>
<varString xsi:type="xsd:string">cinqo</varString>
</item>
<item xsi:type="ns3:SOAPStruct">
<varInt xsi:type="xsd:int">4</varInt>
<varFloat xsi:type="xsd:float">4.4444</varFloat>
<varString xsi:type="xsd:string">quattro</varString>
</item>
<item xsi:type="ns3:SOAPStruct">
<varInt xsi:type="xsd:int">3</varInt>
<varFloat xsi:type="xsd:float">3.333</varFloat>
<varString xsi:type="xsd:string">tres</varString>
</item>
<item xsi:type="ns3:SOAPStruct">
<varInt xsi:type="xsd:int">2</varInt>
<varFloat xsi:type="xsd:float">2.22</varFloat>
<varString xsi:type="xsd:string">duet</varString>
</item>
<item xsi:type="ns3:SOAPStruct">
<varInt xsi:type="xsd:int">1</varInt>
<varFloat xsi:type="xsd:float">1.1</varFloat>
<varString xsi:type="xsd:string">un</varString>
</item>
</inputStructArray>
</ns1:echoStructArray>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
____________________________

We will examine some of this output in more detail as we walk through the example. But first, here is the Apache SOAP 2.2 EchoTestClient in its entirety:

package samples.interop;
  
import java.util.Vector;
import org.apache.soap.*;
import org.apache.soap.encoding.SOAPMappingRegistry;
import org.apache.soap.encoding.soapenc.*;
import org.apache.soap.rpc.*;
import org.apache.soap.messaging.*;
import java.net.URL;
import org.apache.soap.util.xml.*;
import java.io.*;
import org.w3c.dom.*;
import org.apache.soap.util.*;
import java.lang.reflect.*;
  
/** A quick-and-dirty client for the Interop echo test services as defined
 * at http://www.xmethods.net/ilab.
 * 
 * Defaults to the Apache endpoint, but you can point it somewhere else via
 * the command line:
 * 
 *    EchoTestClient http://some.other.place/
 * 
 * DOES NOT SUPPORT DIFFERENT SOAPACTION URIS YET.
 * 
 * @author Glen Daniels ([email protected])
 */
public class EchoTestClient
{
  SOAPMappingRegistry smr = 
    new SOAPMappingRegistry(Constants.NS_URI_CURRENT_SCHEMA_XSD);
  
//  public static final String DEFAULT_URL = 
//    "http://nagoya.apache.org:5089/soap/servlet/rpcrouter";
  public static final String DEFAULT_URL = 
    "http://localhost:8080/soap/servlet/rpcrouter";
// pick one!  First line works for round 1; second for round 2: base
public static final String ACTION_URI = "urn:soapinterop";
// public static final String ACTION_URI = "http://soapinterop.org/";
  
  public static final String OBJECT_URI = "http://soapinterop.org/xsd";
  public Header header = null;
  
  public static void main(String args[])
  {
    URL url = null;
  
    try {
      if (args.length > 0) {
        url = new URL(args[0]);
      } else {
        url = new URL(DEFAULT_URL);
      }
    } catch (Exception e) {
      e.printStackTrace(  );
    }
    
    EchoTestClient eTest = new EchoTestClient(  );
    eTest.doWork(url);
  }
  
  private static boolean equals(Object obj1, Object obj2) {
    if (obj1 == null) return (obj2 == null);
    if (obj1.equals(obj2)) return true;
    if (!obj2.getClass().isArray(  )) return false;
    if (!obj1.getClass().isArray(  )) return false;
    if (Array.getLength(obj1) != Array.getLength(obj2)) return false;
    for (int i=0; i<Array.getLength(obj1); i++)
      if (!equals(Array.get(obj1,i),Array.get(obj2,i))) return false;
    return true;
  }
  
  public void doWork(URL url)
  {
    IntDeserializer intDser = new IntDeserializer(  );
    FloatDeserializer floatDser = new FloatDeserializer(  );
    StringDeserializer stringDser = new StringDeserializer(  );
    ArraySerializer arraySer = new ArraySerializer(  );
    DataSerializer dataSer = new DataSerializer(  );
    smr.mapTypes(Constants.NS_URI_SOAP_ENC, 
        new QName(OBJECT_URI, "SOAPStruct"), Data.class, dataSer, dataSer);
  
    Integer i = new Integer(5);
    Parameter p = new Parameter("inputInteger", Integer.class, i, null);
    smr.mapTypes(Constants.NS_URI_SOAP_ENC, 
        new QName("", "Return"), null, null, intDser);
    doCall(url, "echoInteger", p);
    
    p = new Parameter("inputFloat", Float.class, new Float(55.5), null);
    smr.mapTypes(Constants.NS_URI_SOAP_ENC, 
        new QName("", "Return"), null, null, floatDser);
    doCall(url, "echoFloat", p);
    
    p = new Parameter("inputString", String.class, "Hi there!", null);
    smr.mapTypes(Constants.NS_URI_SOAP_ENC, 
        new QName("", "Return"), null, null, stringDser);
    doCall(url, "echoString", p);
    
    p = new Parameter("inputStruct", Data.class, 
        new Data(5, "Hola, baby", (float)10.0), null);
    smr.mapTypes(Constants.NS_URI_SOAP_ENC, 
        new QName("", "Return"), null, null, dataSer);
    doCall(url, "echoStruct", p);
    
    p = new Parameter("inputIntegerArray", Integer[].class, new Integer[]{
                      new Integer(5),
                      new Integer(4),
                      new Integer(3),
                      new Integer(2),
                      new Integer(1)}, null);
    smr.mapTypes(Constants.NS_URI_SOAP_ENC, 
        new QName("", "Return"), null, null, arraySer);
    doCall(url, "echoIntegerArray", p);        
  
    p = new Parameter("inputFloatArray", Float[].class, new Float[]{
                      new Float(5.5),
                      new Float(4.4),
                      new Float(3.3),
                      new Float(2.2),
                      new Float(1.1)}, null);
    smr.mapTypes(Constants.NS_URI_SOAP_ENC, 
        new QName("", "Return"), null, null, arraySer);
    doCall(url, "echoFloatArray", p);        
  
    p = new Parameter("inputStringArray", String[].class, new String[]{
                      "First",
                      "Second",
                      "Fifth (just kidding :))",
                      "Fourth",
                      "Last"}, null);
    smr.mapTypes(Constants.NS_URI_SOAP_ENC, 
        new QName("", "Return"), null, null, arraySer);
    doCall(url, "echoStringArray", p);        
  
    p = new Parameter("inputStructArray", Data[].class, new Data[]{
                      new Data(5, "cinqo", new Float("5.55555").floatValue(  )),
                      new Data(4, "quattro", (float)4.4444),
                      new Data(3, "tres", (float)3.333),
                      new Data(2, "duet", (float)2.22),
                      new Data(1, "un", (float)1.1)}, null);
    smr.mapTypes(Constants.NS_URI_SOAP_ENC, 
        new QName("", "Return"), null, null, arraySer);
    doCall(url, "echoStructArray", p);        
  }
  
  public void doCall(URL url, String methodName, Parameter param)
  {
    try {
      Call call = new Call(  );
      Vector params = new Vector(  );
      params.addElement(param);
      call.setSOAPMappingRegistry(smr);
      call.setTargetObjectURI(ACTION_URI);
      call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);
      call.setMethodName(methodName);
      call.setParams(params);
      if (header != null)
        call.setHeader(header);
      
      String soapAction = ACTION_URI;
//      System.out.println("soapAction: " + soapAction);
/*      if (true) {
        soapAction = soapAction + methodName;
      }
*/      
      Response resp = call.invoke(url, soapAction);
      
      // check response 
      if (!resp.generatedFault(  )) {
        Parameter ret = resp.getReturnValue(  );
        Object output = ret.getValue(  );
        Object input = param.getValue(  );
  
        if (equals(input,output)) {
          System.out.println(methodName + "	 OK");
        } else {
          System.out.println(methodName + "	 FAIL: " + output);
        }
      }
      else {
        Fault fault = resp.getFault (  );
        System.err.println (methodName + " generated fault: ");
        System.out.println ("  Fault Code   = " + fault.getFaultCode(  ));  
        System.out.println ("  Fault String = " + fault.getFaultString(  ));
      }
      
    } catch (Exception e) {
      e.printStackTrace(  );
    }
  }
}

Let’s examine some of this code in detail. First, here is what we did to get around the mismatch of the schema namespace URIs. The value passed into the mapping registry is based on a default, which was initialized to use the older value:

public class EchoTestClient
{
  SOAPMappingRegistry smr = 
    new SOAPMappingRegistry(Constants.NS_URI_CURRENT_SCHEMA_XSD);

Apache SOAP 2.2 supports the 2001 schema—it just does not default to it. We could have simply changed this line of code, but changing it doesn’t fix the problem everywhere. Instead, we got the Constants.java file from the Apache SOAP distribution; updated Constants.NS_URI_CURRENT_SCHEMA_XSD to default to the desired value; and recompiled the Constants, SoapEncUtils, and ArraySerializer classes:

/*  Changed this:
public static final String NS_URI_CURRENT_SCHEMA_XSI =
    NS_URI_1999_SCHEMA_XSI;
  public static final String NS_URI_CURRENT_SCHEMA_XSD =
    NS_URI_1999_SCHEMA_XSD;
*/
// To this:
  public static final String NS_URI_CURRENT_SCHEMA_XSI =
    NS_URI_2001_SCHEMA_XSI;
  public static final String NS_URI_CURRENT_SCHEMA_XSD =
    NS_URI_2001_SCHEMA_XSD;

We also commented out the following lines in the doWork( ) method of the test:

      String soapAction = ACTION_URI;
/*      if (true) {
        soapAction = soapAction + methodName;
      }
*/      
      Response resp = call.invoke(url, soapAction);

Almost every test we tried did not like having the method name appended to the soapAction header. It’s good that the author of the code was aware of this problem and isolated it so it could be turned on and off easily. Also, depending on what round of tests we wanted to run, we had to change the action URI; the Round 1 tests expected the URI urn:soapinterop, while the current Round 2: base tests expect http://soapinterop.org/:

// pick one!  First line works for round 1; second for round 2: base
public static final String ACTION_URI = "urn:soapinterop";
// public static final String ACTION_URI = "http://soapinterop.org/";

The Apache Axis version of the same test didn’t need any modification because it is a new test that presumably works only against the Round 2 tests.

The mapping registry maintains the relationship between the XML datatypes and their corresponding Java types. It is also a utility that marshals and unmarshals the data between the Java representation and the SOAP envelope representation. It accomplishes this task by maintaining a list of serialization and deserialization classes for each datatype it knows about.

By default, the SOAPMappingRegistry is instantiated with the appropriate mappings and serializers/deserializers for each type that it supports.

The default serialization mapping for the String class creates the XML rendition. The SOAP envelope resulting from this call looks like:

<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SOAP-ENV:Body>
    <ns1:echoString 
        xmlns:ns1="urn:soapinterop" 
        SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <inputString 
          xmlns:ns2="http://www.w3.org/2001/XMLSchema"
           xsi:type="ns2:string">
                          Hi there!
      </inputString>
    </ns1:echoString>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Note the inclusion of the xsi:type attribute. Not all SOAP toolkits that participated in the Round 1 testing supported this attribute.

These default mappings may be overridden by calling the mapTypes( ) method. The mapTypes( ) method takes the following parameters:

For example, the following objects are part of Apache SOAP’s serialization framework and are included in the org.apache.soap.encoding.soapenc package:

    IntDeserializer intDser = new IntDeserializer(  );
    FloatDeserializer floatDser = new FloatDeserializer(  );
    StringDeserializer stringDser = new StringDeserializer(  );
    ArraySerializer arraySer = new ArraySerializer(  );

In the EchoTestClient, the call to mapTypes( ) is necessary for the “Return” because the SOAP Toolkit that services the request may not support the placement of the xsi:type attribute in the response envelope. The type information for the parameter is specified along with its name and value when the parameter object is constructed:

    p = new Parameter("inputString", String.class, "Hi there!", null);
    smr.mapTypes(Constants.NS_URI_SOAP_ENC, 
        new QName("", "Return"), null, null, stringDser);
    doCall(url, "echoString", p);

Default mappings are available for more complicated objects, such as arrays. The following code constructs a method invocation with a parameter that is an array of 5 integers, with the values of 1 through 5:

    p = new Parameter("inputIntegerArray", Integer[].class, new Integer[]{
                      new Integer(5),
                      new Integer(4),
                      new Integer(3),
                      new Integer(2),
                      new Integer(1)}, null);
    smr.mapTypes(Constants.NS_URI_SOAP_ENC, 
        new QName("", "Return"), null, null, arraySer);
    doCall(url, "echoIntegerArray", p);

The serialization framework knows how to traverse the array, using the appropriate serialization classes for each member element (in this case, all of type Integer). The serialized output looks like:

<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope 
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SOAP-ENV:Body>
    <ns1:echoIntegerArray 
        xmlns:ns1="urn:soapinterop" 
        SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <inputIntegerArray 
          xmlns:ns2="http://schemas.xmlsoap.org/soap/encoding/" 
          xsi:type="ns2:Array" 
          xmlns:ns3="http://www.w3.org/2001/XMLSchema" 
          ns2:arrayType="ns3:int[5]">
        <item xsi:type="ns3:int">5</item>
        <item xsi:type="ns3:int">4</item>
        <item xsi:type="ns3:int">3</item>
        <item xsi:type="ns3:int">2</item>
        <item xsi:type="ns3:int">1</item>
      </inputIntegerArray>
    </ns1:echoIntegerArray>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Part of the test involves sending a complex data structure represented as a SOAP struct.^[17] The structure contains three data items: an integer, a string, and a float. Creating a custom data serialization requires the following steps:

In the following code, DataSerializer is a custom class that we will explain shortly. The custom object, the serializer, and the deserializer are plugged into the mapping registry with the call to mapTypes( ):

    DataSerializer dataSer = new DataSerializer(  );
    smr.mapTypes(Constants.NS_URI_SOAP_ENC, 
        new QName(OBJECT_URI, "SOAPStruct"), Data.class, dataSer, dataSer);

As shown in the following listing, the setup for call( ) is similar to the setup that was used for the “built-in” types:

    p = new Parameter("inputStruct", Data.class, 
       new Data(5, "Hola, baby", (float)10.0), null);
    doCall(url, "echoStruct", p);

Here’s the SOAP envelope generated by the call:

<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope 
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SOAP-ENV:Body>
    <ns1:echoStruct xmlns:ns1="urn:soapinterop" 
        SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <inputStruct xmlns:ns2="http://soapinterop.org/xsd" 
        xsi:type="ns2:SOAPStruct">
        <varInt xmlns:ns3="http://www.w3.org/2001/XMLSchema" 
            xsi:type="ns3:int">
          5
        </varInt>
        <varFloat xmlns:ns4="http://www.w3.org/2001/XMLSchema" 
            xsi:type="ns4:float">
          10.0
        </varFloat>
        <varString xmlns:ns5="http://www.w3.org/2001/XMLSchema" 
            xsi:type="ns5:string">
          Hola, baby
        </varString>
      </inputStruct>
    </ns1:echoStruct>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The next listing shows the Java class that represents the data structure. It holds the data and implements an equals( ) method that the EchoTestClient uses to compare results:

class Data
{
  Integer myInt;
  String myString;
  Float myFloat;
  
  public Data(  )
  {
  }
  
  public Data(int i, String s, float f)
  {
    myInt = new Integer(i);
    myString = s;
    myFloat = new Float(f);
  }
  
  public String toString(  )
  {
    return "Data[MyInt=" + myInt + ", MyString='" + 
      myString + "', myFloat=" + myFloat + "]";
  }
  
  /**
   * Equality comparison.  
   */
  public boolean equals(Object object) {
    if (!(object instanceof Data)) return false;
  
    Data that= (Data) object;
  
    if (!this.myInt.equals(that.myInt)) return false;
    if (!this.myFloat.equals(that.myFloat)) return false;
  
    if (this.myString == null) {
      if (that.myString != null) return false;
    } else {
      if (!this.myString.equals(that.myString)) return false;
    }
  
    return true;
  };
}

The custom DataSerializer class implements both the Serializer and Deserializer interfaces; these interfaces define the marshall( ) and unmarshall( ) methods, respectively. Putting both methods in one class and using that class for both serialization and deserialization is a common design strategy. The marshall( ) method simply calls the individual marshall( ) method for each datatype in the Java class. Likewise, the unmarshall( ) method calls the individual unmarshall( ) method for each type in the SOAP struct and returns a JavaBean instance:

package samples.interop;
  
import java.util.Vector;
import org.apache.soap.*;
import org.apache.soap.encoding.SOAPMappingRegistry;
import org.apache.soap.encoding.soapenc.*;
import org.apache.soap.rpc.*;
import org.apache.soap.messaging.*;
import java.net.URL;
import org.apache.soap.util.xml.*;
import java.io.*;
import org.w3c.dom.*;
import org.apache.soap.util.*;
import java.lang.reflect.*;
  
public class DataSerializer implements Serializer, Deserializer
{
  public void marshall(String inScopeEncStyle, Class javaType, Object src,
                       Object context, Writer sink, NSStack nsStack,
                       XMLJavaMappingRegistry xjmr, SOAPContext ctx)
    throws IllegalArgumentException, IOException
  {
    if(!javaType.equals(Data.class))
    {
      throw new IllegalArgumentException("Can only serialize Data instances");
    }
    
    Data data = (Data)src;
    
    nsStack.pushScope(  );
    if(src!=null)
    {
      SoapEncUtils.generateStructureHeader(inScopeEncStyle,
                                           javaType,
                                           context,
                                           sink,
                                           nsStack,xjmr);
  
      sink.write(StringUtils.lineSeparator);
      
      xjmr.marshall(inScopeEncStyle, Integer.class, data.myInt, "varInt",
                    sink, nsStack, ctx);
      sink.write(StringUtils.lineSeparator);
      xjmr.marshall(inScopeEncStyle, Float.class, data.myFloat, "varFloat",
                    sink, nsStack, ctx);
      sink.write(StringUtils.lineSeparator);
      xjmr.marshall(inScopeEncStyle, String.class, data.myString, "varString",
                    sink, nsStack, ctx);
      sink.write(StringUtils.lineSeparator);
      
      sink.write("</" + context + '>'),
    }
    else
    {
      SoapEncUtils.generateNullStructure(inScopeEncStyle,
                                         javaType,
                                         context,
                                         sink,
                                         nsStack,xjmr);
    }
    nsStack.popScope(  );
  }
  
  public Bean unmarshall(String inScopeEncStyle, QName elementType, Node src,
                         XMLJavaMappingRegistry xjmr, SOAPContext ctx)
    throws IllegalArgumentException
  {
    Element root = (Element)src;
    String name = root.getTagName(  );
  
    if (SoapEncUtils.isNull(root))
    {
      return new Bean(Data.class, null);
    }
    
    Data ret = new Data(  );
    NodeList list = root.getElementsByTagName("varInt");
    if (list == null || list.getLength(  ) == 0) {
        throw new IllegalArgumentException(
        "No 'varInt' Element (deserializing Data struct)");
    }
    Element el = (Element)list.item(0);
    ret.myInt = new Integer(DOMUtils.getChildCharacterData(el));
    
    list = root.getElementsByTagName("varFloat");
    if (list == null || list.getLength(  ) == 0) {
        throw new IllegalArgumentException(
        "No 'varFloat' Element (deserializing Data struct)");
    }
    el = (Element)list.item(0);
    ret.myFloat = new Float(DOMUtils.getChildCharacterData(el));
    
    list = root.getElementsByTagName("varString");
    if (list == null || list.getLength(  ) == 0) {
      throw new IllegalArgumentException(
       "No 'varString' Element (deserializing Data struct)");
    }
    el = (Element)list.item(0);
    ret.myString = ((Text)el.getFirstChild()).getData(  );
    
    return new Bean(Data.class, ret);
  }
}

Next, the custom structs are aggregated into an array:

      p = new Parameter("inputStructArray", Data[].class, new Data[]{
                        new Data(5, "cinqo", new Float("5.55555").floatValue(  )),
                        new Data(4, "quattro", (float)4.4444),
                        new Data(3, "tres", (float)3.333),
                        new Data(2, "duet", (float)2.22),
                        new Data(1, "un", (float)1.1)}, null);
      smr.mapTypes(Constants.NS_URI_SOAP_ENC, 
          new QName("", "Return"), null, null, arraySer);
     doCall(url, "echoStructArray", p);        
    }

The output looks like . . . well, you get the idea. Because the Data type is already plugged into the serialization framework, the default array handling mechanism can just call Dataserializer to do its work.

All this coding, marshalling, and unmarshalling is required because we are using a dynamic call interface. On the service side, we don’t need any of this work; we just make an RPC call and Apache SOAP takes care of the rest. The server runtime needs only the information specified in a deployment descriptor. The EchoTest Java service from Apache SOAP 2.2 is comparatively uninteresting:

package samples.interop;
  
/** An implementation of the interop echo service as defined at
 * http://www.xmethods.net/ilab.
 * 
 * @author Glen Daniels ([email protected])
 */
public class EchoTestService
{
  public void nop(  )
  {
  }
  
  public int echoInteger(int i)
  {
    return i;
  }
  
  public float echoFloat(float f)
  {
    return f;
  }
  
  public String echoString(String str)
  {
    return str;
  }
  
  public Data echoStruct(Data data)
  {
    return data;
  }
  
  public int [] echoIntegerArray(int [] ii)
  {
    return ii;
  }
  
  public float [] echoFloatArray(float [] ff)
  {
    return ff;
  }
  
  public String [] echoStringArray(String [] ss)
  {
    return ss;
  }
  
  public Data [] echoStructArray(Data [] ds)
  {
    return ds;
  }
}

In an environment in which the client and service interfaces are automatically generated by a tool, such as one that implements JAX-RPC, this coding is moot because it is hidden from the developer. When you need to understand interoperability issues between clients and services, however, it is critical to understand the concepts behind them. In the future, we may reach a state in which interoperability “just works” between almost any client and server-side implementations; however, that future is still remote.

Many SB Interop participants have built a browser client that remotely executes a test client on your behalf. Figure 9-1 shows the interface to one such site for Iona XMLBus (http://interop.xmlbus.com:7002/InteropTest/index.jsp). You can type in any known WSDL endpoint that participates in the testing and learn how an XMLBus client fared against the remote service.

Figure 9-1. The browser interface used for running SB Interop clients remotely

Figure 9-2 shows an example of the results.

Figure 9-2. Test results from browser-based remote client testing