Copyright © 2009 OW2 Consortium
This work is licensed under the Creative Commons Attribution-ShareAlike License. To view a copy of this license,visit http://creativecommons.org/licenses/by-sa/2.0/deed.en or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
JAX-WS stands for Java API for XML WebServices. It's a technology used to implement webservices endpoints and webservices clients communicating using XML.
SOAP and XML messaging is a complex domain, but JAX-WS aims to hide the complexity of that domain. Endpoint development is an easy task: the developer writes a Java interface that will defines the available webservices operations, writes a concrete class (can be multiple class in case of inheritance) that will implement the Java interface. A minimal set of annotations is required to declares the class and interface as webservices. Writing webservices client is also an easy task: using generated classes from a given WSDL, the client can access the webservice without knowing any technical details. This is the role of the JAX-WS engine to do all the XML marshalling/unmarshalling, SOAP processing, ...
With JAX-WS, developers takes both advantages of a standard Java webservices specification (portability) and of the Java platform independence (OS/hardware neutral). Moreover, with JAX-WS (and webservices in general), a client can access a webservice not implemented with Java and vice versa. This is possible because JAX-WS respects the W3C recommendations (World Wide Web Consortium) for HTTP, SOAP and WSDL (WebServices Description Language).
A Webservice endpoint is the implementation of a webservice. It's a server side artifact that can answer to webservices requests.
An endpoint can be implemented using a POJO or using a Stateless EJB3.
Two approaches can be used to develop an endpoint:
Starting from Java
Starting from WSDL
Taking one of theses 2 approaches is the developer's choice.
Choosing a Java-first approach is typical of a webservices development from scratch.
The service endpoint interface (SEI) is a Java interface that specified the methods that will be exposed as webservices operations. This interface is required to be annotated with the @WebService annotation.
@WebService(name="QuoteReporter", targetNamespace="http://jonas.ow2.org/examples/jaxws/quote") public interface QuoteReporter { public Quote getQuote(@WebParam(name="ticker") String ticker); }
The @WebService annotation, placed on a SEI, provides the information required to generate a valid WSDL:
name: this value will be used as the
wsdl:portType
name in the generated WSDL
targetNamespace: this value will be used as the XML namespace containing the WSDL.
It's required that this value is a URI, it's NOT required to use an URL or that this URL is accessible.
Note | |
---|---|
Annotating the SEI will provides all the necessary information to build an abstract WSDL (types + messages + portType). |
The @WebParam
annotation is placed on the method parameter because Java compilation
do not store the parameter name ('ticker' here) in the byte code.
Having a @WebParam ensure that the generated WSDL will always have the
correct operation parameter names.
Once the SEI has been created, the developer has to implement the SEI.
@WebService(portName="QuoteReporterPort", serviceName="QuoteReporterService", targetNamespace="http://jonas.ow2.org/examples/jaxws/quote", endpointInterface="org.ow2.jonas.examples.jaxws.quote.QuoteReporter") public class QuoteReporterBean implements QuoteReporter { public Quote getQuote(final String ticker) { return new Quote(ticker, Math.random() * 100); } }
Once again, the developer has to annotate its class with the @WebService annotation.
portName: this value specifies the wsdl:port
to
be used
serviceName: this value specifies the
wsdl:service
to be used
targetNamespace: this value specifies the targetNamespace of
the wsdl:service
endpointInterface: this value specifies the service endpoint interface classname (SEI)
That's it, a first simple webservice endpoint code ! The next section will focus on the most important webservices annotations.
Once you have a codebase fully annotated, you may choose to generate a WSDL contract.
Note | |
---|---|
With JOnAS 5.1 M4, there is no simple way to perform a wsdl2java operation, although the Apache CXF ant tasks are available. Next releases will provide more examples and documentation about the generation process. |
In the WSDL first approach, the developer is required to implement a webservice that is constrained by a WSDL contract.
In that case, 2 options are available:
Generates, from the WSDL, the SEI interface and an implementation skeleton.
Implements a Provider that will allow the developer to work at the XML level.
JAX-WS tools are provided to help the developers to quickly start to implement business code by generating most of the plumbing. wsdl2java for a webservice endpoint will generate the following artifacts:
{portType}.java: this is the fully annotated SEI interface. By default, its name is based on the wsdl:portType name.
{portType}Impl.java: this is an implementation skeleton, annotated with @WebService. The developer just have to fill the blanks in this class.
{types}.java + ObjectFactory.java: theses JAXB generated classes represents the operations parameters and documents.
Note | |
---|---|
Insert here a picture of generated classes. |
A SEI generated by a JAX-WS 2.1 compatible tool look like this:
JAX-WS allows developers to write endpoints dealing directly with XML messages using the Provider interface. This can be done by implementing Provider<Source> or Provider<SOAPMessage> or Provider<DataSource>.
T invoke(T request) throws WebServiceException;
Supported parameter's types are: Source, SOAPMessage, DataSource. They define the format of the data that will be manipulated inside the invoke method. What will be available in theses data structures depends on the ServiceMode specified. ServiceMode can be either MESSAGE or PAYLOAD (PAYLOAD being the default when no mode is specified):
ServiceMode.MESSAGE: The structure will represent the whole request message (allowing access to the SOAP envelop and SOAP headers for example)
ServiceMode.PAYLOAD: The structure will represent only the body of the request (restricting access to business data located inside the SOAP Body element)
When writing a Provider, the webservice developer MUST starts with a WSDL, because the Provider implementation do not provide any exploitable information about the XML data structures expected (such as bean class parameters and such).
Note | |
---|---|
Providers cannot be implemented using Stateless EJB. |
Providers implementation supports the one way MEP (Message Exchange Pattern) simply by returning null.
Although many modes and types combinations are possibles, there are some logical restrictions given the Binding type (HTTP, SOAP) in use.
Supported combinations are described below.
In the absence of any customization (like applying a @BindingType annotation on the Provider), the binding is assumed to be SOAP 1.1.
Caution | |
---|---|
Provider<SOAPMessage> used in conjunction with a ServiceMode set to PAYLOAD is invalid. Indeed the SOAPMessage type represents the whole message, not just the SOAP Body element. |
Caution | |
---|---|
Provider<DataSource> is always invalid when used with a SOAP Binding. |
Using a Provider<Source> with the MESSAGE mode is used to change the message's content (provided as a javax.xml.transform.Source object) using XSLT Transformers.
@WebServiceProvider @ServiceMode(Service.Mode.MESSAGE) public class ProviderImpl implements Provider<Source> { public Source invoke(Source message) { // Process the request ... // Prepare the response Source Source response = ...; return response; } }
Using a Provider<Source> with the PAYLOAD mode is used to change the message's payload (provided as a javax.xml.transform.Source object) using XSLT Transformers.
@WebServiceProvider public class ProviderImpl implements Provider<Source> { public Source invoke(Source source) { // Process the request ... // Prepare the response Source Source response = ...; return response; } }
Using a Provider<SOAPMessage> with the MESSAGE mode is used to change the message's content (provided as a javax.xml.soap.SOAPMessage object) with a DOM-like API.
@WebServiceProvider @ServiceMode(Service.Mode.MESSAGE) public class ProviderImpl implements Provider<SOAPMessage> { public SOAPMessage invoke(SOAPMessage message) { // Process the request ... // Prepare the response SOAPMessage SOAPMessage response = ...; return response; } }
Caution | |
---|---|
Provider<SOAPMessage> used in conjunction with a ServiceMode set to PAYLOAD is invalid. Indeed the |
Providers can also be implemented using the HTTP binding. That means that no SOAP messages are involved and that the interaction will only be based on XML/HTTP.
Caution | |
---|---|
Provider<DataSource> used in conjunction with a ServiceMode set to PAYLOAD is invalid. |
Caution | |
---|---|
Provider<SOAPMessage> is always invalid when used with an HTTP Binding. Indeed, using the HTTP binding assume that the messages are not SOAP messages. |
Using a Provider<Source> with the MESSAGE mode and the HTTP binding is used to change the message's content (provided as a javax.xml.transform.Source object) using XSLT Transformers.
@WebServiceProvider @ServiceMode(Service.Mode.MESSAGE) @BindingType(HTTPBinding.HTTP_BINDING) public class ProviderImpl implements Provider<Source> { public Source invoke(Source message) { // Process the request ... // Prepare the response Source Source response = ...; return response; } }
Using a Provider<Source> with the PAYLOAD mode and the HTTP binding is used to change the message's body (provided as a javax.xml.transform.Source object) using XSLT Transformers.
@WebServiceProvider @BindingType(HTTPBinding.HTTP_BINDING) public class ProviderImpl implements Provider<Source> { public Source invoke(Source message) { // Process the request ... // Prepare the response Source Source response = ...; return response; } }
Using a Provider<DataSource> with the MESSAGE mode and the HTTP binding is used to process the message attachment (provided as a javax.xml.transform.Source object). This style of provider is useful when dealing only with message's attachments (no XML changes).
@WebServiceProvider @ServiceMode(Service.Mode.MESSAGE) @BindingType(HTTPBinding.HTTP_BINDING) public class ProviderImpl implements Provider<DataSource> { public DataSource invoke(DataSource message) { // Process the request ... // Prepare the response DataSource DataSource response = ...; return response; } }
The table below summarizes the requirement with all the possible combinations ([1]).
XML/HTTP Binding | SOAP/HTTP Binding | |
---|---|---|
Provider<Source> | ||
Payload | Primary part or content as Source | SOAP Body from the primary part or SOAP Body as Source |
Message | Primary part or content as Source | SOAP Envelope from the primary part or SOAP Envelope as Source |
Provider<DataSource> | ||
Payload | Not Valid [1] | Not Valid [1] |
Message | DataSource as an object | Not Valid [2] |
Provider<SOAPMessage> | ||
Payload | Not Valid [3] | Not Valid [3] |
Message | Not Valid [4] | SOAPMessage as an object |
[1]
Note | |
---|---|
Provider<DataSource> in SOAP/HTTP is not valid since attachments in SOAP are sent using Provider<SOAPMessage>. |
Some annotations values can be overridden in a Java EE application server using the webservices.xml (located in WEB-INF/ or META-INF/ given the implementor is respectively a POJO or an EJB).
The link between @WebService (or @WebServiceProvider) and the XML <port-component> description is done through the <service-impl-bean> element:
<ejb-link> with an ejb-name pointing to a Stateless EJB3 annotated with @WebService / @WebServiceProvider.
<servlet-link> with a servlet-name pointing to a Servlet declaration in the web.xml.
Table 1.1. Overriding @WebService
Annotation | Deployment descriptor element | Comment |
---|---|---|
@WebService | <webservices>/<webservice-description>/<port-component> | One @WebService per <port-component> |
@WebService.wsdlLocation | <webservices>/<webservice-description>/<wsdl-file> | Overrides the WSDL location value for all the <port-component> declared in the <webservice-description> |
@WebService.name | <webservices>/<webservice-description>/<port-component>/<port-component-name> | |
@WebService.serviceName | <webservices>/<webservice-description>/<port-component>/<wsdl-service> | |
@WebService.portName | <webservices>/<webservice-description>/<port-component>/<wsdl-port> | |
@WebService.endpointInterface | <webservices>/<webservice-description>/<port-component>/<service-endpoint-interface> |
Table 1.2. Overriding @WebServiceProvider
Annotation | Deployment descriptor element | Comment |
---|---|---|
@WebServiceProvider | <webservices>/<webservice-description>/<port-component> | One @WebServiceProvider per <port-component> |
@WebServiceProvider.wsdlLocation | <webservices>/<webservice-description>/<wsdl-file> | Overrides the WSDL location value for all the <port-component> declared in the <webservice-description> |
@WebService.serviceName | <webservices>/<webservice-description>/<port-component>/<wsdl-service> | |
@WebService.portName | <webservices>/<webservice-description>/<port-component>/<wsdl-port> | |
@WebService.endpointInterface | N/A | It is not required for a Provider to specify a SEI |
Table 1.3. Overriding @BindingType
Deployment descriptor | Possible values |
---|---|
<port-component>/<protocol-binding> |
Specify the protocol binding used by this port-component. The following alias are supported:
|
<port-component>/<enable-mtom> | This element permits to enable/disable the SOAP MTOM/XOP
mechanism for the endpoint. This element has higher priority
than <protocol-binding>, meaning that if
##SOAP11_HTTP_MTOM is specified as protocol
binding and <enable-mtom> is false, it will be equivalent
to a protocol binding set to
##SOAP11_HTTP |
When the webservices implementation has been finished, code compiled, it's time to take care of the application packaging. There are some simple packaging rules to follow.
When the endpoint is implemented as a POJO, the implementation class may be referenced as a servlet in the WEB-INF/web.xml. If it is not declared in the web.xml, it will be auto discovered at deployment time. If it is declared in the web.xml, it must be specified as a new servlet element and the servlet must have an associated servlet-mapping.
<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" version="2.5"> <servlet> <servlet-name>{servlet-name}</servlet-name> <servlet-class>{implementor-fully-qualified-classname}</servlet-class> </servlet> <servlet-mapping> <servlet-name>{servlet-name}</servlet-name> <url-pattern>{webservice-endpoint-url-pattern}</url-pattern> </servlet-mapping> </web-app>
A usual servlet name: unique among other servlets. |
|
The implementor fully qualified classname (It's not a Servlet, but that's OK, it will be changed during deployment). |
|
The same servlet name specified first in the servlet element. |
|
The URL pattern that will point to the webservice endpoint. |
Caution | |
---|---|
If the endpoint is declared in the
|
If the WSDL is referenced from the endpoint (using
@WebService.wsdlLocation(), @WebServiceProvider.wsdlLocation() or
webservices.xml), it has to be provided in the WEB-INF/wsdl/
directory of the
webapp.
The webservice endpoint contained in the webapp will be available through an URL.
If no servlet-mapping was specified in the web.xml a default mapping will be automatically introduced.
Table 1.4. Automatic Web Endpoints Servlet Mappings Patterns
Condition | Servlet Mapping Pattern |
---|---|
serviceName has been
provided in the @WebService(s) |
/{service-qname-local-part} |
no serviceName
provided |
/{simple-implementor-classname}Simple |
When the webservice endpoint is implemented as a Stateless EJB
As an ejbjar is not a webapp, there is no available web context, or url-pattern that can be used to access the endpoint through HTTP.
A Web context is created and named after the ejbjar's filename (stopping at the first '_' character).
Table 1.5. Automatic EJB Endpoints Servlet Mappings Patterns
Condition | Servlet Mapping Pattern |
---|---|
<endpoint-address> provided for the bean in the easybeans.xml | provided value |
serviceName has been
provided in the @WebService(s) |
/{service-qname-local-part} |
no serviceName
provided |
/{simple-implementor-classname}Simple |
[1] Source Arun Gupta (http://weblogs.java.net/blog/arungupta/archive/2006/03/jaxws_20_provid_1.html)
A Webservice consumer is a client of a webservice endpoint. It's a client side artifact that perform webservices requests.
With JAX-WS, clients can benefits of asynchronous invocations (more on this later).
A webservice consumer can be any of the following Java EE components: EJB (Session/MessageDriven), Servlet (or any web components such as JSP, JSF, ...) or Application Client. For any of theses components, the creation process is the same.
A consumer typically starts with a WSDL (describing the endpoint's contract), but dynamic invocation (working at the XML level) can also be performed.
A webservice consummer can be implemented using a Port. A Port is a Java interface that hides to the client all the WS low level mechanisms (masrshalling, unmarshalling, handler chains, ...).
A Port is usually generated from a WSDL.
When the client's developer starts with a WSDL, it usually generates the client artifacts (Java classes) using a wsdl2java tool.
Note | |
---|---|
With JOnAS 5.1 M4, there is no simple way to perform a wsdl2java operation, although the Apache CXF ant tasks are available. Next releases will provide more examples and documentation about the generation process. |
Using synchronous consumer is the easiest way of consuming a webservice: by default, wsdl2java tools generate classes supporting only synchronous operations.
The following code snippet shows the Port source code that a wsdl2java tool generate using an input WSDL file.
@WebService(targetNamespace = "http://jonas.ow2.org/samples/jaxws/calculator", name = "Calculator") public interface Calculator { @ResponseWrapper(localName = "addResponse", targetNamespace = "http://jonas.ow2.org/samples/jaxws/calculator", className = "org.ow2.jonas.samples.jaxws.calculator.AddResponse") @RequestWrapper(localName = "add", targetNamespace = "http://jonas.ow2.org/samples/jaxws/calculator", className = "org.ow2.jonas.samples.jaxws.calculator.Add") @WebResult(name = "return", targetNamespace = "") @WebMethod public int add(@WebParam(name = "arg0", targetNamespace = "") int arg0, @WebParam(name = "arg1", targetNamespace = "") int arg1); }
By default, WSDL2Java generation do not generate asynchronous methods for each operation of the wsdl:portType.
To enable the async method generation, a binding customization has to be provided during the WSDL2Java execution.
It can be provided as part of the WSDL file:
<portType name="CalculatorPort"> <operation name="add"> <input message="tns:addRequest"/> <output message="tns:addResponse"/> </operation> </portType> <binding name="CalculatorBinding" type="tns:CalculatorPort"> <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/> <operation name="add"> <soap:operation soapAction=""/> <input> <soap:body use="literal"/></input> <output> <soap:body use="literal"/> </output> </operation> </binding>
Or as a separate bindings declaration file:
<bindings xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns="http://java.sun.com/xml/ns/jaxws"
wsdlLocation="...">
<bindings node="wsdl:definitions">
<package name="org.ow2.jonas.ws.async.client"/>
<enableAsyncMapping>true</enableAsyncMapping>
</bindings>
</bindings>
// Synchronous method public int add(int a, int b); // Asynchronous polling method public Response<AddResponse> add(int a, int b); // Asynchronous callback method public Future<?> add(int a, int b, AsyncHandler<AddResponse>);
A Dispatch<T> is an object that allows the client to perform XML level operations. It is the client side equivalent to the Provider<T> interface.
A Webservice endpoint is the web service implementation. It's a server side artifact. It can be implemented as a POJO or as a Stateless EJB.
Also known as a webservice client. It is a client side artifact.
JAX-WS generated artifacts (classes / WSDL / XSD) that are portable across JAX-WS implementation. It means that artifacts generated using Sun RI tools will be usable without any changes on any Java EE 5 compliant application server.
Endpoint can be implemented as Providers if they require low level XML access.
A Handler can be seen like a webservice interceptor. It can be used on client and/or server side. Two kinds of handlers exists: Logical and SOAP handlers.
A Dispatch is a webservice client working at the XML level. A Dispatch is the client side equivalent to a Provider.
Plain Old Java Object. Commonly used word meaning that the beans do not have to implement an interface to be usable by the container.
XML Qualified Name. Disambiguate XML names by prefixing the names (local-part) with a namespace (URI).
Message Exchange Pattern. This is the pattern of the exchange (one-way, request-response, ...).
Service Endpoint Interface. This is an annotated Java interface that represents the business object.
Message Transmission Optimization Mechanism. This is a W3C recommendation defining a method to efficiently sending binary data to and from webservices.
Web Service Description Language. This is the cornerstone of the webservices system. It is an XML file that can basically be compared to a Java interface: it's the contract defining the wire exchange (possible operations, expected types and parameters, ...) between a consumer and an endpoint.