29.2. Exposing a J2EE Component as a Web Service

There are two types of J2EE components that can be exposed as Web Services endpoints: Stateless Session Beans and JAX-RPC classes. Web Services' endpoints must not contain state information.

A new standard Deployment Descriptor has been created to describe Web Services endpoints. This Descriptor is named webservices.xml and can be used in a Web Application (in WEB-INF/) or in an EJB-JAR (in META-INF/). This Descriptor has its JOnAS-specific Deployment Descriptor (jonas-webservices.xml is optional).

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 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 an optional deployment descriptor that is used only for stateless session bean endpoints. This descriptor is used by WsGen to set some specifics for the generated webapp that is in charge of the SOAP request dispatching. Its role is to allow for the specifications of the webapp's name, context root, and security settings.

War Name:

Specifies the name of the generated WAR. Setting the <war> element is optional; if it is not specified, then the default naming convention is used to retrieve the WAR name from the EJBJAR's name.

Default Naming:

<ejbjar-name>.jar will have an <ejbjar-name>.war WebApp.

Context Root:

Specifies the context root of the generated WAR. Setting the <context-root> element is optional; if it is not specified, then the default naming convention is used and the context root will be the same as the WAR's name.

Default Naming:

<webapp-name>.war will have a <webapp-name> context root.

Security:

The security settings specify what security settings, if any, the generated webapp should use. Setting up security within this file is very similar to how you would setup security in a normal web.xml.

NoteNote
 

When using the <endpoint-security-constraint>, <endpoint-login-config>, or <endpoint-security-role> elements, you must include the j2ee namespace in the jonas-webservices element (that is, xmlns:j2ee:"http://java.sun.com/xml/j2ee"), and you will have to specify the namespace for all elements within these tags (that is, the 'j2ee:' in the examples below).

Security Constraint:

The <endpoint-security-constraint> specifies the <security-constraint> element to be used in the web.xml of the generated webapp.

Login Config:

The <endpoint-login-config> is used to specify the <login-config> element to be used in the web.xml of the generated webapp.

Security Role:

The <endpoint-security-role> specifies the <security-role> element to be used in the web.xml of the generated webapp.

Realm:

The <endpoint-realm> specifies the security realm the generated webapp should use.

Realm Name:

The <endpoint-realm-name> specifies the name of the security realm the generated webapp should use.

<?xml version="1.0"?>
<jonas-webservices xmlns="http://www.objectweb.org/jonas/ns"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:j2ee:"http://java.sun.com/xml/j2ee"
        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>

    <!-- the context root the webapp should use -->
    <context-root>endpoint</context-root>

    <!-- everything in this element will appear in the security-constraint -->
    <!-- element in the web.xml of the generated webapp                    -->
    <endpoint-security-constraint>
      <j2ee:web-resource-collection>
        <j2ee:web-resource-collection>Stateless Session Bean Endpoint</j2ee:web-resource-collection>
        <j2ee:url-pattern>/*</j2ee:url-pattern>
      </j2ee:web-resource-collection>
      <j2ee:auth-constraint>
        <j2ee:role-name>admin</j2ee:role-name>
      </j2ee:auth-constraint>
    </endpoint-security-constraint>

    <!-- everything in this element will appear in the login-config -->
    <!-- element in the web.xml of the generated webapp             -->
    <endpoint-login-config>
      <j2ee:auth-method>BASIC</j2ee:auth-method>
      <j2ee:role-name>Endpoint Authentication Area</j2ee:role-name>
    </endpoint-login-config>

    <!-- everything in this element will appear in the security-role -->
    <!-- element in the web.xml of the generated webapp              -->
    <endpoint-security-role>
      <j2ee:role-name>admin</j2ee:role-name>
    </endpoint-security-role>

    <!-- the realm the generated webapp should use -->
    <endpoint-realm>memrlm_1</endpoint-realm>

    <!-- the name of the realm the generated webapp should use -->
    <endpoint-realm-name>Endpoint Authentication Area</endpoint-realm-name;

</jonas-webservices>

Example 29-1. Example:

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.

host

Configure the hostname to use in URL (must be an available web container host).

port

Configure the port number to use in URL (must be an available HTTP/HTTPS connector port number).

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

Limitations: