8.2 wsdeploy JAX-RPC Deployable Web Archive Generation Utility

8.2 wsdeploy ” JAX-RPC Deployable Web Archive Generation Utility

8.2.1 Availability

Java Web Services Developer's Pack. The nearest equivalents for the J2EE 1.4 platform are the deploytool and j2eec utilities described later in this chapter.

8.2.2 Synopsis

 wsdeploy [options] sourceWarFile

8.2.3 Description

The wsdeploy utility is a command-line tool supplied by the JAX-RPC reference implementation in the JWSDP. Its purpose is to create a web archive (WAR) file that can be deployed into a web container (in which the server-side components of the reference implementation are already installed) from a WAR file that contains implementation-independent components together with configuration information. The location of the source WAR file is provided as a command-line argument. This file must contain the following:

The Java classes that define the service endpoint interface (or interfaces) for the web service. These classes typically appear in the /WEB-INF/classes directory of the archive.
The classes that provide the server-side implementation of the service endpoint interfaces, together with any other classes and resources (e.g., images, sound files, text files) that they depend upon. These classes and resources are placed in the /WEB-INF/classes directory of the archive, or in the /WEB-INF/lib directory if they are packaged in JAR files.
A partial web.xml file for the web application that hosts the web service. This file must appear in the /WEB-INF directory.
A configuration file (called jaxrpc -ri.xml ) from which wsdeploy obtains the information necessary to create the deployable WAR file. This file must appear in the /WEB-INF directory.
Optionally , a model file created by wscompile that provides additional information to wsdeploy .

Separating the process of creating the runtime artifacts required by a specific JAX-RPC server-side implementation from the process of implementing the web service makes it possible for developers to create a single WAR file that can then be processed by different vendor tools to create a deployable archive for any number of target environments. In practice, each such tool is likely to require vendor-specific information to complete the deployment. In the case of wsdeploy , this information is provided in the jaxrpc-ri.xml file, which must be placed in the /WEB-INF directory of the source WAR file and optionally by a model file, the location of which is specified within the jaxrpc-ri.xml file. A portable WAR file that is capable of being processed by more than one vendor's deployment tools would need to supply vendor-dependent information for each tool.

The wsdeploy utility is part of the JWSDP. It is not included in the reference implementation of J2EE 1.4, which uses the J2EE deploytool utility to deploy web services instead.

Note that, despite what its name might imply, wsdeploy does not actually deploy the WAR file that it creates. This step must be performed using the deployment tools provided by the target application server or web container.

8.2.4 Options

The behavior of the wsdeploy utility can be controlled to a limited extent using command-line options. Use of the -o option to specify the full pathname of the deployable WAR file is mandatory; all of the other options are truly optional.

-classpath path
-cp path: Synonymous options that specify a semicolon- (Windows) or colon -separated (Unix) list of directories, JAR, and ZIP files that contain classes that are required in order to compile the artifacts created by wsdeploy . It is not necessary to include the JAR files that contain the class files for the JAX-RPC reference implementation.
-keep: Causes temporary files generated by wsdeploy to be retained. By default, these files are deleted. Temporary files are placed in a system-dependent location, or in the directory given by the -tmpdir option, which is typically used in conjunction with -keep .
-o targetWarFile: Supplies the full pathname of the deployable WAR file that wsdeploy creates. If this file already exists, it is overwritten. The directory in which the WAR file is placed must already exist. This option must be supplied.
-tmpdir dirName: Causes wsdeploy to use the given directory, which must already exist, as the location for its temporary files. If this option is not used, a system-dependent temporary directory is chosen instead. This option is commonly used with -keep in order to retain temporary files for inspection once wsdeploy exits.
-verbose: Prints extra messages that indicate what wsdeploy is doing.
-version: Displays the version number of the wsdeploy utility in use and exits. Any other arguments are ignored.

8.2.5 Configuration File

The wsdeploy utility uses a configuration file called jaxrpc-ri.xml , which must be placed in the /WEB-INF directory of the source archive, to obtain information about the service endpoints of the web service for which it will create a deployable web archive file. All of the elements in the jaxrpc-ri.xml file are defined in the XML namespace associated with the URI http://java.sun.com/xml/ns/jax-rpc/ri/dd, which is usually assigned to be the default namespace.

The general form of the jaxrpc-ri.xml file is shown in Example 8-6 and a typical example will be found in Example 2-15 in Chapter 2.

Example 8-6. The jaxrpc-ri.xml file

 <webServices version="1.0"               targetNamespaceBase="URI"              typeNamespaceBase="URI"              urlPatternBase= "/base">     <!-- Nested endpoint elements -- shown later -->     <!-- Nested endpointMapping elements -- shown later --> </webServices>

The webServices element is always the top-level element in the jaxrpc-ri.xml file. The version attribute is required and, at the time of this writing, must have the value "1.0".

The targetNamespaceBase and typeNamespaceBase attributes supply URIs from which the namespaces for the elements and types associated with the web services in the WAR file are generated. The namespaces for a specific endpoint are formed by appending the endpoint name to the corresponding base name. For example, if the targetNamespaceBase attribute is set to urn:jwsnut.chapter2.bookservice/wsdl/ , then the actual target namespace for a nested endpoint called BookQuery is urn:jwsnut.chapter2.bookservice/wsdl/BookQuery . This must match the targetNamespace attribute assigned in the configuration file supplied to wscompile when creating the client-side artifacts. However, if the endpoint element contains a model attribute (see later in this chapter), both the targetNamespace and typeNamespace are taken from the model file rather than by derivation from the attributes of the webServices element, thus ensuring that the client and server agree. The typeNamespaceBase and targetNamespaceBase attributes may be omitted if each endpoint element in the file has a valid model attribute.

The urlPatternBase attribute is a partial URI used to create the servlet path for those endpoints defined in the jaxrpc-ri.xml file that do not have a corresponding endpoint mapping. See Section 8.2.5.2 later in this chapter for further information. This attribute may be omitted if each endpoint element has a matching endpointMapping element.

8.2.5.1 The endpoint element

The endpoint element defines a single service endpoint interface within a web service. Each endpoint therefore corresponds to a single Java interface. A webServices element may contain more than one endpoint element, in which case each is effectively treated as a separate web service, in the sense that each has its own WSDL definition that defines a service containing that endpoint as its only port. All of the endpoints are, however, managed by the same servlet.

The format of the endpoint element is shown in Example 8-7.

Example 8-7. The endpoint element in the jaxrpc-ri.xml file

 <endpoint name= "name"            displayName= "name"            description= "text"           imp;lementation= "className"           interface="className"           model= "modelFile">     <!-- Optional nested handlerChains element --> </endpoint>

The required name attribute supplies the endpoint name, which should be unique within the file. This name may be used in conjunction with the urlPatternBase attribute of the webServices element to generate the URL used to access the endpoint, or as a key to obtain the URL from the corresponding endpointMapping element if there is one (as described shortly). The optional displayName and description elements supply text that describe the endpoint. At the time of this writing, this information does not appear to be used.

The required implementation attribute supplies the fully qualified name of the web service implementation class (or servant class). This class must implement the methods of the service endpoint interface and must be present in the portable WAR file supplied to wsdeploy .

The required interface attribute supplies the fully qualified name of the Java class that defines the web service endpoint interface. This class must also be present in the portable WAR file.

The optional model attribute can be used to pass a model file created by wscompile to wsdeploy . The model file can reside anywhere in the portable WAR file, but is typically placed in the /WEB-INF directory. The value of this attribute gives the location of the model file relative to the archive. A typical value would, therefore, be /WEB-INF/model . If this attribute is omitted, wsdeploy builds a model file based on the service endpoint interface definition referred to by the interface attribute.

If a model file is not supplied, wsdeploy introspects the Java service endpoint interface definition to discover its methods and the types of its parameters in order to generate the necessary server-side ties and any necessary serializers and deserializers. When a model file is used, this information is obtained directly from the model file. Circumstances under which you would need to supply a model file include the following:

The endpoint interface was originally derived from a WSDL document and you want to preserve the method argument names in the generated code rather than use the type-based names (such as String_1 ) obtained by introspecting the Java interface definition.
The endpoint interface was originally derived from a WSDL document and contains document-style operations. See Section 6.6 for an example.
The type information that can be deduced from the Java interface definition is not sufficient to generate all of the necessary serializers. A typical example of this is the use of abstract types or interfaces in method definitions. In such cases, you use a typeMappingRegistry element containing one or more additionalTypes elements in the wscompile configuration file when creating the client-side artifacts. Since the jaxrpc-ri.xml file does not provide a typesMappingRegistry element, this information must be obtained from the model file created by wscompile . See Section 6.9 for an example.

An endpoint element may contain a nested handlerChains element that configures a server-side chain of SOAP message handlers for the endpoint. The format and use of this element are described in Section 8.1.5.4 in the description of the wscompile utility, earlier in this chapter.

8.2.5.2 The endpointMapping element

This optional element specifies the URL mapping for an endpoint configured using an endpoint element. Its format is shown in Example 8-8.

Example 8-8. The endpointMapping element in the jaxrpc-ri.xml file

 <endpointMapping endpointName="name" urlPattern="pattern"/>

The endpointName attribute matches with the value of the name attribute of the endpoint element for which it supplies the URL mapping. The value of the urlPattern attribute is appended to the context URL for the hosting web application to give the full URL for the endpoint to which this element relates . For example, in a web application deployed at the URL http://localhost:8080/Books , the following mapping:

 <endpointMapping endpointName= "BookQuery" urlPattern= "/MyBookQuery"/>

makes the BookQuery endpoint interface available at the URL http://localhost:8080/Books/MyBookQuery . If an endpoint element does not have a corresponding endpointMapping , the URL is formed as follows :

 context-URL + "/" + urlPatternBase + "/" + endpointName

For example, for an endpoint called BookQuery defined within a webServices element for which the urlPatternBase attribute has the value /base , the endpoint URL is http://localhost:8080/Books/base/BookQuery .

8.2.6 Target Web Archive File Content

The web archive created by wsdeploy contains the items described in the following sections.

8.2.6.1 Original class files and resources

The class files, resource files, and JAR files that appear in the original WAR file are copied unchanged into the deployable WAR file.

8.2.6.2 Tie and serializer/deserializer classes

The wsdeploy utility creates a tie class for each endpoint and the appropriate serializer/deserializer classes for each value type defined in the endpoint interface and for the SOAP request and response messages that will be used. For a discussion of the function of tie classes, see Section 2.2.4.1.

These classes are all placed in the same package as the Java interface definition for the corresponding endpoint. Following compilation, they appear below the /WEB-INF/classes directory of the web archive.

8.2.6.3 Model file

If the endpoint element in the jaxrpc-ri.xml file contains a model attribute, then the referenced model file is copied into the deployable web archive. Otherwise, a model file is created based on introspection of the Java interface definition and placed in the /WEB-INF directory. The model file is called name_model.xml.gz , where name is the value of the name attribute of the endpoint element.

8.2.6.4 WSDL document

A WSDL definition describing each endpoint is created and placed in a file called name.wsdl in the /WEB-INF directory, where name is the value of the name attribute of the endpoint element. Note that a service with multiple endpoints will have the same number of generated WSDL documents, each describing a service with a single port.

8.2.6.5 Deployment descriptors

Two files containing deployment information are placed in the /WEB-INF directory of the output WAR file: web.xml and jaxrpc-ri-runtime.xml.

The web.xml file is derived from the skeleton version of the file included in the portable WAR file. Certain elements of the input file are preserved, while others are added (or replaced if they were originally specified).

The principal reason why wsdeploy utility modifies the web.xml file is to create the appropriate URL mappings for each web service endpoint, and to associate the hosting web application with JAXRPCServlet , which is the servlet provided by the reference implementation that handles the dispatching of received SOAP messages to the appropriate tie classes. The original web.xml file is not required to contain the elements that accomplish these tasks , because the association with JAXRPCServlet is implementation-dependent. When deploying the web service in another vendor's server implementation, a different servlet might be used and additional information might need to be included.

For example, Example 8-9 shows a typical set of elements added to the web.xml file during the deployment of a web service with a single endpoint called HandlerBookQuery .

Example 8-9. Elements added by wsdeploy to the web.xml file

 <listener>   <listener-class>com.sun.xml.rpc.server.http.JAXRPCContextListener   </listener-class> </listener> <servlet>   <servlet-name>HandlerBookQuery</servlet-name>   <display-name>HandlerBookQuery</display-name>   <description>JAX-RPC endpoint - HandlerBookQuery</description>   <servlet-class>com.sun.xml.rpc.server.http.JAXRPCServlet</servlet-class>   <load-on-startup>1</load-on-startup> </servlet> <servlet-mapping>   <servlet-name>HandlerBookQuery</servlet-name>   <url-pattern>/HandlerBookQuery</url-pattern> </servlet-mapping>

The URL mapping defined by the servlet-mapping element is derived from the endpointMapping element in the jaxrpc-ri.xml file ” or, if there is no such element, from the endpoint name together with the urlPatternBase attribute of the webServices element.

Note the presence of a listener element in the web.xml file. Since this element was introduced in Version 2.3 of the Java Servlet Specification, it follows that the JWSDP requires a web container that conforms to Java Servlets Version 2.3 or later.

Other elements present in the web.xml file (including context parameters, environment entries, and so on) are preserved unchanged by wsdeploy . A copy of the original file is placed in the /WEB-INF directory under the name web-before.xml .

The other deployment- related file placed in the /WEB-INF directory is called jaxrpc-ri-runtime.xml. This file contains deployment information derived from the jaxrpc-ri.xml file; since it is only intended for internal use, its content is not discussed here. The original jaxrpc-ri.xml file can be found in /WEB-INF/jaxrpc-ri-before.xml.