Migrate Apache SOAP web services to JAX-RPC web services based on Java EE standards

We can migrate web services that were developed using Apache SOAP to JAX-RPC web services developed based on the Web Services for Java EE specification.

If we have used web services based on Apache SOAP and now want to develop and implement web services that are Java-based, we need to migrate client applications developed with all versions of 4.0, and versions of 5.0 prior to 5.0.2.

SOAP-Security (XML digital signature) based on Apache SOAP implementation has been removed. Instead of using SOAP-Security, migrate and re-configure the application to the JSR-109 implementation of web services.

To migrate these client applications according to Java standards:

Tasks

1. Plan the migration strategy. We can port an Apache SOAP client to a JAX-RPC web services client in one of two ways:

   • If we 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 the article on developing a web services client in the information center.

   • If we do not have a WSDL document for the service, do not expect the service to change, and we want to port the Apache SOAP client with minimal work, we 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.

   Because JAX-RPC does not specify a framework for user-written serializers, the JAX-RPC does not support the use of custom serializers. If the application cannot conform to the default mapping between Java, WSDL, and XML technology supported by WebSphere Application Server, do not attempt to migrate the application. The remainder of this topic assumes that we decided to use the JAX-RPC dynamic invocation interface (DII) APIs.

2. Review the GetQuote Sample. A web services migration Sample is available in the Samples section of the Information Center. This sample is located in the GetQuote.java file, originally written for Apache SOAP users, and includes an explanation about the changes needed to migrate to the JAX-RPC DII interfaces. To learn more, see the Samples section of the Information Center.
3. Convert the client application from Apache SOAP to JAX-RPC DII The Apache SOAP API and JAX-RPC DII API structures are similar. We can instantiate and configure a call object, set up the parameters, invoke the operation, and process the result in both. Create a generic instance of a Service object with the following command:

   javax.xml.rpc.Service service = ServiceFactory.newInstance().createService(new QName(""));
   

   in JAX-RPC.

   1. Create the Call object. An instance of the Call object is created with the following code:

      org.apache.soap.rpc.Call call = new org.apache.soap.rpc.Call ()
      

      in Apache SOAP.

      An instance of the Call object is created by

      java.xml.rpc.Call call = service.createCall();
      

      in JAX-RPC.

   2. Set the endpoint Uniform Resource Identifiers (URI). The target URI for the operation is passed as a parameter to

      call.invoke:  call.invoke("http://...", "");
      

      in Apache SOAP.

      The setTargetEndpointAddress method is used as a parameter to

      call.setTargetEndpointAddress("http://...");
      

      in JAX-RPC.

      Apache SOAP has a setTargetObjectURI method on the Call object containing 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. The operation name is configured on the Call object by

      call.setMethodName("opName");
      

      in Apache SOAP.

      The setOperationName method, which accepts a QName instead of a String parameter, is used in JAX-RPC as illustrated in the following example:

      call.setOperationName(new javax.xml.namespace.Qname("namespace", "opName"));
      

   4. Set the encoding style. The encoding style is configured on the Call object by

      call.setEncodingStyleURI(org.apache.soap.Constants.NS_URI_SOAP_ENC);
      

      in Apache SOAP.

      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/");
      

      in JAX-RPC.
   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. The operation is invoked on the Call object by

      org.apache.soap.Response resp = call.invoke(endpointURI, "");
      

      in Apache SOAP.

      The parameter values are collected into an array and passed to call.invoke as illustrated in the following example:

      Object resp = call.invoke(new Object[] {parm1, parm2,...});
      

      in JAX-RPC.

   7. Check for faults. We 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(); 
      }
      

      in Apache SOAP.

      A java.rmi.RemoteException error is displayed 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 is 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 invoke is the returned object when no exception is displayed:

      Object result = call.invoke(...);
       ... 
      return result;
      

We have migrated Apache SOAP web services to a JAX-RPC Web services based on the Java EE specification.

What to do next

Develop a web services client based on the Web Services for Java EE specification.

Test the web services-enabled clients to make sure that the migration process is successful and we can implement the web services in a Java EE environment.

Related:

Web Services for Java EE specification

Implement JAX-RPC web services clients

Testing web services-enabled clients

WSDL2Java command for JAX-RPC applications

Mapping between Java language, WSDL and XML for JAX-RPC applications