8.6 J2EE 1.4 Web Services Configuration File | Java Web Services in a Nutshell

8.6.1 Availability

All J2EE 1.4 platforms.

8.6.2 Description

All J2EE modules that contain a web service are required to provide information that allows deployment tools to locate the classes that implement the service, the WSDL document describing its service interface, and a mapping file that describes how that interface should be mapped to elements of the Java programming language. The location of this file depends on the archive in which it resides:

For a web service hosted by a servlet, the file belongs to the hosting web application and must be called WEB-INF/ webservices .xml .
For an EJB-hosted web service, the file is placed in the same EJB JAR file as the implementing bean and is called META-INF/webservices.xml .

The content of this file is defined by an XML Schema document that can be downloaded from http://www.ibm.com/webservices/xsd/j2ee_web_services_1_1.xsd. An outline of the content of this file is shown in Example 8-12.

Example 8-12. The webservices.xml file

 <webservices>   <webservice-description>                <!-- One or more -->     <description>text</description>       <!-- Optional -->     <display-name>text</display-name>     <!-- Optional -->     <icon> <!-- Optional -->       <small-icon>name</small-icon>       <!-- Optional -->       <large-icon>name</large-icon>       <!-- Optional -->     </icon>     <web-service-description-name>name</web-service-description-name>     <wsdl-file>file-location</wsdl-file>     <jaxrpc-mapping-file>file-location</jaxrpc-mapping-file>     <port-component>                        <!-- One or more -->       <description>text</description>       <!-- Optional -->       <display-name>text</display-name>     <!-- Optional -->       <icon>                                <!-- Optional -->         <small-icon>name</small-icon>       <!-- Optional -->         <large-icon>name</large-icon>       <!-- Optional -->       </icon>       <port-component-name>name</port-component-name>       <wsdl-port/>                          <!-- See text -->       <service-endpoint-interface>class name</service-endpoint-interface>       <service-impl-bean>                   <!-- See text -->       <handler/>                            <!-- Zero or more. See text -->     </port-component>   </webservice-description> </webservices>

Each web service defined in the module requires its own webservice-description element, in which the web-service-description-name has a value that is unique within the module. The wsdl-file and jaxrpc-mapping-file elements specify the locations of the WSDL file and the JAX-RPC mapping file that apply to the service, relative to the root of the module. Either absolute or relative paths may be used and are interpreted in the same way ” that is, the tags shown here:

 <wsdl-file>BookService.wsdl</wsdl-file>

and the tags shown here:

 <wsdl-file>/BookService.wsdl</wsdl-file>

refer to the same location. The jaxrpc-mapping-file specifies the mapping from the elements of the WSDL file to Java programming language elements and is described in Section 8.7, later in this chapter.

Each webservice-description element contains one or more port-component elements, each of which describes a single port within the service. The port-component-name element provides a name for the port that must be unique within the module, whereas the service-endpoint-interface element gives the fully qualified name of the Java class that implements the service endpoint interface. A port-component is linked to a port element from the associated WSDL file using the wsdl-port element, which is structured as follows :

 <wsdl-port>     <namespaceURI>urn:jwsnut.chapter2.bookservice/wsdl/BookQuery     </namespaceURI>     <localpart>BookQueryPort</localpart>  </wsdl-port>

The namespaceURI element must match the namespace within which the port is defined, which is the same as the value of the targetNamespace attribute of the definitions element in the WSDL definition file. The localpart is the value of the name attribute of the port element in the WSDL file. The values shown previously correspond to the following parts of the WSDL definition for the book web service created in Chapter 2.

 <definitions name="BookService"  targetNamespace="urn:jwsnut.chapter2.bookservice/wsdl                               /BookQuery  "              xmlns:tns="urn:jwsnut.chapter2.bookservice/wsdl/                   BookQuery" .... >   .....   <service name="BookService">      <  port name="BookQueryPort  " binding="tns:BookQueryBinding">       <soap:address location="http://localhost:8000/Books/BookQueryPort"/>      </port>   </service> </definitions>

The service implementation class is linked to by the service-impl-bean element, which may be either a servlet or an EJB. Servlets are referred to using the servlet-link element:

 <service-impl-bean>   <servlet-link>BookQueryServlet</servlet-link> </service-impl-bean>

where, in this case, BookQueryServlet must be the value of a servlet-name element in the web.xml file located in the same module as the webservices.xml file. A web service implemented as an EJB requires an ejb-link element instead:

 <service-impl-bean>   <ejb-link>BookQueryBean</ejb-link> </service-impl-bean>

The target of the link must be the value of the ejb-name element of a stateless session bean declared in the ejb-jar.xml file in the same module.

An optional set of SOAP message handlers (see Section 6.8.2) can be configured using one or more handler elements, which is structured as shown in Example 8-13.

Example 8-13. The handler element in the webservices.xml file

 <handler>   <handler-name>name</handler-name>   <handler-class>class name</handler-class>   <init-param>                            <!-- Zero or more -->     <description>text</description>       <!-- Optional -->     <param-name>name</param-name>     <param-value>value</param-value>   </init-param>   <soap-header>                           <!-- Zero or more -->     <namespaceURI>URI</namespaceURI>     <localpart>name</localpart>   <soap-header>   <soap-role>rolename</soap-role>         <!-- Zero or more --> </handler>

The Java class that implements the handler is named by the handler-class element. This class must implement the javax.xml.rpc.handler.Handler interface. Optional initialization parameters may be passed to the handler's init( ) method by including one or more init-param elements.

The soap-header and soap-role elements specify respectively the header or headers that the message handler can process and the SOAP roles that apply to the message handler. See Section 6.8.2.4 for a full description of message headers and SOAP roles. The soap-header element requires the specification of both the namespace URI and the local part of the name:

 <soap-header>   <namespaceURI>urn:jwsnut.chapter6.handlerbookservice/wsdl/ HandlerBookQuery</namespaceURI>   <localpart>auth</localpart> </soap-header>