Web Services with JOnAS

1. Web Services

A. Some Definitions

B. Overview of a Web Service

Strictly speaking, a Web Service is a well-defined, modular, encapsulated function used for loosely coupled integration between applications' or systems' components. It is based on standard technologies, such as XML, SOAP, and UDDI.

Web Services are generally exposed and discovered through a standard registry service. With these standards, Web Services consumers (whether they be users or other applications) can access a broad range of information -- personal financial data, news, weather, and enterprise documents -- through applications that reside on servers throughout the network.

Web Services use a WSDL Definition (refer to www.w3.org/TR/WSDL) as a contract between client and server (also called endpoint). WSDL defines the types to serialize through the network (described with XMLSchema), the messages to send and receive (composition, parameters), the portTypes (abstract view of a Port), the bindings (concrete description of PortType: SOAP, GET, POST, ...), the services (set of Ports), and the Port (the port is associated with a unique endpoint URL that defines the location of the Web Service).

A Web Service for J2EE is a component with some methods exposed and accessible by HTTP (through servlet(s)). Web Services can be implemented as Stateless Session Beans or as JAXRPC classes (a simple Java class, no inheritance needed).

Figure 1. Web Services endpoints deployed within JOnAS (an external client code can access the endpoint via AxisServlet)

Figure 2. Web Services client deployed within JOnAS (can access external Web Services)

The servlet is used to respond to a client request and dispatch the call to the designated instance of servant (the SSB or JAXRPC class exposed as Web Service). It handles the deserialization of incoming SOAP messages to transform SOAP XML into a Java Object, perform the call, and serialize the call result (or the thrown exception) into SOAP XML before sending the response message to the client.

2. Exposing a J2EE Component as a Web Service

A. JAX-RPC Endpoint

B. Stateless Session Bean Endpoint

C. Usage

In this Descriptor, the developer describes the components that will be exposed as Web Services' endpoints; these are called the port-component(s). 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 and/or modify the SOAP Message before transmission and/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 actor(s) 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 (i.e., 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 (i.e., 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 uses 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.

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

E. The optional jonas-webservices.xml

• jonas:jonas-webservices/jonas:war: specify the filename of the webapp frontend generated for this EjbJar
• jonas:jonas-webservices/jonas:context-root: specify the context root of the webapp frontend generated for this EjbJar

<?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/ns/j2ee"
                   xsi:schemaLocation="http://www.objectweb.org/jonas/ns http://www.objectweb.org/jonas/ns/jonas_j2ee_web_services_4_5.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>

  <jonas-port-component>
    <port-component-name>ssbEndpoint</port-component-name>
    <!-- We can specify with endpoint-uri the URL we want to have for the given port.      -->
    <!-- Will be something like : http://<host>:<port>/<context-root>/services1/webservice -->
    <endpoint-uri>/services1/webservice</endpoint-uri>
  </jonas-port-component>

  <!-- everthing in this element will appear in the security-constraint -->
  <!-- element in the web.xml of the generated webapp                   -->
  <endpoint-security-constraint>
    <j2ee:web-resouce-collection>
      <j2ee:web-resource-name>Stateless Session Bean Endpoint</j2ee:web-resource-name>
      <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:realm-name>Endpoint Authentication Area</j2ee:realm-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>

F. Changes to jonas-web.xml

3. The client of a Web Service

A. The service-ref element

B. The jonas-service-ref element

4. WsGen

WsGen is a new JOnAS tool that works in the same way as GenIC. It takes archive files (EJB-JAR, WAR, JAR client, EAR) and generates all the necessay components related to web services:

• Creates vendor-specific web-services deployment files for the server side and, when needed, the client side (Axis will use its own wsdd format).
• Creates a WebApp for each EJB-JAR exposing web services.
• Generates and compiles client side artifacts (Services and Port Bindings implementations classes).

For example, to provide an EJB-exposing method as a web service, a developer creates a webservices.xml file packaged in EjbJar's META-INF directory. WsGen automatically creates a configured webapp (using an Axis servlet) and wraps it (ejbjar + webapp) in an EAR file.

With a JaxRpc class, WsGen adds a servlet (an Axis servlet) inside the existing web deployment descriptor and generates an Axis-specific configuration file.

When using service-ref (from ejbjars, web applications, or clients), WsGen automatically generates a Stub from WSDL (if a generated service interface name is provided).

Usage

WsGen is used typically from an ant build file. Simply add this taskdef under the ejbjar taskdef:

<taskdef name="wsgen" classname="org.objectweb.jonas.ant.WsGenTask"
   classpath="${jonas.root}/lib/common/ow_jonas_ant.jar" />
<wsgen srcdir="${temp.dir}"
   destdir="${dist.dir}"
   verbose="false"
   debug="false">
      <include name="webapps/wswarsample.war"/>
</wsgen>

See the $JONAS_ROOT/examples/webservices samples for complete build scripts.

Note that the ejbjar/webapp/client archive must include WSDL, jax-rpc-mappings used in service-ref, or webservices.xml. When these files are used from a service-ref, they are added into the generic ejb-jar with the ejbjar ant task of JOnAS; you must ensure that they have been placed inside the srcdir given to the ejbjar task (otherwise, the ejbjar task cannot find them and will produce an error).

This task is a directory-based task and, as such, forms an implicit Fileset. This defines which files, relative to the srcdir, will be processed. The wsgen task supports all the attributes of Fileset to refine the set of files to be included in the implicit fileset.

Wsgen is also usable from the command line with WsGen script (available on *nix and Windows).