Web services hints and tips: JAX-RPC versus JAX-

WS, Part 1
Introduction
Introduction
Web services have been around a while now. First there was SOAP. But SOAP only described what the messages looked
like. Then there was WSDL. But WSDL didn't tell you how to write web services in Java™. Then along came JAX-RPC 1.0.
After a few months of use, the Java Community Process (JCP) folks who wrote that specification realized that it needed a
few tweaks, so out came JAX-RPC 1.1. After a year or so of using that specification, the JCP folks wanted to build a better
version: JAX-RPC 2.0. A primary goal was to align with industry direction, but the industry was not merely doing RPC web
services, they were also doing message-oriented web services. So "RPC" was removed from the name and replaced with
"WS" (which stands for web Services, of course). Thus the successor to JAX-RPC 1.1 is JAX-WS 2.0 - the Java API for XML-
based web services.
What remains the same?
Before we itemize the differences between JAX-RPC 1.1 and JAX-WS 2.0, we should first discuss what is the same.
 JAX-WS still supports SOAP 1.1 over HTTP 1.1, so interoperability will not be affected. The same messages can
still flow across the wire.
 JAX-WS still supports WSDL 1.1, so what you've learned about that specification is still useful. A WSDL 2.0
specification is nearing completion, but it was still in the works at the time that JAX-WS 2.0 was finalized.
What is different?
 SOAP 1.2
JAX-RPC and JAX-WS support SOAP 1.1. JAX-WS also supports SOAP 1.2.
 XML/HTTP
The WSDL 1.1 specification defined an HTTP binding, which is a means by which you can send XML messages
over HTTP without SOAP. JAX-RPC ignored the HTTP binding. JAX-WS adds support for it.
 WS-I's Basic Profiles
JAX-RPC supports WS-I's Basic Profile (BP) version 1.0. JAX-WS supports BP 1.1. (WS-I is the web services
interoperability organization.)
 New Java features
o JAX-RPC maps to Java 1.4. JAX-WS maps to Java 5.0. JAX-WS relies on many of the features new in
Java 5.0.
o Java EE 5, the successor to J2EE 1.4, adds support for JAX-WS, but it also retains support for JAX-
RPC, which could be confusing to today's web services novices.
 The data mapping model
o JAX-RPC has its own data mapping model, which covers about 90 percent of all schema types. Those
that it does not cover are mapped to javax.xml.soap.SOAPElement.
o JAX-WS's data mapping model is JAXB. JAXB promises mappings for all XML schemas.
 The interface mapping model
JAX-WS's basic interface mapping model is not extensively different from JAX-RPC's; however:
o JAX-WS's model makes use of new Java 5.0 features.
o JAX-WS's model introduces asynchronous functionality.
 The dynamic programming model
o JAX-WS's dynamic client model is quite different from JAX-RPC's. Many of the changes acknowledge
industry needs:
 It introduces message-oriented functionality.
 It introduces dynamic asynchronous functionality.
o JAX-WS also adds a dynamic server model, which JAX-RPC does not have.
 MTOM (Message Transmission Optimization Mechanism)
JAX-WS, via JAXB, adds support for MTOM, the new attachment specification. Microsoft never bought into the
SOAP with Attachments specification; but it appears that everyone supports MTOM, so attachment interoperability
should become a reality.
 The handler model
o The handler model has changed quite a bit from JAX-RPC to JAX-WS.
o JAX-RPC handlers rely on SAAJ 1.2. JAX-WS handlers rely on the new SAAJ 1.3 specification.
In the remainder of this tip, we will discuss SOAP 1.2, XML/HTTP, the WS-I Basic Profiles, and Java 5. Each of the
remaining five bullets above will be a separate tip in this series.
SOAP encoding
SOAP encoding has fallen out of favor in the web services community. It is not supported
by the WS-I basic profile. So JAX-WS, as the latest incarnation of Java web services, has
disallowed SOAP encoding. JAX-RPC supports SOAP encoding, so if you really must
use SOAP encoded messages, stick with JAX-RPC.
SOAP 1.2
There is really not a lot of difference, from a programming model point of view, between SOAP 1.1 and SOAP 1.2. As a Java
programmer, the only place you will encounter these differences is when using the handlers, which we will cover in a future
tip. SAAJ 1.3 has been updated to support SOAP 1.2.
XML/HTTP
Like the changes for SOAP 1.2, there is really not a lot of difference, from a programming model point of view, between
SOAP/HTTP and XML/HTTP messages. As a Java programmer, the only place you will encounter these differences is when
using the handlers, which we will cover in a future tip. The HTTP binding has its own handler chain and its own set of
message context properties.
WS-I's basic profiles
JAX-RPC 1.1 supports WS-I's Basic Profile (BP) 1.0. Since that time, the WS-I folks have developed BP 1.1 (and the
associated AP 1.0 and SSBP 1.0). These new profiles clarify some minor points, and more clearly define attachments. JAX-
WS 2.0 supports these newer profiles. For the most part, the differences between them do not affect the Java programming
model. The exception is attachments. WS-I not only cleared up some questions about attachments, but they also defined
their own XML attachment type: wsi:swaRef.
Many people are confused by all these profiles. You will need a little history to clear up the confusion.
WS-I's first basic profile (BP 1.0) did a good job of clarifying the various specs. But it wasn't perfect. And support for SOAP
with Attachments (Sw/A) in particular was still rather fuzzy. In their second iteration, the WS-I folks pulled attachments out of
the basic profile - BP 1.1 - and fixed some of the things they missed the first time around. At that point they also added two
mutually exclusive supplements to the basic profile: AP 1.0 and SSBP 1.0. AP 1.0 is the Attachment Profile which describes
how to use Sw/A. SSBP 1.0 is the Simple SOAP Binding Profile, which describes a web services engine that does not
support Sw/A (such as Microsoft's .NET). The remaining profiles that WS-I has and is working on build on top of those basic
profiles.
Java 5
There are a number of changes to the Java language. JAX-WS relies on: annotations, generics, and executors. We will detail
exactly how JAX-WS relies on this new functionality in follow-on tips. For information on these new features of Java, see the
Java 5 link in Resources.
Summary
JAX-WS 2.0 is the successor to JAX-RPC 1.1. There are some things that haven't changed, but most of the programming
model is different to a greater or lesser degree. The topics introduced in this tip will be expanded upon in a series of tips
which we will publish over the coming months that will compare, in detail, JAX-WS and JAX-RPC. At a high level though,
here are a few reasons why you would or would not want to move to JAX-WS from JAX-RPC.
Reasons you may want to stay with JAX-RPC 1.1:
 If you want to stay with something that's been around a while, JAX-RPC will continue to be supported for some
time to come.
 If you don't want to step up to Java 5.
 If you want to send SOAP encoded messages or create RPC/encoded style WSDL.
Reasons to step up to JAX-WS 2.0:
 If you want to use the new message-oriented APIs.
 If you want to use MTOM to send attachment data.
 If you want better support for XML schema through JAXB.
 If you want to use an asynchronous programming model in your web service clients.
 If you need to have clients or services that can handle SOAP 1.2 messages.
 If you want to eliminate the need for SOAP in your web services and just use the XML/HTTP binding.
 If you like playing with leading edge technology.

Web services hints and tips: JAX-RPC versus JAX-

WS, Part 2
A look at the differences in data mapping
Introduction
While some aspects of JAX-WS 2.0 are merely evolutionary to JAX-RPC 1.1, other parts are revolutionary. For example,
JAX-WS does not provide mapping between XML schema and Java, a major feature of JAX-RPC 1.1. Instead, JAX-WS uses
another JCP-defined technology, JAXB (the Java Architecture for XML Binding) 2.0, to do its data mapping for it. JAX-WS
simply represents the invocation model for Web services. It no longer concerns itself with the Java Beans that represent
application data; it only focuses on delivering them to the target Web service. Here, we'll compare JAX-RPC 1.1 and the
JAXB 2.0 mappings.

Back to top
Mapping XML schema to Java
JAX-RPC and JAXB
Why didn't JAX-RPC use JAXB in the first place? The answer is timing. The first version
of JAX-RPC was completed before JAXB, so rather than wait, the writers of JAX-RPC
developed their own mapping feature.
Mapping XML names to Java names in JAX-RPC and JAX-WS/JAXB are essentially the same, while mapping simple types
has some slight differences. Table 1 shows these differences, which may appear significant; however, except for date/time
types, they're the least-used XML simple types.

Table 1. Mapping differences between JAX-RPC 1.1 and JAXB 2.0 for XML simple
types
Type JAX-RPC 1.1 JAXB 2.0

xsd:anySimpleType java.lang.String java.lang.Object

xsd:duration java.lang.String javax.xml.datatype.Duration (new type)

xsd:dateTime java.util.Calendar javax.xml.datatype.XMLGregorianCalendar (new type)

xsd:time java.util.Calendar javax.xml.datatype.XMLGregorianCalendar

xsd:date java.util.Calendar javax.xml.datatype.XMLGregorianCalendar

xsd:gYearMonth java.lang.String javax.xml.datatype.XMLGregorianCalendar

xsd:gYear java.lang.String javax.xml.datatype.XMLGregorianCalendar

xsd:gMonthDay java.lang.String javax.xml.datatype.XMLGregorianCalendar

xsd:gMonth java.lang.String javax.xml.datatype.XMLGregorianCalendar

xsd:gDay java.lang.String javax.xml.datatype.XMLGregorianCalendar

xsd:anyURI java.net.URI java.lang.String

xsd:NMTOKENS java.lang.String[] java.util.List<java.lang.String>

xsd:IDREF java.lang.String java.lang.Object

xsd:IDREFS java.lang.String[] java.util.List<java.lang.Object>

xsd:ENTITY not supported java.lang.String

xsd:ENTITIES not supported java.util.List<java.lang.String>

The pure Java aspects of the simple type mappings are nearly the same between JAX-RPC and JAXB, but the JAXB
mappings also use the new Java annotation feature. See Listings 1 through 3 for some examples of simple type mappings.

Listing 1. XML complexType elements and attributes

<xsd:sequence> <xsd:element name="intField" type="xsd:int"/>
<xsd:element name="intMinField" type="xsd:int" minOccurs="0"/> <xsd:element
name="intNilField" type="xsd:int" nillable="true"/> <xsd:element
name="stringField" type="xsd:string"/> <xsd:element name="stringMinField"
type="xsd:string" minOccurs="0"/> <xsd:element name="stringNilField"
type="xsd:string" nillable="true"/> </xsd:sequence> <xsd:attribute
name="intAttr" type="xsd:int"/> <xsd:attribute name="intAttrReq"
type="xsd:int" use="required"/>

Listing 2. Mapping to Java Bean properties via JAX-RPC 1.1

private int intField; private Integer intMinField; private
Integer intNilField; private String stringField; private String
stringMinField; private String stringNilField; private Integer intAtt;
private int intAttReq;

Listing 3. Mapping to Java Bean properties via JAXB 2.0

protected int intField; protected Integer intMinField;
@XmlElement(required = true, type = Integer.class, nillable = true)
protected Integer intNilField; @XmlElement(required = true) protected
String stringField; protected String stringMinField;
@XmlElement(required = true, nillable = true) protected String
stringNilField; @XmlAttribute protected Integer intAtt;
@XmlAttribute(required = true) protected int intAttReq;

In a JAX-RPC 1.1-generated Java Bean, you cannot tell the difference between:
 An element field and an attribute field
 A field mapped from minOccurs="0" type="xsd:int" and a field mapped from nillable="true"
type="xsd:int"
 A field mapped from type="xsd:string" and type="xsd:string" minOccurs="0"
But now you can, thanks to JAXB's use of new Java annotations. The @XmlElement and @XmlAttribute annotations
have several parameters. The ones pertinent to this article include:
 Required: Must the element exist? For example, is minOccurs something other than one?
 Nillable: Does the field contain the nillable="true" attribute?
Mapping arrays
Mapping arrays from XML to Java differs between JAX-RPC and JAXB because JAXB uses the new generic Java feature, as
Listings 4 through 6 show.

Listing 4. XML array

<xsd:element name="intArrayField" type="xsd:int" minOccurs="0"
maxOccurs="unbounded"/>

Listing 5. Mapping to Java Bean properties via JAX-RPC 1.1

private int[] intArrayField; public int[] getIntArrayField() {...}
public void setIntArrayField(int[] intArrayField) {...} public int
getIntArrayField(int i) {...} public void setIntArrayField(int i, int value)
{...}

Listing 6. Mapping to Java Bean properties via JAXB 2.0

@XmlElement(type = Integer.class) protected List<Integer>
intArrayField; public List<Integer> getIntArrayField() {...}

Notice the differences in the accessor methods. The JAX-RPC mapping follows the strict definition of Java Bean array
accessors. The JAXB mapping does not map to an array, so it slightly differs. getIntArrayField returns a reference, not
just a snapshot, to the live list. Therefore, any modification you make to the returned list will be present inside the property.
This is why no setmethod exists for 'array' properties.
Mapping complex types
Mapping a complexType is nearly the same between JAX-RPC and JAXB, except the fields are private in JAX-RPC and
protected in JAXB, and the JAXB mapping adds annotations describing the field order. See Listings 7 through 9 for an
example and comparisons between the two mappings.

Listing 7. XML schema complexType

<xsd:element name="Phone" type="tns:Phone"/> <xsd:complexType
name="Phone"> <xsd:sequence> <xsd:element name="areaCode"
type="xsd:string"/> <xsd:element name="exchange" type="xsd:string"/>
<xsd:element name="number" type="xsd:string"/> </xsd:sequence>
</xsd:complexType>

Listing 8. JAX-RPC 1.1 mapping of complexType

public class Phone { private String areaCode; private String exchange;
private String number; ... }
Listing 9. JAXB 2.0 mapping of complexType
@XmlType(name = "Phone", propOrder = { "areaCode", "exchange",
"number" }) public class Phone { @XmlElement(required = true) protected
String areaCode; @XmlElement(required = true) protected String exchange;
@XmlElement(required = true) protected String number; ... }

Note that the schema in Listing 7 used xsd:sequence. If it had used xsd:all instead, the propOrder annotation would
have been empty: @XmlType(name = "Phone", propOrder = {}).
The new ObjectFactory class
JAXB generates a file that JAX-RPC does not: ObjectFactory. Each directory containing Java Beans will have
oneObjectFactory. For each type defined in the schema's corresponding namespace, the ObjectFactory class will have
a create method for that type. For each element, the ObjectFactory class will have a create element method, which
returns ajavax.xml.bind.JAXBElement<Type>. For example, for the Phone schema in Listing 7, Listing 10 shows
the generatedObjectFactory class with a method that returns an instance of Phone and a method that returns an
instance ofJAXBElement<Phone>. You can still directly instantiate the Java Beans in the directory, but it would be best
to use the factory.

Listing 10. JAXB 2.0 ObjectFactory for Phone

import javax.xml.bind.JAXBElement; import
javax.xml.bind.annotation.XmlElementDecl; import javax.xml.namespace.QName;
public class ObjectFactory { private final static QName _Phone_QNAME = new
QName ("urn:types.MyServiceSample.ibm.com", "Phone"); public
ObjectFactory() {...} public Phone createPhone() {...}
@XmlElementDecl(namespace = "urn:types.MyServiceSample.ibm.com", name = "Phone")
public JAXBElement<Phone> createPhone(Phone value) {...} }

Back to top
Java to XML schema mappings
With a judicious sprinkling of these new JAXB-defined annotations, Java can map in a well-directed manner to XML,
essentially in the reverse of the XML-to-Java mappings that we have presented. But what about unannotated Java?
Mapping Java names to XML names in JAX-RPC and JAXB are essentially the same. That is, Java primitive types map to
the same XML schema whether the mapping follows JAX-RPC or JAXB. JAX-RPC defines a small set of standard Java
classes that map to XML. For all but one of those, JAXB maps precisely the same, but JAXB adds a few more to its list of
mapped classes, as Table 2 shows.

Table 2. Mapping differences between JAX-RPC 1.1 and JAXB 2.0 for standard
Java classes
Type JAX-RPC 1.1 JAXB 2.0

java.lang.String xsd:string xsd:string

java.math.BigInteger xsd:integer xsd:integer

java.math.BigDecimal xsd:decimal xsd:decimal

java.util.Calendar xsd:dateTime xsd:dateTime

java.util.Date xsd:dateTime xsd:dateTime

javax.xml.namespace.QName xsd:QName xsd:QName

java.net.URI xsd:anyURI xsd:string

javax.xml.datatype.XMLGregorianCalendar n/a xsd:anySimpleType

javax.xml.datatype.Duration n/a xsd:duration

java.lang.Object n/a1 xsd:anyType

java.awt.Image n/a2 xsd:base64Binary

javax.activation.DataHandler n/a2 xsd:base64Binary

javax.xml.transform.Source n/a2 xsd:base64Binary

java.util.UUID n/a xsd:string

Table 2 Notes:
1. Some vendors mapped java.lang.Object to xsd:anyType.
2. In JAX-RPC, this is mapped to a mime binding type - the XML type is undefined.
Back to top
Conclusion
We've compared the mappings of JAX-RPC 1.1 and JAXB 2.0. They are similar with some notable exceptions:
 XML to Java:
o A few of the simple types are mapped differently
o JAXB adds the ObjectFactory class
o JAXB makes use of the new Java language annotation feature and generic feature
 Java to XML:
o The primitive type mappings are identical
o The standard Java mappings are nearly identical
We can say much more about the JAXB 2.0 specification, particularly its use of Java annotations, but that topic is out of this
article's scope. For more information about JAXB 2.0, see Resources.