password
username
Sponsored by CakeMail, an email marketing software.
Newsletter preview


======================================================
IBM developerWorks
Web services/XML Tip
13 June 2007, Vol. 7, Issue 12

IBM's resource for developers
http://www.ibm.com/developerworks/?ca=dnx-712
======================================================
TOPIC: JAX-RPC VS. JAX-WS, PART 3
http://www.ibm.com/developerworks/webservices/library/ws-tip-jaxwsrpc3/index.html?ca=dnx-712

Level: Intermediate

Russell Butek (butek@us.ibm.com)
IT Specialist, IBM
Nicholas Gallardo (nlgallar@us.ibm.com)
Staff Software Engineer, IBM

Hello, tip readers.

This third part of the series about Java API for XML-based RPC
(JAX-RPC) 1.1 and Java API for XML Web Services (JAX-WS) 2.0 compares
the mapping of Web Services Description Language (WSDL) to a service
endpoint interface (SEI). The concept of an SEI was first introduced
in JAX-RPC 1.0 and has been maintained in JAX-WS 2.0, with some
additions. This tip walks you through the major differences.

For the full tip, read on below.

Until next time,
The Web services/XML tip team at developerWorks

Correspondence:
mailto:dwnews@us.ibm.com


__________________________________________________________
INTRODUCTION

Overall, the structures of a Java API for XML-based RPC (JAX-RPC) 1.1
service endpoint interface (SEI) and a Java API for XML Web Services
(JAX-WS) 2.0 SEI are very similar. This article addresses the
differences. Even with differences in structure, however, the goal of
providing an interface that reflects the contract of the Web service
is the same.


__________________________________________________________
COMPARING SEI MAPPING

Listing 1 shows the WSDL for a simple HelloWorld Web service.


------------------------------------------------------------
Listing 1. HelloWorld WSDL


xmlns:tns="urn:helloWorld/sample/ibm/com"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" name="HelloWorld"
targetNamespace="urn:helloWorld/sample/ibm/com">

xmlns:tns="urn:helloWorld/sample/ibm/com"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
















































Listing 2 shows the JAX-RPC mapping of the Java SEI from this WSDL
without the method signatures (you will see more about those later).


------------------------------------------------------------
Listing 2. JAX-RPC HelloWorld SEI

package com.ibm.samples;
public interface HelloWorld extends java.rmi.Remote {
...
}


Listing 3 shows the JAX-WS SEI for the same WSDL.


------------------------------------------------------------
Listing 3. JAX-WS HelloWorld SEI

package com.ibm.samples.helloworld;

import javax.jws.WebService;

@WebService(name = "HelloWorld", targetNamespace = "urn:samples.ibm.com/HelloWorld")
public interface HelloWorld {
...
}


There are three differences here:


- Package: The target namespace is "urn:helloWorld/sample/ibm/com".
Both mappings take the domain name-like string and reverse the
order of the elements. JAX-RPC's mapping stops at the first slash.
JAX-WS's mapping continues with the string, adding the information
after the first slash. Both specifications allow for custom
namespace-to-package mappings.

- Annotations: JAX-WS requires that all SEIs include the @WebService
annotation. As mentioned in Part 1 of this series, JAX-WS includes
support for the annotations defined in JSR-181 Web Services Metadata.

- java.rmi.Remote: The JAX-RPC SEI extends the java.rmi.Remote
interface. JAX-WS no longer requires this.

Before moving into the details of operation mappings, there is one
last thing about the SEI itself. Although JAX-WS provides support for
Web services that have an SEI, this is not mandatory for all services.
With JAX-WS, a JavaBean can be deployed on its own as a Web service
implementation, as opposed to JAX-RPC where the bean must include an
SEI. JAX-WS services deployed without an SEI are considered to have an
implicit SEI.


__________________________________________________________
COMPARING OPERATION MAPPING

Now that you have seen the interfaces, look at the comparison of how
the operations are mapped. There are different ways of designing a WSDL
document to represent Web services that have similar semantics. The
article "Which style of WSDL should I use?" provides an overview of the
different styles of WSDL documents available and how to determine which
is best for you.
http://www.ibm.com/developerworks/webservices/library/ws-whichwsdl/

Now, look at how JAX-RPC and JAX-WS map to each of the WSDL styles.


__________________________________________________________
EXPLORING THE DOCUMENT/LITERAL WRAPPED PATTERN

The WSDL in Listing 1 is formatted using the document/literal wrapped
pattern. Listings 4 and 5 are mappings for the same wrapped operation
in JAX-RPC and JAX-WS. Notice that JAX-WS adds the @RequestWrapper and
@ResponseWrapper annotations to the method. These provide additional
metadata about both the elements that will serve as the operation
wrapper along with any Java beans that might have been generated for
those wrapper elements. These annotations are optional.


------------------------------------------------------------
Listing 4. JAX-RPC complete HelloWorld SEI

package com.ibm.samples;

public interface HelloWorld extends java.rmi.Remote {
public java.lang.String hello(java.lang.String name) throws java.rmi.RemoteException;
}


------------------------------------------------------------
Listing 5. JAX-WS complete HelloWorld SEI

package com.ibm.samples.helloworld;

import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebResult;
import javax.jws.WebService;
import javax.xml.ws.RequestWrapper;
import javax.xml.ws.ResponseWrapper;

@WebService(name = "HelloWorld", targetNamespace = "urn:samples.ibm.com/HelloWorld")
public interface HelloWorld {

@WebMethod(action = "urn:samples.ibm.com/HelloWorld/hello")
@WebResult(name = "response", targetNamespace = "")
@RequestWrapper(localName = "hello",
targetNamespace = "urn:samples.ibm.com/HelloWorld",
className = "com.ibm.samples.helloworld.Hello")
@ResponseWrapper(localName = "helloResponse",
targetNamespace = "urn:samples.ibm.com/HelloWorld",
className = "com.ibm.samples.helloworld.HelloResponse")
public String hello(
@WebParam(name = "name", targetNamespace = "")
String name);
}


As you can see, the JAX-WS mapping again has a lot of annotations, but
when you get down to the root signature, the only difference is that
the JAX-RPC method can throw java.rmi.RemoteException while the JAX-WS
method is not defined to do so.


__________________________________________________________
EXPLORING DOCUMENT/LITERAL PATTERNS

Both JAX-RPC and JAX-WS support mapping operations that are
document/literal, but are not wrapped. To accomplish this with the
HelloWorld sample, you would need to remove the wrapper elements that
represent the operation name. Listing 6 shows what the relevant
portions of the WSDL document would look like in comparison to the WSDL
in Listing 1.


------------------------------------------------------------
Listing 6. Document/literal WSDL


xmlns:tns="urn:helloWorld/sample/ibm/com"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">














Now look at the Java mapping for this new WSDL. Listings 7 and 8 show
the JAX-RPC and JAX-WS mappings respectively. Do you see how similar
the JAX-RPC mapping is? The only difference is the parameter name. As
with the previous case, putting the annotations aside, there is no
real difference between the JAX-RPC mapping and the JAX-WS mapping.


------------------------------------------------------------
Listing 7. JAX-RPC document/literal mapping

public interface HelloWorld extends java.rmi.Remote {
public java.lang.String hello(java.lang.String helloParameters)
throws java.rmi.RemoteException;
}


------------------------------------------------------------
Listing 8. JAX-WS document/literal mapping

@WebService(name = "HelloWorld", targetNamespace = "urn:helloWorld/sample/ibm/com")
@SOAPBinding(parameterStyle = ParameterStyle.BARE)
public interface HelloWorld {

@WebMethod(action = "urn:helloWorld/sample/ibm/com/hello")
@WebResult(name = "helloResponse",
targetNamespace = "urn:helloWorld/sample/ibm/com",
partName = "helloResult")
public String hello(
@WebParam(name = "hello",
targetNamespace = "urn:helloWorld/sample/ibm/com",
partName = "helloParameters")
String helloParameters);

}


Notice that for JAX-WS, you no longer see the @RequestWrapper and
@ResponseWrapper annotations. Also note that a new annotation appears
at the interface level as well, @SOAPBinding. This annotation provides
information about the parameter style. If absent, the default value for
the parameterStyle attribute is wrapped, which would be like the WSDL
in Listing 1.


__________________________________________________________
EXPLORING THE RPC/LITERAL PATTERN

The next example is somewhat different from the previous two. With an
RPC/literal style WSDL, the parts are defined in terms of types rather
than elements. Listing 9 contains the relevant WSDL differences.


------------------------------------------------------------
Listing 9. RPC/literal WSDL changes












The Java mappings in Listings 10 and 11 reflect the changes to the
WSDL. Again, you see an identical mapping when the annotations are
stripped away.


------------------------------------------------------------
Listing 10. JAX-RPC RPC/literal mapping

public interface HelloWorld extends java.rmi.Remote {
public java.lang.String hello(java.lang.String helloParameters)
throws java.rmi.RemoteException;
}


------------------------------------------------------------
Listing 11. JAX-WS RPC/Literal mapping

@WebService(name = "HelloWorld", targetNamespace = "urn:helloWorld/sample/ibm/com")
@SOAPBinding(style = Style.RPC)
public interface HelloWorld {

@WebMethod(action = "urn:helloWorld/sample/ibm/com/hello")
@WebResult(name = "helloResult", partName = "helloResult")
public String hello(
@WebParam(name = "helloParameters", partName = "helloParameters")
String helloParameters);

}


Comparing this JAX-WS interface to the previous, you see that the
@SOAPBinding annotation remains, but now it is not used for the
parameter style, but rather the WSDL style.


__________________________________________________________
EXPLORING THE RPC/ENCODED PATTERNS

There is no comparison for RPC/encoded style operations that can be
made. JAX-WS does not support any mappings for WSDL documents that
contain an encoded representation for the data. This comes from
JAX-WS's compliance with WS-I's Basic Profile 1.1, which does not
allow usage of encoded WSDL documents. There are good reasons to build
an RPC/encoded Web service, in which case you should stick with the
JAX-RPC mappings, but if you want to write interoperable Web services,
you should not use RPC/encoded.


__________________________________________________________
CONSIDERING OTHER DIFFERENCES

A major difference in operation mapping for JAX-WS over JAX-RPC is the
introduction of asynchronous operations. Any WSDL operation with a
two-way message flow, or one where the client expects to receive a
response, can be mapped to an asynchronous Java representation. There
are two different mechanisms, asynchronous with a callback and
asynchronous polling, that require two different mappings. A future
article will describe how these two types of operations work. This
article just shows you an example. Listing 12 contains an asynchronous
callback operation, where the javax.xml.ws.AsyncHandler object is the
callback object. Listing 13 contains an asynchronous polling operation
mapping.


------------------------------------------------------------
Listing 12. JAX-WS asynchronous callback

@WebMethod(action = "urn:samples.ibm.com/HelloWorld/hello")
@RequestWrapper(localName = "hello",
targetNamespace = "urn:samples.ibm.com/HelloWorld",
className = "com.ibm.samples.helloworld.Hello")
@ResponseWrapper(localName = "helloResponse",
targetNamespace = "urn:samples.ibm.com/HelloWorld",
className = "com.ibm.samples.helloworld.HelloResponse")
public Future helloAsync(
@WebParam(name = "name", targetNamespace = "")
String name,
@WebParam(name = "asyncHandler", targetNamespace = "")
AsyncHandler asyncHandler);


------------------------------------------------------------
Listing 13. JAX-WS asynchronous polling

@WebMethod(action = "urn:samples.ibm.com/HelloWorld/hello")
@RequestWrapper(localName = "hello",
targetNamespace = "urn:samples.ibm.com/HelloWorld",
className = "com.ibm.samples.helloworld.Hello")
@ResponseWrapper(localName = "helloResponse",
targetNamespace = "urn:samples.ibm.com/HelloWorld",
className = "com.ibm.samples.helloworld.HelloResponse")
public Response helloAsync(
@WebParam(name = "name", targetNamespace = "")
String name);


There is no asynchronous mapping for WSDL operations in JAX-RPC, so
you do not have anything to make a comparison to here. One important
note, however, is that the asynchronous mappings only apply to the
client side. No such asynchronous mappings exist for service endpoints,
only for clients.


__________________________________________________________
COMPARING IN/OUT PARAMETERS

Both JAX-RPC and JAX-WS support parameters known as IN/OUT parameters.
In Listing 14, you see an IN/OUT parameter added to the WSDL from
Listing 1. Notice that the parameter with the name "inout" appears in
both the input and the output. In this scenario, both JAX-RPC and
JAX-WS map that parameter to a holder parameter, but the impact this
has is different for each mapping.


------------------------------------------------------------
Listing 14. A WSDL with an IN/OUT parameter




















Listing 15 has the JAX-RPC mapping for a holder parameter, and Listing
16 has the JAX-WS mapping.


------------------------------------------------------------
Listing 15. JAX-RPC SEI with IN/OUT parameters

public interface HelloWorld extends java.rmi.Remote {
public java.lang.String hello(
java.lang.String name,
javax.xml.rpc.holders.StringHolder inout) throws java.rmi.RemoteException;
}


------------------------------------------------------------
Listing 16. JAX-WS SEI with IN/OUT parameters

@WebService(name = "HelloWorld", targetNamespace = "urn:helloWorld/sample/ibm/com")
public interface HelloWorld {

@WebMethod(action = "urn:helloWorld/sample/ibm/com/hello")
@RequestWrapper(localName = "hello",
targetNamespace = "urn:helloWorld/sample/ibm/com",
className = "helloworld.sample.ibm.com.Hello")
@ResponseWrapper(localName = "helloResponse",
targetNamespace = "urn:helloWorld/sample/ibm/com",
className = "helloworld.sample.ibm.com.HelloResponse")
public void hello(
@WebParam(name = "name", targetNamespace = "")
String name,
@WebParam(name = "inout", targetNamespace = "", mode = Mode.INOUT)
Holder inout,
@WebParam(name = "response", targetNamespace = "", mode = Mode.OUT)
Holder response);

}


For JAX-RPC, there are a set of classes defined by the specification
as holder classes for known types. These include types like
java.lang.String and other primitive types. For user-defined types,
JAX-RPC requires that custom holder classes be generated that can
handle the user-defined types. JAX-WS, on the other hand, makes use of
the Generics feature in Java 5 to provide a single class that can work
for all types, including user-defined types.

Another interesting thing to note here is the difference in return
types. Rather than keeping the return type as JAX-RPC does, JAX-WS
makes the method void and makes use of the holder for what was the
return value. By rule in JAX-WS, when there is more than one parameter
that can be considered an OUT parameter for an operation, the return
type must be void, and all OUT parameters are mapped to holder types.


__________________________________________________________
SUMMARY

The above examples illustrate that, while there are a number of
differences between JAX-RPC and JAX-WS, the mapping from WSDL to the
structure of a service endpoint interface is very similar. The key
differences are:

- The package names are different.

- JAX-RPC requires java.rmi.Remote and java.rmi.RemoteException, which
JAX-WS does not.

- Holders are defined differently.

Even with all the similarities that exist, there is one major
difference that makes the JAX-WS SEI a very different entity from the
JAX-RPC one. The use of JSR-181 annotations gives the JAX-WS SEI the
capability to not only represent the Java-centric view of the Web
service, but also the WSDL-centric view. A number of the annotations
included are used to map the Java information back to WSDL constructs.
This information does not exist in any form in a JAX-RPC SEI. Some of
the other things that are exclusive to JAX-WS are the asynchronous
invocation model and the fact that it does not require a generated SEI
in the first place. On the other hand, JAX-RPC has something that
JAX-WS does not: It supports an RPC/encoded WSDL.


======================================================
LINKS TO OTHER GOOD STUFF

::: Resources related to this tip :::
http://www.ibm.com/developerworks/webservices/library/ws-tip-jaxwsrpc3/index.html#resources

::: Full text of this tip on the Web :::
http://www.ibm.com/developerworks/webservices/library/ws-tip-jaxwsrpc3/index.html?ca=dnx-712

::: Read the other articles in this series :::
http://www.ibm.com/developerworks/search/searchResults.jsp?searchType=1&searchSite=dW&searchScope=webservZ&query=Web+services+hints+and+tips%3A+JAX-RPC+JAX-WS&Search.x=42&Search.y=11&Search=Search

::: IBM developerWorks SOA and Web services zone :::
http://www.ibm.com/developerworks/webservices/?ca=dnx-712

::: IBM developerWorks XML zone :::
http://www.ibm.com/developerworks/xml/?ca=dnx-712

::: developerWorks weekly edition archives :::
http://ibm.com/developerworks/newsletter/nl-weekly-archive.html?ca=dnx-712

==========================================================
ABOUT THIS NEWSLETTER
Created by IBM developerWorks
3039 Cornwallis Rd., P.O. Box 12195, Research Triangle Park, NC 27709
http://www.ibm.com/developerworks/
Delivered by Topica
http://www.topica.com/index.html
==========================================================
Subscribe to developerWorks newsletters:
http://www.ibm.com/developerworks/newsletter/
Get help:
mailto:customersupport@ibm.email-publisher.com
Send comments:
https://www.ibm.com/developerworks/secure/feedback.jsp
IBM's privacy policy:
http://www.ibm.com/privacy/
IBM's copyright and trademark information:
http://www.ibm.com/legal/copytrade.phtml

THIS NEWSLETTER IS FOR INFORMATION ONLY. This newsletter should not be
interpreted to be a commitment on the part of IBM, and, after the
publication date, IBM cannot guarantee the accuracy of any information
presented. You may copy and distribute this newsletter, as long as:

1. All text is copied without modification and all pages are included.
2. All copies contain IBM's copyright notice and any other notices
provided therein.
3. This document is not distributed for profit.


====================================================================
***:
http://topica.com/f***/aaadu2c9h92ih7i2y9imkqz7yuvykdmj9d14pigm4yi7zb
Update Your Profile:
http://topica.com/f/?a84vCg.aCgq9o.dGF5bGxv
Confirm Your Subscription:
http://topica.com/f/?a84vCg.aCgq9o.dGF5bGxv.c