Tutorials : Using SOAP with Java :

by Samudra Gupta

Welcome back to part two of the series. Hope you had a nice coding time and had no major problem in deploying your first SOAP application. If you had one, it is most likely a classpath related problem and you yourself could solve it. One of the easiest ways of solving these problems is to explicitly specify the required .jar files to the java runtime.

Anyway, it is time to explore SOAP in a greater detail; after all life is not always as simple as passing String data-types to the SOAP services. Often the world is much more complex with applications exchanging user-defined data-types. The major issue in handling these complex data-types in the SOAP context is to define a Serialization and Deserialization mechanism for them. The Apache SOAP API defines and implements a couple of default Serializers/Deserializers for primitive data types and Java Beans and it is also possible to create our own custom Serializers and Deserializers. In this installment, we will discuss issues related with the Serialization and Deserialization and will develop a Java Bean based SOAP application. Before we venture to do that, we need to understand the Serialization mechanism behind the SOAP implementations.

Serialization/Deserialization protocol in SOAP

First let us define the term Serialization and Deserialization in SOAP context. Serialization is a process of converting objects to the XML instance and Deserialization is the process of constructing objects out of the XML instance. In the context of a SOAP Remote Procedure Call, which we are developing throughout this series, there are two types of data exchange taking place.

• The parameters to the SOAP Remote method.
• The response from the SOAP remote service.

The exchange of data usually takes place using a methodology for transforming object graphs to XML, named as Section 5 encoding. All major SOAP implementations available today use this encoding scheme internally. Consider the following complex data type:

class Person
{
     String name;
     nt age;
}

and also consider a SOAP remote service accepting a Person data-type as a parameter:

class Aservice
{
   public String acceptPerson(Person p)
   {
       //do something here
       return “a string”;
    }
 }

If we invoke this remote method named acceptPerson as a part of the remote service Aservice, then the corresponsing SOAP representation of the RPC will look like:

<SOAP-ENV:Body>
  <ns1:accptPerson xmlns:ns1=”urn:the urn of the service” 
  SOAP-ENV:encodingStyle = “http://schemas.xmlsoap.org/soap/encoding/”>
      <serviceParam xmlns:ns2=”some uri” xsi:type=”ns2:Person”>
          <age xsi:type=” xsd:int”>22</age>
          <name xsi:type=xsd:string”>Samudra</name>
      </serviceParam>
    </ns1:acceptPerson>
 </SOAP-ENV:Body>

The above SOAP XML instance is a representation of a RPC call that dispatches the method call acceptPerson with a Person object as a parameter. The elements serviceParam, name, age are called accessors and they are the container of the values. The xsi:type attributes define the exact data-types of the elements. The SOAP provider and the client normally agree in advance on the data-types of parameters of each RPC but this exact specification becomes useful in a case where the service uses a generalised data-type which can potentially represent two or more data-types. Consider a case that a method accepts a java.lang.Object as a parameter. The Object might be an Integer or a String or anything else. In this case, the xsd:type attribute will strictly indicate the data-type to be used. The accessors with explicit xsd:type attribute are known as polymorphic accessors. The Apache SOAP serialization mechanism uses polymorphic accessors.

Simple data-types in SOAP

The Apache SOAP implementation supports most of the simple data-types except char. But it is a trivial task to implement a Serializer for the same. The list of the all supported simple types can be found within the Apache SOAP API documentation but for a handy note, the following table illustrates a few of them.

If you have been tempted to overlook the table, you might have missed one or two important points. First of all, it is worth noticing that the primitive types and their wrapper(s) both are handled with a separate Serializer class but they are represented as the same data-type in the SOAP XML instance. Second, there is a rather curious data-type QName. This is a data-type designed to represent the user-defined compound data-types.

Compound types

As you can see from the above table that arbitrary Java bean classes which are compound data-types can be serialized with a BeanSerializer provided by the Apache SOAP, but to do that the compound data-type that you are using must follow the java bean specification which we will discuss in the relevant section.

How to Add Java Applets to Your Site

New on the Java Boutique:

New Article:
J2EE Deployment Specification
Why is it that J2EE applications written in the same language, Java, may not coexist on different servers? While the answer isn't simple Sun has set out to alleviate these problems with the "J2EE Deployment Specification".
... [more articles]

New Tutorial:
Designing Packages for Stability
Are your designs stable? This month Samudra will focus on the change impact relationship involved in designing classes showing us how to take them into account when designing the package relationship.
... [more Tutorials]

Year in Review:
The Best of 2002
The year 2002 saw 201 new applets posted to JavaBoutique. Check out the 2 most popular apps from each month of 2002!
... [popular applets]

Elsewhere on internet.com:

WebDeveloper Java
Lots of Java information on webdeveloper.com

WDVL Java
Thorough Java resource at the Web Developer's Virtual Library.

ScriptSearch Java
Hundreds of free Java code files to download.