# Web Services with JOnAS

Starting with JOnAS 3.3, WebServices can be used within EJBs and/or servlets/JSPs. This integration conforms to the JSR 921(v1.1) specification (public draft 3).
Note: While JSR 921 is in a maintenance review phase, we provide a link to the 109(v1.0) specification.

## 1. Web Services

### A. Some Definitions

WSDL: WSDL (Web Service Description Language) specifies an XML format for describing a service as a set of endpoints that operate on messages.
SOAP: SOAP (Simple Object Access Protocol) v1.1 specification defines an XML-based protocol for the exchange of information in a decentralized, distributed environment. SOAP defines a convention for representation of remote procedure calls and responses.
JAXRPC: JAXRPC (Java Api for XML RPC) v1.1 is the specification that defines the programming model for XML RPC with Java.

### 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 WebService).

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. WebServices endpoints deployed within JOnAS (an external client code can access the endpoint via AxisServlet)
Figure 2. WebServices client deployed within JOnAS (can access external WebServices)

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 WebService). It handles the deserialization of incoming SOAP message to transform SOAP XML into a Java Object, perform the call, and serialize the call result (or the thrown exception) into SOAP XML before send the response message to the client.

## 2. Exposing a J2EE Component as a Web Service

There are two types of J2EE components that can be exposed as WebServices endpoints: StateLess Session Beans and JAX-RPC classes. WebServices' Endpoints must not contain state information.
A new standard Deployment Descriptor has been created to describe WebServices endpoints. This Descriptor is named "webservices.xml" and can be used in a webapp (in WEB-INF/) or in an EjbJar (in META-INF/). This Descriptor has its JOnAS-specific Deployment Descriptor (jonas-webservices.xml is optional).
At this time, the user must configure the Axis-specific deployment descriptor (.wsdd). Refer to the Axis reference guide for more information about WSDD files.
Refer to the webServices sample for example files (etc directory).

#### A. JAX-RPC Endpoint

A JAX-RPC endpoint is a simple class running in the servlet container (Tomcat or Jetty). 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 WebApp (the war file must contain a "WEB-INF/webservices.xml").
Note: The developer must declare the AxisServlet with only one servlet-mapping. Additionally, a server-config.wsdd must be provided in the WEB-INF directory. This file tells Axis which service to expose (one service element corresponds to one port-component in webservices.xml) with information for accessing the servant class set as parameter(s) sub element(s) (className, allowedMethods, ...).

#### B. Stateless Session Bean Endpoint

An SSB is an EJB that will be exposed (all or some of its methods) as a WebService endpoint.
Typically, an SSB must be in an EjbJar, and a "META-INF/webservices.xml" is located in the EjbJar file.
Note: Because an SSB cannot be accessed directly via HTTP, the user must create an empty webapp that declares the AxisServlet with a server-config.wsdd file (refer to the previous). For this, the user must set information for bean access (beanJndiName, localHomeInterfaceName, localInterfaceName, homeInterfaceName, remoteInterfaceName) in server-config.xml. Not all of these parameters are required, only those specific to the user's needs (for example, no remote interfaces if an SSB is only local). The developer must also create a JOnAS-specific deployment descriptor for webservices: jonas-webservices.xml. The filename of the war created previously must be specified to identify to JOnAS the URL for accessing the SSB. Finally, these two files (EjbJar and WebApp) must be added into an Application archive.

#### C. Usage

In this Descriptor, the developer describes the components that will be exposed as WebServices' 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 WebServices' 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 WebService) 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 use a port not implemented/linked with a component, the client call will systematically fail).

As for all other Deployment Descriptor, a standard DTD is used to constrain the XML. Note that DTDs will be replaced by XML schemas in J2EE 1.4.

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

`<?xml version="1.0"?>
<!DOCTYPE webservices PUBLIC
"-//IBM Corporation, Inc.//DTD J2EE Web services 1.0//EN"
"http://www.ibm.com/webservices/dtd/j2ee_web_services_1_0.dtd">
<webservices>
<display-name>Simple Web Service Endpoint DeploymentDesc</display-name>
<webservice-description>
<!-- name must be unique in an Application unit -->
<webservice-description-name>Simple Web Service Endpoint</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 -->`
`<port-component-name>WebappPortComp1</port-component-name>
<!-- The QName of the WSDL Port the J2EE port-component is linked to -->
<wsdl-port>
<namespaceURI>http://wsendpoint.servlets.ws.objectweb.org</namespaceURI>
<localpart>wsendpoint1</localpart>
</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 element 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>`

#### E. The optionnal jonas-webservices.xml

The jonas-webservices.xml file is collocated with the webservices.xml. It is an optional Deployment Descriptor (only required in some case). Its role is to link a webservices.xml to the WebApp in charge of the SOAP request dispatching. In fact, it is only needed for an EjbJar (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 webapp name from the EjbJar name.
Convention: <ejbjar-name>.jar will have an <ejbjar-name>.war WebApp.
Example:

`<?xml version="1.0"?>` `<!DOCTYPE jonas-webservices PUBLIC` `"-//Objectweb//DTD JOnAS WebServices 3.3//EN"` `"``http://jonas.objectweb.org/dtds/``jonas-webservices_3_3.dtd"> <jonas-webservices> <!-- the name of the webapp in the EAR (it is the same as the one in application.xml) --> <war>dispatchingWebApp.war</war> </jonas-webservices>`

#### F. 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 WebServices. This is done in the jonas-web.xml of the dispatching WebApp.
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:
- The host can only be determined when only one host is set for the web container.
- The port can only be determined when only one connector is used by the web container.

## 3. The client of a WebService

An EJB or a servlet that wants to use a WebService (as client) must declare a dependency on the WebService with a service-ref element (same principle as for all *-ref elements).
Note: In JOnAS 3.3, the EJB 2.1 and servlet 2.4 XML Grammar is not yet supported. Therefore, to use service-ref elements in an ejb-jar.xml and a web.xml, the developer must change the DOCTYPE of the Deployment Descriptors.
For web.xml:

`<!DOCTYPE web-app PUBLIC` `"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"` `"``http://jonas.objectweb.org/dtds/``web-app_2_3_ws.dtd">`

For ejb-jar.xml:

`<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN" "http://jonas.objectweb.org/dtds/ejb-jar_2_0_ws.dtd">`

### A. The service-ref element

The service-ref element declares reference to a WebService used by a J2EE component in the web and EJB Deployment Descriptor.
The component uses a logical name called a service-ref-name to lookup the service instance. Thus, any component that performs a lookup on a WebService must declare a dependency (the service-ref element) in the standard deployment descriptor (web.xml or ejb-jar.xml).
Example of service-ref:

`<service-ref>
<!--` `(Optional) A Web services description that can be used in administration tool.``-->
<description>Sample WebService Client</description>
<!--` `(Optional) The WebService reference name. (used in Administration tools)``-->
<display-name>WebService Client 1</display-name>
<!--` `(Optional) An icon for this WebService.``-->
<icon> <!-- ... --> </icon>
<!--``The logical name for the reference that is used in the client source code.
It is recommended, but not required that the name begin with 'services/'``-->
<service-ref-name>services/myService</service-ref-name>
<!--``Defines the class name of the JAX-RPC Service interface that the client depends on.
In most cases, the value will be : javax.xml.rpc.Service
but a generated specific Service Interface class may be specified
(require WSDL knowledge and so the wsdl-file element).` `-->
<service-interface>javax.xml.rpc.Service</service-interface>
<!--``(Optional) Contains the location (relative to the root of
the module) of the web service WSDL description.`
`- need to be in the wsdl directory.
- required if generated interface and sei are declared. -->
<wsdl-file>WEB-INF/wsdl/stockQuote.wsdl</wsdl-file>
<!--` `(Optional) A file specifying the correlation of the WSDL definition
to the interfaces (Service Endpoint Interface, Service Interface).`
`- required if `generated interface and sei (Service Endpoint Interface) are declared.```-->
<jaxrpc-mapping-file>WEB-INF/myMapping.xml</jaxrpc-mapping-file>
<!--``(Optional) Declares the specific WSDL service element that is being referred to.
It is not specified if no wsdl-file is declared or if WSDL contains only 1 service element.
A service-qname is composed by a namespaceURI and a localpart.
It must be defined if more than 1 service is declared in the WSDL.``-->
<service-qname>
<namespaceURI>http://beans.ws.objectweb.org</namespaceURI>
<localpart>MyWSDLService</localpart>
</service-qname>
<!--` `Declares a client dependency on the container to resolving a Service Endpoint Interface
to a WSDL port. It optionally associates the Service Endpoint Interface with a
particular port-component.``-->
<port-component-ref>
<service-endpoint-interface>``org.objectweb.ws.beans.ssbendpoint.MyService``</service-endpoint-interface>
<!-- Define a link to a port component declared in another unit of the application -->
<port-component-link>ejb_module.jar#PortComponentName``</port-component-link>`
`</port-component-ref>
<!--A list of Handler to use for this service-ref -->
<handler>
<!--` `Must be unique within the module.``-->
<handler-name>MyHandler</handler-name>
<handler-class>org.objectweb.ws.handlers.myHandler</handler-class>
<!-- A list of init-param (couple name/value) for Handler initialization -->
<init-param>
<param-name>param_1</param-name>
<param-value>value_1</param-value>
</init-param>
<!-- A list of QName specifying the SOAP Headers the handler will work on.
- namespace and locapart values must be found inside the WSDL. -->
<soap-header>
<namespaceURI>http://ws.objectweb.org</namespaceURI>
<localpart>MyWSDLHeader</localpart>
</soap-header>
<!-- A list of` `SOAP actor definition that the Handler will play as a role.
a soap-role is a namespace URI.` `-->
<soap-role>http://actor.soap.objectweb.org</soap-role>
<!-- A list of` `port-name element defines the WSDL port-name that a handler
should be associated with.
If no port-name is specified, the handler is assumed to be associated with all ports of the service-ref.``-->
<port-name>myWSDLPort</port-name>
</handler>
</service-ref>`

### B. The jonas-service-ref element

A jonas-service-ref must be specified for each service-ref declared in the standard Deployment Descriptor. The jonas-service-ref adds JOnAS-specific (and WebService engine-specific) information to service-ref elements.
Example of jonas-service-ref:

`<jonas-service-ref>
` `<!-- Define the service-ref contained in the component
deployment descriptor (web.xml or ejb-jar.xml).
used as a key to associate a service-ref to its correspondent jonas-service-ref-->
` `<service-ref-name>services/myService</service-ref-name>
` `<!-- Define the physical name of the resource. -->
` `<jndi-name>webservice_1</jndi-name>
<!-- A list of init-param used for specific configuration of the service -->
<jonas-init-param>
<param-name>serviceClassName</param-name>
<param-value>org.objectweb.ws.services.myServiceImpl</param-value>
</jonas-init-param>
</jonas-service-ref>`

## 6. Limitations

- The jaxrpx-mapping-file is used only to retrieve XML namespace to java package information mapping. All other information is not used at this time (Axis limitation).
- service-endpoint-interface in port-component and port-component-ref is read, but not used.
- port-component-link element is not supported

last update : 17 September 2003