You can migrate web services that were developed using
Apache SOAP to Java API for XML-based RPC (JAX-RPC)
web services that are developed based on the Web Services for Java Platform, Enterprise Edition (Java EE) 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
Deprecated feature: For this version of the application
server, SOAP-Security (XML digital signature) based on Apache SOAP
implementation has been removed. Instead of using SOAP-Security,
migrate and re-configure your application to the JSR-109 implementation
of web services.
depfeat
To migrate these client applications
according to Java standards:
Procedure
- Plan your migration strategy. You can port an
Apache SOAP client to a 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 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.
- 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 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
you can implement the web services in a Java EE
environment.