WebReference.com - Part 5 of chapter 3 from Professional Java Web Services, Wrox Press Ltd. (3/6)

[previous] [next]

Professional Java Web Services

Obtaining the Interface

In order to write a SOAP client we first have to obtain the interface description of the service. The interface of a service is the methods that are exposed. We can obtain the interface by either looking at WSDL file for the service or looking at the implementation (code artifact) of the service. For the Job Resumé Repository Service example we have the implementation, so we can look at that to obtain the signature of exposed methods. The signatures of the methods are below:

String Submit(Resume resume)
Resume Retrieve(String uid)

Registering User-Defined Types

Now that we know the interface for the service we must ensure that we have the class file for each user-defined type in the Java classpath. We also have to make sure any custom serializers and deserializiers are registered for parameters we are sending and receiving, respectively. We also have to make sure that their class files are part of the Java classpath. In regard to the Job Resumé Repository Service example, we handled this in the Job Resumé Repository section, but we have to register a serializer/deserializer for the Resume.class. Since the Resume.class conforms to the JavaBean standard we are able to use the BeanSerializer class that comes with Apache SOAP to handle the serialization. The code snippet below shows how this is done:

SOAPMappingRegistry smr = new SOAPMappingRegistry();
BeanSerializer beanSer = new BeanSerializer();
// Map the types
smr.mapTypes(Constants.NS_URI_SOAP_ENC,
           new QName("urn:jobresumé", "resumé"),
                 Resumé.class, beanSer, beanSer);

In the above snippet, the mapTypes() method of the SOAPMappingRegistry class is used to the register the "resume" type. The syntax for the mapTypes() method is below:

public void mapTypes(java.lang.String encodingStyleURI,
                     QName elementType, java.lang.Class javaType,
                     Serializer s, Deserializer ds)

The encodingStyleURI is used to specify the encoding style that should be used to encode the type. We are using the SOAP encoding style, which is defined by the Constants.NS_URI_SOAP_ENC() static method. The elementType argument takes a variable of type QName, which contains the fully qualified element name (namespace.element) of the type. The javaType element contains the class that implements the type. The "s" and "ds" arguments should contain objects that handle serialization and deserialization, respectively. In our case, the Resume type is JavaBean, which can be serialized and deserialized by the BeanSerializier class.

Setting Up the Request

We are now ready to set up the SOAP request. This is done through the use of the org.apache.soap.rpc.RPCMessage.Call object. The Call object is responsible for setting up the details of the request:

// Setup the Call
Call call = new Call();
call.setSOAPMappingRegistry(smr);
call.setTargetObjectURI("urn:JobResuméRepositoryService");
call.setMethodName("submit");  
call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);

The setSOAPMappingRegistry() method is used to set up a reference to a SOAPMappingRegistry object so that the Call object is aware of types that will be sent and received. It's worth noting that we wouldn't call this method if we were only using the predefined types because Apache SOAP has the majority of the types defined by default. However, we are using a user-defined type so the method must be called.

The setTargetObjectURI() method is used to specify the name of the service to which the request should be routed. In our case, the name of the service is urn:JobResumeRepositoryService.>

The setMethodName() method is used to specify the name of the method that we want to execute. In our case, the method is called submit.

The setEncodingStyleURI() method is used to specify the encoding style that should be used in encoding the SOAP message. In the above code snippet, the value provided to the method specifies that SOAP encoding should be used. Note that the Constants class has many useful constants defined for SOAP.

Specifying Parameters

Since the submit() method requires a parameter, parameters have to be added to the Call object:

// Add the parameters
Vector params = new Vector();
params.addElement(new Parameter("resumé", Resumé.class, resumé, null));
call.setParams(params);

Parameters are added to the Call object by using the setParams() method. The setParams() method takes a Vector of Parameter objects as an argument. In our case there will be only one Parameter object in the array since the submit() method only takes one parameter. The Parameter object represents an argument or return value to a method call. The syntax of the parameter constructor is shown below:

Parameter(java.lang.String name, java.lang.Class type,
          java.lang.Object value, java.lang.String encodingStyleURI)

The name parameter is used to specify the name of the argument, which in our case is resume. The type parameter should contain the Java class that implements the argument (that is, String.class, Integer.class, and so on), which in our case is Resume.class. The value parameter should contain the value of the argument, which in our case is resume (an instance of the Resume class that we created). The encodingStyleURI parameter could optionally be used to specify the encoding style that should be used for encoding the type.