Table of Contents
This chapter describes how to create the standard web service deployment descriptor for JAX-RPC web services and the JAX-RPC mapping file
Java EE JAX-RPC web services require a web service descriptor called 'webservices.xml' to be included in a compressed file (WAR or JAR) that contains a Java endpoint or EJB endpoint. For an EJB endpoint, the deployment descriptor must be in the 'META-INF' directory. For a servlet based endpoint, it must be in the 'WEB-INF' directory of the WAR file.
The following is the deployment descriptor file for a web service called 'FileAttachmentService'.
[Example 24.1] << webservices.xml >>
<?xml version="1.0"?>
<webservices version="1.1" xmlns="http://java.sun.com/xml/ns/j2ee">
<webservice-description>
<webservice-description-name>
FileAttachmentService
</webservice-description-name>
<wsdl-file>
WEB-INF/wsdl/FileAttachmentService.wsdl
</wsdl-file>
<jaxrpc-mapping-file>
WEB-INF/FileAttachmentService-mapping.xml
</jaxrpc-mapping-file>
<port-component>
<port-component-name>FileAttPort</port-component-name>
<wsdl-port xmlns:ns2="urn:FileAttachmentService">
ns2:FileTransferIFPort
</wsdl-port>
<service-endpoint-interface>
filetransfer.FileTransferIF
</service-endpoint-interface>
<service-impl-bean>
<servlet-link>FileAttachmentServlet</servlet-link>
</service-impl-bean>
<handler>
<handler-name>ServerAttachmentHandler</handler-name>
<handler-class>
filetransfer.ServerAttachmentHandler
</handler-class>
<init-param>
<param-name>directory</param-name>
<param-value>/temp</param-value>
</init-param>
</handler>
</port-component>
</webservice-description>
</webservices>
The root element of the 'webservices.xml' is <webservices>, and it can contain one or more <webservicedescription> elements as required components.
The <webservice-description> element describes a group of Java classes and EJB endpoints that use the same WSDL file. A <webservice-description> element is required for each WSDL file. For example, if two different Java class endpoints each have different WSDLs in the same WAR file, there must be two <webservice-description> elements that describe each JSE.
The <webservice-description> element binds a Java EE endpoint to the WSDL port definition, DD implementation, JAX-RPC mapping file, and endpoint interface. This chapter discusses their relationships and their purpose.
Location of the JAX-RPC mapping file that defines the mapping between a WSDL file and a Java EE endpoint. For more information about the JAX-RPC mapping file, refer to "24.2. Creating a Web Service Mapping File".
Maps Java class or EJB endpoint to a specific port element in the WSDL document. For a Java class, WSDL port and binding definitions are used to generate the servlet required to host a web service.
For an EJB endpoint, they are used by an EJB container to marshal a SOAP message which is sent to a stateless session bean object.
When deploying the service, this element defines which service implementation logic definition will be the Java EE endpoint. For a Java class, this specifies the servlet definitions in the web.xml file. For an EJB endpoint, this specifies the session definitions in the ejb-jar.xml file.
For JSE, this is defined in the <servlet-link> element as in the following example.
[Example 24.2] DocLitEchoService : <<webservices.xml >>
<?xml version="1.0"?>
<webservices …>
<webservice-description>
<webservice-description-name>
DocLitEchoService
</webservice-description-name>
<wsdl-file>WEB-INF/wsdl/DocLitEchoService.wsdl</wsdl-file>
<jaxrpc-mapping-file>
WEB-INF/DocLitEchoService-mapping.xml
</jaxrpc-mapping-file>
<port-component>
<port-component-name>EchoPort</port-component-name>
<wsdl-port xmlns:ns2="urn:DocLitService">
ns2:EchoPort
</wsdl-port>
<service-endpoint-interface>
jeustest.webservices.java2wsdl.doclit.Echo
</service-endpoint-interface>
<service-impl-bean>
<servlet-link>EchoServlet</servlet-link>
</service-impl-bean>
</port-component>
</webservice-description>
</webservices>
The <servlet-link> element value must be same as the <servlet-name> element value in the web.xml file.
[Example 24.3] DocLitEchoService : << web.xml >>
<?xml version="1.0"?>
<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee">
<servlet>
<servlet-name>EchoServlet</servlet-name>
<servlet-class>
jeustest.webservices.java2wsdl.doclit.EchoImpl
</servlet-class>
. . .
</servlet>
</web-app>
As before, the <ejb-link> element is used to
define the EJB Endpoint as in the following example.
[Example 24.4] AddressBookService : <<webservices.xml >>
<?xml version="1.0"?>
<webservices …>
<webservice-description>
<webservice-description-name>
AddressBookService
</webservice-description-name>
<wsdl-file>META-INF/wsdl/AddressBookService.wsdl</wsdl-file>
<jaxrpc-mapping-file>
META-INF/AddressBookService-mapping.xml
</jaxrpc-mapping-file>
<port-component>
<port-component-name>
AddressBookIFPort
</port-component-name>
<wsdl-port xmlns:ns2="urn:AddressBookService">
ns2:AddressBookIFPort
</wsdl-port>
<service-endpoint-interface>
address.AddressBookIF
</service-endpoint-interface>
<service-impl-bean>
<ejb-link>AddressEJB</ejb-link>
</service-impl-bean>
</port-component>
</webservice-description>
</webservices>
The <ejb-link> element value must be same as the
<ejb-name> element value in the ejb-jar.xml file.
[Example 24.5] AddressBookService : << web.xml >>
<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar …>
<display-name>AddressEJB</display-name>
<enterprise-beans>
<session>
<display-name>AddressEJB</display-name>
<ejb-name>AddressEJB</ejb-name>
<service-endpoint>
address.AddressBookIF</service-endpoint>
<ejb-class>address.AddressBookEJB</ejb-class>
. . .
</session>
</enterprise-beans>
</ejb-jar>
Note that the targets that will be connected to by
using the <servlet-link> or <ejb-link> element must
exist in a compressed file that contains the webservices.xml
file.
A message handler filters and processes messages exchanged by a Java EE endpoint. The message handler and the processing order can be configured in the webservices.xml file. For more information about message handlers, refer to "Chapter 23. Creating SOAP Message Handler of JAX-RPC Web Service".
The following is an example of configuring a handler in the webservices.xml file.
[Example 24.6] FileAttachmentService : <<webservices.xml >>
<?xml version="1.0"?>
<webservices version="1.1" xmlns="http://java.sun.com/xml/ns/j2ee">
<webservice-description>
. . .
<port-component>
<port-component-name>FileAttPort</port-component-name>
. . .
<handler>
<handler-name>ServerAttachmentHandler</handler-name>
<handler-class>
filetransfer.ServerAttachmentHandler
</handler-class>
<init-param>
<param-name>directory</param-name>
<param-value>/temp</param-value>
</init-param>
</handler>
</port-component>
</webservice-description>
</webservices>
The following table contains the child elements of the <handler> element.
The JAX-RPC mapping file helps JAX-RPC compiler, which is embedded in the JEUS web service, to determine the relationship between the WSDL document and Java interface, which represents the web service endpoint. In many cases, WSDL and Java can be mapped without a mapping file, but the JAX-RPC mapping file has been added for when explicit definitions are required.
A JAX-RPC mapping file is required whenever Java EE web service endpoint or Java EE web service client is used, and there is one JAX-RPC mapping file for each WSDL file.
The following are the elements defined in a JAX-RPC mapping file.
XML complex type and Java beans
Fault messages and exception classes
portType definition and service endpoint interface in WSDL
portType definition and service endpoint interface in WSDL
Those that are not defined in the JAX-RPC mapping file are mapped using the standard mapping rules for WSDL and XML to Java. The definitions in the mapping file always have priority over the standard mapping rules.
The contents of JAX-RPC seems more complex and longer than other configuration files.
The following is the JAX-RPC mapping file structure.
[Example 24.7] JAX-RPC Mapping File Structure
<java-wsdl-mapping>
<package-mapping/>
<java-xml-type-mapping/>
<exception-mapping/>
<service-interface-mapping/>
<service-endpoint-interface-mapping>
<service-endpoint-method-mapping/>
<service-endpoint-method-mapping/>
. . .
</service-endpoint-interface-mapping>
<service-interface-mapping/>
<service-endpoint-interface-mapping>
<service-endpoint-method-mapping/>
<service-endpoint-method-mapping/>
. . .
</service-endpoint-interface-mapping>
</java-wsdl-mapping>
Used by the JAX-RPC compiler to generate Java class and interface definitions by using various types specified in the WSDL file. The <package-mapping> element must be specified.
The <package-type> element value corresponds to the Java package name, and the <namespaceURI> element value is an XML namespace that is mapped to the specified Java package.
<java-wsdl-mapping version="1.1"
xmlns="http://java.sun.com/xml/ns/j2ee">
<package-mapping>
<package-type>address</package-type>
<namespaceURI>urn:AddressBookService</namespaceURI>
</package-mapping>
. . .
</java-wsdl-mapping>
Relationship between the XML schema complex type and Java type. This element is required when using a complex or simple type of XML schema, but is not needed if the built-in type allows standard Java mapping.
<java-wsdl-mapping version="1.1"
xmlns="http://java.sun.com/xml/ns/j2ee">
. . .
<java-xml-type-mapping>
<java-type>address.Address</java-type>
<ns1:root-type-qname
xmlns:ns1=”http://java.sun.com/xml/ns/j2ee”
xmlns="urn:AddressBookService">
Address
</ns1:root-type-qname>
<qname-scope>complexType</qname-scope>
<variable-mapping>
<java-variable-name>addr</java-variable-name>
<xml-element-name>addr</xml-element-name>
</variable-mapping>
<variable-mapping>
<java-variable-name>street</java-variable-name>
<xml-element-name>street</xml-element-name>
</variable-mapping>
<variable-mapping>
<java-variable-name>zipcode</java-variable-name>
<xml-element-name>zipcode</xml-element-name>
</variable-mapping>
</java-xml-type-mapping>
. . .
</java-wsdl-mapping>
Maps the service definition of WSDL to JAX-RPC service interface type. The <service-interface> element specifies the full class package name of the Java interface, and the name must match the <package-mapping> element value.
The <port-mapping> element specifies the port name returned from the getPortName() method of the service interface as the <port> element value of the WSDL.
<java-xml-mapping…>
. . .
<service-interface-mapping>
<service-interface>
address.AddressBookService
</service-interface>
<ns3:wsdl-service-name
xmlns:ns3="http://java.sun.com/xml/ns/j2ee"
xmlns="urn:AddressBookService">
AddressBookService
</ns3:wsdl-service-name>
<port-mapping>
<port-name>AddressBookIFPort</port-name>
<java-port-name>AddressBookIFPort</java-port-name>
</port-mapping>
</service-interface-mapping>
. . .
</java-xml-mapping>
The following Java service interface class is created by using the previous definitions.
[Example 24.8] << AddressBookService.java >>
package address; public interface AddressBookService extends javax.xml.rpc.Service { public java.lang.String getAddressBookIFPortAddress(); public address.AddressBookIF getAddressBookIFPort() throws javax.xml.rpc.ServiceException; public address.AddressBookIF getAddressBookIFPort(java.net.URL portAddress) throws javax.xml.rpc.ServiceException; }
<service-endpoint-interface-mapping>
This element maps the service endpoint element to the portType and binding definition of the WSDL. It also provides information required to generate an appropriate endpoint stub and endpoint interface and specifies how the operation and message part definition of the WSDL are mapped to a Java endpoint method.
The following is an example of the definitions in the mapping file of the AddressBookService.
<java-wsdl-mapping…>
. . .
<service-endpoint-interface-mapping>
<service-endpoint-interface>
address.AddressBookIF
</service-endpoint-interface>
<ns4:wsdl-port-type
xmlns:ns4="http://java.sun.com/xml/ns/j2ee"
xmlns="urn:AddressBookService">
AddressBookIF
</ns4:wsdl-port-type>
<ns5:wsdl-binding
xmlns:ns5="http://java.sun.com/xml/ns/j2ee"
xmlns="urn:AddressBookService">
AddressBookIFSoapBinding
</ns5:wsdl-binding>
<service-endpoint-method-mapping>
<java-method-name>add</java-method-name>
<wsdl-operation>add</wsdl-operation>
<wrapped-element/>
<method-param-parts-mapping>
<param-position>0</param-position>
<param-type>address.PersonInfo</param-type>
<wsdl-message-mapping>
<ns6:wsdl-message
xmlns:ns6="http://java.sun.com/xml/ns/j2ee"
xmlns="urn:AddressBookService">
addRequest
</ns6:wsdl-message>
<wsdl-message-part-name>
parameters
</wsdl-message-part-name>
<parameter-mode>IN</parameter-mode>
</wsdl-message-mapping>
</method-param-parts-mapping>
<wsdl-return-value-mapping>
<method-return-value>
address.PersonInfo[]
</method-return-value>
<ns7:wsdl-message
xmlns:ns7=”http://java.sun.com/xml/ns/j2ee“
xmlns="urn:AddressBookService">
addResponse
</ns7:wsdl-message>
<wsdl-message-part-name>
parameters
</wsdl-message-part-name>
</wsdl-return-value-mapping>
</service-endpoint-method-mapping>
. . .
</service-endpoint-interface-mapping>
. . .
</java-wsdl-mapping>