Section 12.3. Java Web Services

12.3. Java Web Services

There are several standard APIs for implementing and using web services in Java. The principal ones we'll discuss here are the Java API for XML Remote Procedure Calls (JAX-RPC), the SOAP with Attachments API for Java (SAAJ), and the Web Services for J2EE specification. JAX-RPC and SAAJ are APIs aimed at helping you develop both web services and web service clients. These web service clients might be standalone Java applications or code running within a J2EE application (e.g., JSP or servlet web components, EJBs, etc). The Web Services for J2EE specification describes a standard approach for the packaging and deployment of web services.

Relative to the standard web service protocols discussed earlier (SOAP, WSDL, etc.), JAX-RPC and SAAJ together provide a standard Java framework for consuming SOAP messages from web services and for generating SOAP messages and delivering them to web services. In a sense, you can think of JAX-RPC and SAAJ as being in the same category as other remote object APIs in Java, such as RMI and the Java bindings of CORBA. The web service APIs in Java use a different set of protocols to accomplish their remote object and messaging services.

12.3.1. Mapping SOAP and WSDL to Java

JAX-RPC provides more than just an API for consuming and producing web services. It also defines standard mappings from SOAP and WSDL entities to Java entities and back again. This is a very important asset, since it makes it clear how various web service data types will be represented in Java, and it allows your Java web service clients and implementations to be much more portable across different JAX-RPC and SAAJ implementations.

Table 12-1 shows the JAX-RPC mapping from standard XML Schema data types to Java types. In all of these mappings, the xsd: prefix on an XML type refers to an entity defined in the XML Schema basic data types. Each XML data type has two Java mappings. The first mapping is used by default for that XML type. The second mapping is used if the XML entity is used in a context in which its presence is optional. Examples of these "optional" situations are XML elements that are marked as nillable in their schema, elements whose minOccurs attribute is zero and maxOccurs attribute is nonzero, and attributes whose use attribute is set to optional without specifying a default value.

Table 12-1. JAX-RPC mappings from XML types to Java types

XML type	Java type (default)	Java type if optional in XML
xsd:anySimpleType	java.net.URI (J2SE 1.4 and later) or java.lang.String	Same
xsd:anyURI	java.lang.String	Same
xsd:base64Binary	byte[]	Same
xsd:boolean	boolean	java.lang.Boolean
xsd:byte	byte	java.lang.Byte
xsd:date	java.util.Calendar	Same
xsd:dateTime	java.util.Calendar	Same
xsd:decimal	java.math.BigDecimal	Same
xsd:double	double	java.lang.Double
xsd:float	float	java.lang.Float
xsd:hexBinary	byte[]	Same
xsd:int	int	java.lang.Integer
xsd:integer	java.math.BigInteger	Same
xsd:long	long	java.lang.Long
xsd:QName	javax.xml.namespace.QName	Same
xsd:short	short	java.lang.Short
xsd:string	java.lang.String	Same
xsd:time	java.util.Calendar	Same
xsd:unsignedByte	short	java.lang.Short
xsd:unsignedInt	long	java.lang.Long
xsd:unsignedShort	int	java.lang.Integer

When mapping Java entities into equivalent XML/SOAP entities (e.g., when a Java-based web service is being published), JAX-RPC specifies the mappings shown in Table 12-2. Notice that Java basic data types, like int, and their wrapper classes, like java.lang.Integer, are mapped to the same XML data type, but the wrapper class is mapped with the nillable attribute enabled. A Java int, for example, will be mapped to an XML Schema like this:

     <xsd:element name="myintvar" type="xsd:int"/> 

while a java.lang.Integer will be mapped like this:

     <xsd:element name="myIntegerVar" type="xsd:int" nillable="true"/> 

The nillable attribute for the Object data wrappers allows for the situation in which a null value needs to be mapped from Java to XML.

Table 12-2. JAX-RPC mappings from Java types to XML types

Java type	XML type
java.math.BigDecimal	xsd:decimal
java.math.BigInteger	xsd:integer
boolean	xsd:boolean
java.lang.Boolean	xsd:booleana
byte	xsd:byte
java.lang.Byte	xsd:bytea
java.util.Calendar	xsd:dateTime
java.util.Date	xsd:dateTime
double	xsd:double
java.lang.Double	xsd:doublea
float	xsd:float
java.lang.Float	xsd:floata
int	xsd:int
java.lang.Integer	xsd:inta
long	xsd:long
java.lang.Long	xsd:longa
short	xsd:short
java.lang.Short	xsd:shorta
java.lang.String	xsd:string
javax.xml.namespace.QName	xsd:QName
java.net.URI	xsd:anyURI
a This type has the nillable attribute.

On top of these basic data type mappings, JAX-RPC also specifies how various complex XML types and structures are mapped to Java. Both the SOAP encoding and the WSDL schemas define an XML Array type, and these are mapped to equivalent Java arrays. An <xsd:complexType> structure is mapped to an equivalent JavaBean class whose name is mapped from the name attribute of the complexType, and whose properties are mapped from the elements defined for the complexType using these mappings.

Finally, in addition to these type mappings, JAX-RPC defines a set of standard mappings from WSDL entities to Java entities, as depicted in Figure 12-3. This mapping is used in both directions by a Java web service engine. WSDL entities describing an external web service are mapped into Java entities for use by a Java client of the web service. A Java web service will also have its WSDL description mapped from its interface and implementation classes using this same mapping. A web service engine will typically provide a tool that will implement this mapping. For clients, the tool will read in a WSDL file (either from the network or from a local file) and generate a set of equivalent Java code that can be used by a client to interact with the web service. This generated code serves as a client-side stub, or proxy, for the web service, performing the runtime mapping of standard Java objects, data, and method calls into their equivalent SOAP messages and back again. For service implementations, the tool will parse a set of Java classes that implement a service and generate a WSDL description for the service.

Figure 12-3. JAX-RPC entity mappings from WSDL to Java

12.3.2. Web Service Deployment

The Web Services for J2EE specification sits next to JAX-RPC and SAAJ as a complementary standard, aimed at defining standard approaches for describing web services to Java application servers and for packaging web services for deployment to these application servers. It plays a role for Java-based web services analogous to the deployment descriptors and archive formats defined for web components and EJB components. Describing web services is slightly more complicated, however, since you not only need to tell the application server about the Java elements that make up your web service, but you also need to tell it how to handle the mapping from Java objects to SOAP elements (and vice versa) in cases in which the standard mappings described earlier don't cover everything. Also, web services in Java can be implemented using a handful of different models (an EJB can serve as a web service, and so can a regular Java object running in a web container). Supporting these aspects of Java-based web services makes the deployment of web services in a J2EE environment a bit more involved in some cases.

In the remainder of this chapter, we're going to look at how to write Java clients for web services, how to implement web services in Java, and how to deploy Java-based web services. We're starting with clients because they are the easiestsomeone else has done the hard work of implementing a web service, and you "only" want to interact with it as a client. Writing Java-based web services isn't that much more difficult than writing a client, but deploying a web service in a Java application server involves some extra steps, and various web service engines and application servers introduce their own spin on this process.