29.2. Exposing a J2EE Component as a Web Service

29.2.1. A JAX-RPC Endpoint

A JAX-RPC endpoint is a simple class running in the Tomcat servlet container. SOAP requests are dispatched to an instance of this class and the response is serialized and sent back to the client.

A JAX-RPC endpoint must be in a Web Application (the WAR file must contain a WEB-INF/webservices.xml).

29.2.2. Stateless Session Bean Endpoint

An Stateless Session Bean (SSB) is an EJB that will be exposed (all or some of its methods) as a Web Service endpoint.

In the ejb-jar.xml standard descriptor, a Session Bean, exposed as a Web Service, must now use the new service-endpoint tag. Here the developer defines the fully qualified interface name of the Web Service. Notice that no other interfaces (home, remote, localhome, local) are needed with a Session Bean exposed as Web Service.

Typically, an SSB must be in an EJB-JAR, and a META-INF/webservices.xml is located in the EJB-JAR file.

29.2.3. Usage

In this Descriptor, the developer describes the components that will be exposed as Web Services' endpoints; these are called the port-components. A set of port-components defines a webservice-description, and a webservice-description uses a WSDL Definition file for a complete description of the Web Services' endpoints.

Each port-component is linked to the J2EE component that will respond to the request (service-impl-bean with a servlet-link or ejb-link child element) and to a WSDL port (wsdl-port defining the port's QName). A list of JAX-RPC Handlers is provided for each port-component. The optional service-endpoint-interface defines the methods of the J2EE components that will be exposed (no inheritance needed).

A JAX-RPC Handler is a class used to read or modify the SOAP Message before transmission or after reception (refer to the JAX-RPC v1.1 spec. chap#12 "SOAP Message Handlers"). The Session Handler is a simple example that will read/write SOAP session information in the SOAP Headers. Handlers are identified with a unique name (within the application unit), are initialized with the init-param(s), and work on processing a list of SOAP Headers defined with soap-headers child elements. The Handler is run as the SOAP actors defined in the list of SOAP-roles.

A webservice-description defines a set of port-components, a WSDL Definition (describing the Web Service) and a mapping file (WSDL-2-Java bindings). The wsdl-file element and the jaxrpc-mapping-file element must specify a path to a file contained in the module unit (that is, the WAR/JAR file). Note that a URL cannot be set here. The specification also requires that the WSDLs be placed in a wsdl subdirectory (that is, WEB-INF/wsdl or META-INF/wsdl); there is no such requirement for the jaxrpc-mapping-file. All the ports defined in the WSDL must be linked to a port-component. This is essential because the WSDL is a contract between the endpoint and a client (if the client use a port not implemented/linked with a component, the client call will systematically fail).

As for all other Deployment Descriptors, a standard XML Schema (http://www-124.ibm.com/developerworks/opensource/jsr109/xsd/j2ee_web_services_1_1.xsd) is used to constrain the XML.

29.2.4. Simple Example (expose a JAX-RPC Endpoint) of webservices.xml

<webservices xmlns="http://java.sun.com/xml/ns/j2ee"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
   http://www.ibm.com/webservices/xsd/j2ee_web_services_1_1.xsd"
   version="1.1">
   <display-name>Simple Web Service Endpoint 
      DeploymentDesc</display-name>
      
  <webservice-description>
    <!-- name must be unique in an Application unit-->
    <!-- Should not contains spaces !!! -->
    <webservice-description-name>
      SimpleWebServiceEndpoint
    </webservice-description-name>
      
    <!-- Link to the WSDL file describing the endpoint -->
   
<wsdl-file>WEB-INF/wsdl/warendpoint.wsdl</wsdl-file>
      
    <!-- Link to the mapping file describing binding
       between WSDL and Java -->
   
<jaxrpc-mapping-file>WEB-INF/warEndpointMapping.xml
</jaxrpc-mapping-file>
      
    <!-- The list of endpoints -->
    <port-component>
      
    <!-- Unique name of the port-component -->
    <!-- Must not contains spaces !!! --> 
           
<port-component-name>WebappPortComp1</port-component-name>
      
      <!-- The QName of the WSDL Port the
J2EE port-component is linked to -->
      <!-- Must Refers to a port in
associated WSDL document -->
      <wsdl-port xmlns:ns=" 
      http://wsendpoint.servlets.ws.objectweb.org ">
          ns:wsendpoint1
      </wsdl-port>
      
      <!-- The endpoint interface defining methods exposed -->
      <!-- for the endpoint                                -->
      <service-endpoint-interface>
         org.objectweb.ws.servlets.wsendpoint.WSEndpointSei
      </service-endpoint-interface>
      
      <!-- Link to the J2EE component (servlet/EJB)    -->
      <!-- implementing methods of the SEI             -->
      <service-impl-bean>
      <!-- name of the servlet defining the JAX-RPC endpoint    -->
      <!-- can be ejb-link if SSB is used (only in EjbJar !)    -->
             <servlet-link>WSEndpoint</servlet-link>
      </service-impl-bean>
      
      <!-- The list of optional JAX-RPC Handlers --> 
      <handler>
      <handler-name>MyHandler</handler-name>
      <handler-class>org.objectweb.ws.handlers.SimpleHandler</handler-class>
      <!-- A list of init-param for Handler configuration --> 
         <init-param>
             <param-name>param1</param-name>
             <param-value>value1</param-value>
         </init-param>
         <init-param>
             <param-name>param2</param-name>
             <param-value>value2</param-value>
         </init-param>
      </handler>
    </port-component>
  </webservice-description>
</webservices> 

29.2.5. The Optional jonas-webservices.xml

The jonas-webservices.xml file is collocated with the webservices.xml. It is an optional Deployment Descriptor (required only in some cases). Its role is to link a webservices.xml to the Web Application in charge of the SOAP request dispatching. In fact, it is only needed for an EJB-JAR (the only one that depends on another servlet to be accessible with HTTP/HTTPS) that does not use the Default Naming Convention used to retrieve a Web Application name from the EJB-JAR name.

Convention: ejbjar-name.jar will have an ejbjar-name.war Web Application.

Example:

<jonas-webservices xmlns="http://www.objectweb.org/jonas/ns"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.objectweb.org/jonas/ns
   http://www.objectweb.org/jonas/ns/jonas_j2ee_web_services_4_0.xsd">
   <!-- the name of the webapp in the EAR              -->
   <!-- (it is the same as the one in application.xml) -->
   <war>dispatchingWebApp.war</war>
</jonas-webservices>

29.2.6. Changes to jonas-web.xml

JOnAS allows the developer to fully configure an application by setting the hostname, the context-root, and the port used to access the Web Services. This is done in the jonas-web.xml file of the dispatching Web Application.

When these values are not set, JOnAS will attempt to determine the default values for host and port.

Limitations:

• The host can be determined only when only one host is set for the web container.

• The port can be determined only when only one connector is used by the web container.