You can migrate Web services that were developed using
Apache SOAP to Web services that are developed based on the Web Services for
Java 2 Platform, Enterprise Edition (J2EE) specification.
Before you begin
If you have used Web services based on Apache SOAP and now want
to develop and implement Web services that are Java-based, you need to migrate
client applications developed with all versions of 4.0, and versions of 5.0
prior to 5.0.2.
About this task
To migrate these client applications according to Java standards:
Procedure
- Plan your migration strategy. You can port an Apache
SOAP client to a Java API for XML-based RPC (JAX-RPC) Web services client
in one of two ways:
Because 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 technology
supported by WebSphere Application Server, do not attempt to migrate the application.
The remainder of this topic assumes that you decided to use the JAX-RPC
dynamic invocation interface (DII) APIs.
- Review
the GetQuote Sample. A Web services migration Sample is
available in the Samples Gallery.
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.
- 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. You can 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.
- 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.
- 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 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.
- 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"));
- 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.
- 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
- 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.
- Check for faults. 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();
}
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) ...
- 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;
Results
You have migrated Apache SOAP Web services to J2EE Web services.