8.7 J2EE 1.4 JAX-RPC Mapping File | Java Web Services in a Nutshell

8.7.1 Availability

All J2EE 1.4 platforms.

8.7.2 Description

Every web service deployed on the J2EE 1.4 platform must have an associated mapping that describes how the namespaces, port types, operations, exceptions, and data types defined in the WSDL definition of the service are to be mapped to Java language packages, interfaces, methods , exception classes, and primitive or object types. In the simplest cases, it is permissible to specify only the namespace to package mapping, allowing everything else to be defaulted according to built-in rules for the WSDL to JAX-RPC mapping described in the JAX-RPC specification.

The JAX-RPC mapping file does not have a fixed name . Instead, its location is given by the wsdl-file element in the webservices .xml file in the same J2EE module. The J2EE 1.4 reference implementation allows a model file to be used instead of a mapping file. This is extremely convenient because the model file can be created automatically from a WSDL definition. Since the mapping file is complex, it is likely that other vendors will provide tool-based support for creating it.

The content of the JAX-RPC mapping file is defined by an XML Schema document that can be downloaded from http://www.ibm.com/webservices/xsd/j2ee_jaxrpc_mapping_1_1.xsd. Example 8-14 shows the elements that appear at the two outer-most nesting levels of this document.

Example 8-14. The JAX-RPC mapping file

 <java-wsdl-mapping>   <package-mapping/>               <!-- One or more  - see text -->   <java-xml-type-mapping/>         <!-- Zero or more - see text -->   <exception-mapping/>             <!-- Zero or more - see text -->   <!-- Any number of the next two elements may appear -->      <service-interface-mapping>      <! -- Zero or one may appear - see text -->   <service-endpoint-interface-mapping> <!-- One or more -- see text --> </java-wsdl-mapping>

At the time of this writing, the beta release of J2EE Version 1.4 supports only the package-mapping element of this file; therefore, this section covers only that element. Note that, in most cases, this is the only part of the file that you need to supply. Following the FCS release of J2EE 1.4, updated information on this file will be posted on the web page for this book at O'Reilly's web site (http://www.oreilly.com/catalog/javawsian).

8.7.2.1 Package mappings

The package-mapping element describes the correspondence between namespaces used in the WSDL file and the Java packages in which the classes for the objects in those namespaces should be generated. The structure of the package-mapping element is shown in Example 8-15.

Example 8-15. The package-mapping element in the JAX-RPC mapping file

 <package-mapping>     <package-type>Java package</package-type>     <namespaceURI>namespace</namespaceURI> </package-mapping>

There should be one package-mapping element for each namespace from which Java objects will be generated. The most common case would require an element that maps the namespace given by the targetNamespace attribute of the definitions element in the WSDL file. If the types defined or imported by the WSDL file have a different targetNamespace , and those types require the generation of Java classes, then a mapping should also be included for each such namespace. In the case of the book web service from Chapter 2, for example, the types element uses a different namespace from that of the definitions themselves :

 <definitions name="BookService"  targetNamespace="urn:jwsnut.chapter2.bookservice/wsdl/                    BookQuery  " ... >   <types>     <schema  targetNamespace=               "urn:jwsnut.chapter2.bookservice/types/BookQuery  "  ...>

Since there are two different namespaces, to create a Java implementation of this web service and deploy it on the J2EE 1.4 platform, you need to include a JAX-RPC mapping file with two package-mapping elements:

 <package-mapping>     <package-type>ora.jwsnut.chapter2.bookservice</package-type>     <namespaceURI>urn:jwsnut.chapter2.bookservice/wsdl/BookQuery</ namespaceURI> </package-mapping> <package-mapping>     <package-type>ora.jwsnut.chapter2.bookservice</package-type>     <namespaceURI>urn:jwsnut.chapter2.bookservice/types/BookQuery</namespaceURI> </package-mapping>

The extract shown here defines a mapping in which Java objects from both namespaces are created in a package called ora.jwsnut.chapter2.bookservice . It is permissible, however, to use a different Java package for each namespace if you wish to.