Migrate Apache SOAP Web services to Web services for J2EE

Note: This page applies to WebSphere Application Server - Express Version 5.0.2 and later only.

If you have used the Apache SOAP support to create Web services client applications in WebSphere Application Server - Express Version 5.0 and want use Web services for J2EE, also known as JSR 109, you need to migrate your Version 5.0 client applications.

To migrate these client applications to the JSR 109 Web services standards:

Plan your migration strategy.
There are two ways you can port an Apache SOAP client to Java API for XML-based RPC (JAX-RPC) Web services client:
- If you have, or can create, a Web Services Description Language (WSDL) document for the service, consider using the WSDL2Java command tool to generate bindings for the Web service. It is more work to adapt an Apache SOAP client to use the generated JAX-RPC bindings, but the resulting client code is more robust and easier to maintain. To follow this path, see Develop a Web services client.
- If you do not have a WSDL document for the service, do not expect the service to change, and you want to port the Apache SOAP client with a minimal work, you can convert the code to use the JAX-RPC dynamic invocation interface (DII), which is similar to the Apache SOAP APIs. The DII APIs do not use WSDL or generated bindings.
You should be aware that since JAX-RPC does not specify a framework for user-written serializers, the JAX-RPC does not support the use of custom serializers. If your application cannot conform to the default mapping between Java, WSDL, and XML supported by WebSphere Application Server - Express, you should not attempt to migrate the application.

The remainder of this topic assumes that you have decided to use the JAX-RPC DII APIs.
Convert the client application from Apache SOAP to JAX-RPC DII
The Apache SOAP API and JAX-RPC DII API structures are similar. You can instantiate and configure a call object, set up the parameters, invoke the operation, and process the result in both.

In JAX-RPC, you can create a generic instance of a Service object with javax.xml.rpc.Service service = ServiceFactory.newInstance().createService(new QName(""));
1. Create the call object.
  In Apache SOAP, an instance of the call object is created by org.apache.soap.rpc.Call call = new org.apache.soap.rpc.Call()
  
  In JAX-RPC, an instance of the call object is created by java.xml.rpc.Call call = service.createCall();
2. Set the endpoint URI.
  In Apache SOAP, the target URI for the operation is passed as a parameter to call.invoke: call.invoke("http://...", "");
  
  In JAX-RPC, the setTargetEndpointAddress() method is used as a parameter to parametcall.setTargetEndpointAddress("http://...");
  
  Apache SOAP has a setTargetObjectURI() method on the call object that contains routing information for the request. JAX-RPC has no equivalent method. The information in the targetObjectURI is included in the targetEndpoint URI for JAX-RPC.
3. Set the operation name.
  In Apache SOAP, the operation name is configured on the call object by call.setMethodName("opName");
  
  The setOperationName method, which accepts a QName instead of a String parameter, is used in JAX-RPC as follows:
```
  call.setOperationName(new javax.xml.namespace.Qname("namespace", 
                        "opName"));
```
4. Set the encoding style.
  In Apache SOAP, the encoding style is configured on the call object by call.setEncodingStyleURI(org.apache.soap.Constants.NS_URI_SOAP_ENC);
  
  In JAX-RPC, the encoding style is set by a property of the call object call.setProperty(javax.xml.rpc.Call.ENCODINGSTYLE_URI_PROPERTY, "http://schemas.xmlsoap.org/soap/encoding/");
5. Declare the parameters and set the parameter values.
  Apache SOAP parameter types and values are described by parameter instances, which are collected into a Vector and set on the call object before the call, for example:
```
  Vector params = new Vector (); 
  params.addElement (new org.apache.soap.rpc.Parameter(name, 
                     type, value, encodingURI)); 
  // repeat for additional parameters... call.setParams (params);
```
  For JAX-RPC, the call object is configured with parameter names and types without providing their values, for example:
```
  call.addParameter(name, xmlType, mode); 
  // repeat for additional parameters call.setReturnType(type);
```
  where
  - name (type java.lang.String) is the name of the parameter
  - xmlType (type javax.xml.namespace.QName) is the XML type of the parameter
  - mode (type javax.xml.rpc.ParameterMode) the mode of the parameter, for example: IN, OUT, or INOUT
6. Make the call.
  In Apache SOAP, the operation is invoked on the call object by org.apache.soap.Response resp = call.invoke(endpointURI, "");
  
  In JAX-RPC, the parameter values are collected into an array and passed to call.invoke as follows:
```
Object resp = call.invoke(new Object[] {parm1, parm2,...});
```
7. Check for faults.
  In Apache SOAP, you can check for a SOAP fault on the invocation by checking the Response:
```
  if resp.generatedFault then {   
    org.apache.soap.Fault f = resp.getFault;   
    f.getFaultCode();   
    f.getFaultString(); }
```
  A java.rmi.RemoteException is thrown in JAX-RPC if a SOAP fault occurs on the invocation.
```
  try   
    ... call.invoke(...) 
  catch (java.rmi.RemoteException) ...
```
8. Retrieve the result.
  In Apache SOAP, if the invocation was successful and returns a result, it can be retrieved from the Response object:
```
Parameter result = resp.getReturnValue(); return result.getValue();
```
  In JAX-RPC, the result of the invocation is the returned object when no exception is thrown:
```
  Object result = call.invoke(...);
    ... 
  return result;
```

Note: Examples may be wrapped for display purposes.