<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" | |
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> | |
<html xmlns="http://www.w3.org/1999/xhtml"> | |
<head> | |
<title>JAX-WS Guide</title> | |
</head> | |
<body> | |
<h1>JAX-WS Guide</h1> | |
<h2>Table of Contents</h2> | |
<ol> | |
<li><a href="#JAXWSIntro">Introduction to JAX-WS</a></li> | |
<li><a href="#JAXBIntro">Introduction to JAXB</a></li> | |
<li> | |
<a href="#DevelopService">Developing JAX-WS Web services</a> | |
<ol type='a'> | |
<li><a href="#BottomUpService">From a JavaBean | |
(bottom-up)</a></li> | |
<li><a href="#TopDownService">From a WSDL document | |
(top-down)</a></li> | |
</ol> | |
</li> | |
<li> | |
<a href="#DeployService">Packaging and deploying a JAX-WS | |
service</a> | |
<ol type='a'> | |
<li><a href="#ProxyClient">Developing a JAX-WS client from | |
a WSDL document</a></li> | |
<li><a href="#DispatchClient">Developing a dynamic client | |
using JAX-WS APIs</a></li> | |
</ol> | |
</li> | |
<li><a href="#DevelopClient">Developing JAX-WS clients</a></li> | |
<li><a href="#RunClient">Running a JAX-WS client</a></li> | |
<li><a href="#Async">Invoking JAX-WS Web services | |
asynchronously</a></li> | |
<li><a href="#Handlers">Using handlers in JAX-WS Web | |
services</a></li> | |
<li><a href="#HTTPSession">Enabling HTTP session management | |
support for JAX-WS applications</a></li> | |
<li><a href="#MTOM">Enabling MTOM</a></li> | |
</ol> | |
<h2><a name="JAXWSIntro" id="JAXWSIntro">Introduction to | |
JAX-WS</a></h2>JAX-WS 2.0 is a new programming model that | |
simplifies application development through support of a standard, | |
annotation-based model to develop Web Service applications and | |
clients. The JAX-WS 2.0 specification strategically aligns itself | |
with the current industry trend towards a more document-centric | |
messaging model and replaces the remote procedure call | |
programming model as defined by JAX-RPC. JAX-WS is the strategic | |
programming model for developing Web services and is a required | |
part of the Java Platform, Enterprise Edition 5 (Java EE 5). The | |
implementation of the JAX-WS programming standard provides the | |
following enhancements for developing Web services and clients: | |
<ul> | |
<li>Better platform independence for Java applications.</li> | |
<li style="list-style: none"><br /> | |
Using JAX-WS APIs, development of Web services and clients is | |
simplified with better platform independence for Java | |
applications. JAX-WS takes advantage of the dynamic proxy | |
mechanism to provide a formal delegation model with a pluggable | |
provider. This is an enhancement over JAX-RPC, which relies on | |
the generation of vendor-specific stubs for invocation.<br /> | |
<br /></li> | |
<li>Annotations</li> | |
<li style="list-style: none"> | |
<br /> | |
JAX-WS introduces support for annotating Java classes with | |
metadata to indicate that the Java class is a Web service. | |
JAX-WS supports the use of annotations based on the Metadata | |
Facility for the Java Programming Language (JSR 175) | |
specification, the Web Services Metadata for the Java | |
Platform (JSR 181) specification and annotations defined by | |
the JAX-WS 2.0 specification. Using annotations within the | |
Java source and within the Java class simplifies development | |
of Web services by defining some of the additional | |
information that is typically obtained from deployment | |
descriptor files, WSDL files, or mapping metadata from XML | |
and WSDL files into the source artifacts.<br /> | |
<br /> | |
For example, you can embed a simple @WebService tag in the | |
Java source to expose the bean as a Web service. | |
<pre> | |
@WebService | |
public class QuoteBean implements StockQuote { | |
public float getQuote(String sym) { ... } | |
} | |
</pre>The <code>@WebService</code> annotation tells the server | |
runtime to expose all public methods on that bean as a Web service. | |
Additional levels of granularity can be controlled by adding | |
additional annotations on individual methods or parameters. Using | |
annotations makes it much easier to expose Java artifacts as Web | |
services. In addition, as artifacts are created from using some of | |
the top-down mapping tools starting from a WSDL file, annotations | |
are included within the source and Java classes as a way of | |
capturing the metadata along with the source files.<br /> | |
Using annotations also improves the development of Web | |
services within a team structure because you do not need to | |
define every Web service in a single or common deployment | |
descriptor as required with JAX-RPC Web services. Taking | |
advantage of annotations with JAX-WS Web services allows | |
parallel development of the service and the required | |
metadata.<br /> | |
<br /> | |
</li> | |
<li>Invoking Web services asynchronously</li> | |
<li style="list-style: none"> | |
<br /> | |
With JAX-WS, Web services are called both synchronously and | |
asynchronously. JAX-WS adds support for both a polling and | |
callback mechanism when calling Web services asynchronously. | |
Using a polling model, a client can issue a request, get a | |
response object back, which is polled to determine if the | |
server has responded. When the server responds, the actual | |
response is retrieved. Using the callback model, the client | |
provides a callback handler to accept and process the inbound | |
response object. Both the polling and callback models enable | |
the client to focus on continuing to process work without | |
waiting for a response to return, while providing for a more | |
dynamic and efficient model to invoke Web services.<br /> | |
<br /> | |
For example, a Web service interface might have methods for | |
both synchronous and asynchronous requests. Asynchronous | |
requests are identified in bold below: | |
<pre> | |
@WebService | |
public interface CreditRatingService { | |
// sync operation | |
Score getCreditScore(Customer customer); | |
// async operation with polling | |
<b>Response<Score></b> getCreditScoreAsync(Customer customer); | |
// async operation with callback | |
<b>Future<?></b> getCreditScoreAsync(Customer customer, | |
<b>AsyncHandler<Score></b> handler); | |
} | |
</pre>The asynchronous invocation that uses the callback mechanism | |
requires an additional input by the client programmer. The callback | |
is an object that contains the application code that will be | |
executed when an asynchronous response is received. The following | |
is a code example for an asynchronous callback handler: | |
<pre> | |
CreditRatingService svc = ...; | |
<b>Future<?></b> invocation = svc.getCreditScoreAsync(customerFred, | |
<b>new AsyncHandler<Score>() { | |
public void handleResponse ( | |
Response<Score> response) | |
{ | |
Score score = response.get(); | |
// do work here... | |
} | |
}</b> | |
); | |
</pre>The following is a code example for an asynchronous polling | |
client: | |
<pre> | |
CreditRatingService svc = ...; | |
<b>Response<Score> response</b> = svc.getCreditScoreAsync(customerFred); | |
while (<b>!response.isDone()</b>) { | |
// do something while we wait | |
} | |
// no cast needed, thanks to generics | |
Score score = <b>response.get()</b>; | |
</pre><br /> | |
<br /> | |
</li> | |
<li>Using resource injection</li> | |
<li style="list-style: none">JAX-WS supports resource injection | |
to further simplify development of Web services. JAX-WS uses | |
this key feature of Java EE 5 to shift the burden of creating | |
and initializing common resources in a Java runtime environment | |
from your Web service application to the application container | |
environment itself. JAX-WS provides support for a subset of | |
annotations that are defined in JSR-250 for resource injection | |
and application lifecycle in its runtime.<br /> | |
Axis2 supports the JAX-WS usage of the <code>@Resource</code> | |
annotation for resource injection. The <code>@Resource</code> | |
annotation is defined by the JSR-250, Common Annotations | |
specification that is included in Java Platform, Enterprise | |
Edition 5 (Java EE 5). By placing the <code>@Resource</code> | |
annotation on a service endpoint implementation, you can | |
request a resource injection and collect the | |
<code>javax.xml.ws.WebServiceContext</code> interface related | |
to that particular endpoint invocation. When the endpoint | |
sees the <code>@Resource</code> annotation, the endpoint adds | |
the annotated variable with an appropriate value before the | |
servlet is placed into service. From the | |
<code>WebServiceContext</code> interface, you can collect the | |
<code>MessageContext</code> for the request associated with | |
the particular method call using the | |
<code>getMessageContext()</code> method.<br /> | |
<br /> | |
The following example illustrates using the | |
<code>@Resource</code> annotation for resource injection: | |
<pre>@WebService | |
public class MyService { | |
@Resource | |
private WebServiceContext ctx; | |
public String echo (String input) { | |
… | |
} | |
} | |
</pre>Refer to sections 5.2.1 and 5.3 of the JAX-WS 2.0 | |
specification for more information on resource injection.<br /> | |
<br /> | |
</li> | |
<li>Data binding with Java Architecture for XML Binding (JAXB) | |
2.0</li> | |
<li style="list-style: none"><br /> | |
JAX-WS leverages the JAXB 2.0 API and tools as the binding | |
technology for mappings between Java objects and XML documents. | |
JAX-WS tooling relies on JAXB tooling for default data binding | |
for two-way mappings between Java objects and XML | |
documents.<br /> | |
<br /></li> | |
<li>Dynamic and static clients</li> | |
<li style="list-style: none"><br /> | |
The dynamic client API for JAX-WS is called the dispatch client | |
(<code>javax.xml.ws.Dispatch</code>). The dispatch client is an | |
XML messaging oriented client. The data is sent in either | |
<code>PAYLOAD</code> or <code>MESSAGE</code> mode. When using | |
the <code>PAYLOAD</code> mode, the dispatch client is only | |
responsible for providing the contents of the <soap:Body> | |
and JAX-WS adds the <soap:Envelope> and | |
<soap:Header> elements. When using the | |
<code>MESSAGE</code> mode, the dispatch client is responsible | |
for providing the entire SOAP envelope including the | |
<soap:Envelope>, <soap:Header>, and | |
<soap:Body> elements and JAX-WS does not add anything | |
additional to the message. The dispatch client supports | |
asynchronous invocations using a callback or polling | |
mechanism.<br /> | |
The static client programming model for JAX-WS is the called | |
the proxy client. The proxy client invokes a Web service based | |
on a Service Endpoint interface (SEI) which must be | |
provided.<br /> | |
<br /></li> | |
<li>Support for Message Transmission Optimized Mechanism | |
(MTOM)</li> | |
<li style="list-style: none"><br /> | |
Using JAX-WS, you can send binary attachments such as images or | |
files along with Web services requests. JAX-WS adds support for | |
optimized transmission of binary data as specified by Message | |
Transmission Optimization Mechanism (MTOM).<br /> | |
<br /></li> | |
<li>Multiple data binding technologies</li> | |
<li style="list-style: none"><br /> | |
JAX-WS exposes the following binding technologies to the end | |
user: XML Source, SOAP Attachments API for Java (SAAJ) 1.3, and | |
Java Architecture for XML Binding (JAXB) 2.0. XML Source | |
enables a user to pass a javax.xml.transform.Source into the | |
runtime which represents the data in a Source object to be | |
processed. SAAJ 1.3 now has the ability to pass an entire SOAP | |
document across the interface rather than just the payload | |
itself. This is done by the client passing the SAAJ | |
<code>SOAPMessage</code> object across the interface. JAX-WS | |
leverages the JAXB 2.0 support as the data binding technology | |
of choice between Java and XML.<br /> | |
<br /></li> | |
<li>Support for SOAP 1.2</li> | |
<li style="list-style: none"><br /> | |
Support for SOAP 1.2 has been added to JAX-WS 2.0. JAX-WS | |
supports both SOAP 1.1 and SOAP 1.2 so that you can send binary | |
attachments such as images or files along with Web services | |
requests. JAX-WS adds support for optimized transmission of | |
binary data as specified by MTOM.<br /> | |
<br /></li> | |
<li>New development tools</li> | |
<li style="list-style: none"> | |
<br /> | |
JAX-WS provides the <b>wsgen</b> and <b>wsimport</b> | |
command-line tools for generating portable artifacts for | |
JAX-WS Web services. When creating JAX-WS Web services, you | |
can start with either a WSDL file or an implementation bean | |
class. If you start with an implementation bean class, use | |
the wsgen command-line tool to generate all the Web services | |
server artifacts, including a WSDL file if requested. If you | |
start with a WSDL file, use the wsimport command-line tool to | |
generate all the Web services artifacts for either the server | |
or the client. The wsimport command line tool processes the | |
WSDL file with schema definitions to generate the portable | |
artifacts, which include the service class, the service | |
endpoint interface class, and the JAXB 2.0 classes for the | |
corresponding XML schema. | |
<h2><a name="JAXBIntro" id="JAXBIntro">Introduction to | |
JAXB</a></h2>Java Architecture for XML Binding (JAXB) is a | |
Java technology that provides an easy and convenient way to | |
map Java classes and XML schema for simplified development of | |
Web services. JAXB leverages the flexibility of | |
platform-neutral XML data in Java applications to bind XML | |
schema to Java applications without requiring extensive | |
knowledge of XML programming.<br /> | |
<br /> | |
Axis2 provides JAXB 2.0 standards.<br /> | |
<br /> | |
JAXB is an XML to Java binding technology that supports | |
transformation between schema and Java objects and between | |
XML instance documents and Java object instances. JAXB | |
consists of a runtime application programming interface (API) | |
and accompanying tools that simplify access to XML documents. | |
JAXB also helps to build XML documents that both conform and | |
validate to the XML schema.<br /> | |
<br /> | |
JAXB provides the <b>xjc</b> schema compiler tool, the | |
<b>schemagen</b> schema generator tool, and a runtime | |
framework. You can use the <b>xjc</b> schema compiler tool to | |
start with an XML schema definition (XSD) to create a set of | |
JavaBeans that map to the elements and types defined in the | |
XSD schema. You can also start with a set of JavaBeans and | |
use the <b>schemagen</b> schema generator tool to create the | |
XML schema. Once the mapping between XML schema and Java | |
classes exists, XML instance documents can be converted to | |
and from Java objects through the use of the JAXB binding | |
runtime API. Data stored in XML documents can be accessed | |
without the need to understand the data structure. You can | |
then use the resulting Java classes to assemble a Web | |
services application.<br /> | |
<br /> | |
JAXB annotated classes and artifacts contain all the | |
information needed by the JAXB runtime API to process XML | |
instance documents. The JAXB runtime API supports marshaling | |
of JAXB objects to XML and unmarshaling the XML document back | |
to JAXB class instances. Optionally, you can use JAXB to | |
provide XML validation to enforce both incoming and outgoing | |
XML documents to conform to the XML constraints defined | |
within the XML schema.<br /> | |
<br /> | |
JAXB is the default data binding technology used by the Java | |
API for XML Web Services (JAX-WS) 2.0 tooling and | |
implementation within this product. You can develop JAXB | |
objects for use within JAX-WS applications.<br /> | |
<br /> | |
You can also use JAXB independently of JAX-WS when you want | |
to leverage the XML data binding technology to manipulate XML | |
within your Java applications.<br /> | |
<br /> | |
The following diagram illustrates the JAXB | |
architecture.<br /> | |
<img src="images/JAXB_architecture.gif" width="600" height="301" | |
border="0" alt="" /> | |
<h2><a name="DevelopService" id="DevelopService">Developing | |
JAX-WS Web services</a></h2> | |
<h3><a name="BottomUpService" id="BottomUpService">Developing | |
a JAX-WS Web service from a JavaBean (bottom-up | |
development)</a></h3>When developing a JAX-WS Web service | |
starting from JavaBeans, you can use a bean that already | |
exists and then enable the implementation for JAX-WS Web | |
services. The use of annotations simplifies the enabling of a | |
bean for Web services. Adding the <code>@WebService</code> | |
annotation to the bean defines the application as a Web | |
service and how a client can access the Web service. | |
JavaBeans can have a service endpoint interface, but it is | |
not required. Enabling JavaBeans for Web services includes | |
annotating the bean and the optional service endpoint | |
interface, assembling all artifacts required for the Web | |
service, and deploying the application into Axis2. You are | |
not required to develop a WSDL file because the use of | |
annotations can provide all of the WSDL information necessary | |
to configure the service endpoint or the client. It is, | |
however, a best practice to develop a WSDL file.<br /> | |
<br /> | |
<ol> | |
<li>Develop a service endpoint interface.</li> | |
<li style="list-style: none"> | |
<br /> | |
Java API for XML-Based Web Services (JAX-WS) supports two | |
different service endpoint implementations types, the | |
standard JavaBeans service endpoint interface and a new | |
<code>Provider</code> interface to enable services to | |
work at the XML message level. By using annotations on | |
the service endpoint or client, you can define the | |
service endpoint as a Web service.<br /> | |
<br /> | |
JavaBeans endpoints in JAX-WS are similar to the endpoint | |
implementations in the Java API for XML-based RPC | |
(JAX-RPC) specification. Unlike JAX-RPC, the requirement | |
for a service endpoint interface (SEI) is optional for | |
JavaBeans-based services. JAX-WS services that do not | |
have an associated SEI are regarded as having an implicit | |
SEI, whereas services that have an associated SEI are | |
regarded as having an explicit SEI. The service endpoint | |
interfaces required by JAX-WS are also more generic than | |
the service endpoint interfaces required by JAX-RPC. With | |
JAX-WS, the SEI is not required to extend the | |
java.rmi.Remote interface as required by the JAX-RPC | |
specification.<br /> | |
<br /> | |
The JAX-WS programming model also leverages support for | |
annotating Java classes with metadata to define a service | |
endpoint application as a Web service and define how a | |
client can access the Web service. JAX-WS supports | |
annotations based on the Metadata Facility for the Java | |
Programming Language (JSR 175) specification, the Web | |
Services Metadata for the Java Platform (JSR 181) | |
specification and annotations defined by the JAX-WS 2.0 | |
(JSR 224) specification, which includes Java Architecture | |
for XML Binding (JAXB) annotations. Using annotations, | |
the service endpoint implementation can independently | |
describe the Web service without requiring a WSDL file. | |
Annotations can provide all of the WSDL information | |
necessary to configure your service endpoint | |
implementation or Web services client. You can specify | |
annotations on the service endpoint interface used by the | |
client and the server, or on the server-side service | |
implementation class.<br /> | |
<br /> | |
To develop a JAX-WS Web service, you must annotate your | |
Java class with the <code>javax.jws.WebService</code> | |
annotation for JavaBeans endpoints or the | |
<code>javax.jws.WebServiceProvider</code> annotation for | |
a Provider endpoint. These annotations define the Java | |
class as a Web service endpoint. For a JavaBeans | |
endpoint, the service endpoint interface or service | |
endpoint implementation is a Java interface or class, | |
respectively, that declares the business methods provided | |
by a particular Web service. The only methods on a | |
JavaBeans endpoint that can be invoked by a Web services | |
client are the business methods that are defined in the | |
explicit or implicit service endpoint interface.<br /> | |
<br /> | |
All JavaBeans endpoints are required to have the | |
<code>@WebService (javax.jws.WebService)</code> | |
annotation included on the bean class. If the service | |
implementation bean also uses an SEI, then that endpoint | |
interface must be referenced by the endpointInterface | |
attribute on that annotation. If the service | |
implementation bean does not use an SEI, then the service | |
is described by the implicit SEI defined in the | |
bean.<br /> | |
<br /> | |
The JAX-WS programming model introduces the new Provider | |
API, <code>javax.xml.ws.Provider</code>, as an | |
alternative to service endpoint interfaces. The | |
<code>Provider</code> interface supports a more messaging | |
oriented approach to Web services. With the | |
<code>Provider</code> interface, you can create a Java | |
class that implements a simple interface to produce a | |
generic service implementation class. The | |
<code>Provider</code> interface has one method, the | |
invoke method, which uses generics to control both the | |
input and output types when working with various messages | |
or message payloads. All Provider endpoints must be | |
annotated with the <code>@WebServiceProvider | |
(javax.xml.ws.WebServiceProvider)</code> annotation. A | |
service implementation cannot specify the | |
<code>@WebService</code> annotation if it implements the | |
<code>javax.xml.ws.Provider</code> interface.<br /> | |
<br /> | |
So the steps involved are: | |
<ol> | |
<li>Identify your service endpoint requirements for | |
your Web services application.</li> | |
<li style="list-style: none"> | |
<br /> | |
First determine if the service implementation is a | |
JavaBeans endpoint or a Provider endpoint. If you | |
choose to use a JavaBeans endpoint, then determine if | |
you want to use an explicit SEI or if the bean itself | |
will have an implicit SEI.<br /> | |
A Java class that implements a Web service must | |
specify either the <code>javax.jws.WebService</code> | |
or <code>javax.xml.ws.WebServiceProvider</code> | |
annotation. Both annotations must not be present on a | |
Java class. The | |
<code>javax.xml.ws.WebServiceProvider</code> | |
annotation is only supported on classes that | |
implement the <code>javax.xml.ws.Provider</code> | |
interface. | |
<ul> | |
<li>If you have an explicit service endpoint | |
interface with the Java class, then use the | |
endpointInterface parameter to specify the service | |
endpoint interface class name to the | |
<code>javax.jws.WebService</code> annotation. You | |
can add the <code>@WebMethod</code> annotation to | |
methods of a service endpoint interface to | |
customize the Java-to-WSDL mappings. All public | |
methods are considered as exposed methods | |
regardless of whether the <code>@WebMethod</code> | |
annotation is specified or not. It is incorrect to | |
have an <code>@WebMethod</code> annotation on an | |
service endpoint interface that contains the | |
<code>exclude</code> attribute.</li> | |
<li>If you have an implicit service endpoint | |
interface with the Java class, then the | |
<code>javax.jws.WebService</code> annotation will | |
use the default values for the | |
<code>serviceName</code>, <code>portName</code>, | |
and <code>targetNamespace</code> parameters. To | |
override these default values, specify values for | |
these parameters in the <code>@WebService</code> | |
annotation. If the <code>@WebMethod</code> | |
annotation is not specified, all public methods are | |
exposed including the inherited methods with the | |
exception of methods inherited from | |
<code>java.lang.Object</code>. The | |
<code>exclude</code> parameter of the | |
<code>@WebMethod</code> annotation can be used to | |
control which methods are exposed.</li> | |
<li>If you are using the <code>Provider</code> | |
interface, use the | |
<code>javax.xml.ws.WebServiceProvider</code> | |
annotation on the Provider endpoint.</li> | |
</ul> | |
</li> | |
<li>Annotate the service endpoints.</li> | |
<li>Implement your service.</li> | |
</ol><br /> | |
<br /> | |
When using a bottom-up approach to develop JAX-WS Web | |
services, use the wsgen command-line tool when starting | |
from a service endpoint implementation. The wsgen tool | |
processes a compiled service endpoint implementation | |
class as input and generates the following portable | |
artifacts: | |
<ul> | |
<li>any additional Java Architecture for XML Binding | |
(JAXB) classes that are required to marshal and | |
unmarshal the message contents. The additional classes | |
include classes that are represented by the | |
@RequestWrapper annotation and the | |
<code>@ResponseWrapper</code> annotation for a wrapped | |
method.</li> | |
<li>a WSDL file if the optional <code>-wsdl</code> | |
argument is specified. The wsgen command does not | |
automatically generate the WSDL file. The WSDL file is | |
automatically generated when you deploy the service | |
endpoint.</li> | |
</ul><br /> | |
You are not required to develop a WSDL file when | |
developing JAX-WS Web services using the bottom-up | |
approach of starting with JavaBeans. The use of | |
annotations provides all of the WSDL information | |
necessary to configure the service endpoint or the | |
client. Axis2 supports WSDL 1.1 documents that comply | |
with Web Services-Interoperability (WS-I) Basic Profile | |
1.1 specifications and are either Document/Literal style | |
documents or RPC/Literal style documents. Additionally, | |
WSDL documents with bindings that declare a USE attribute | |
of value <code>LITERAL</code> are supported while the | |
value, <code>ENCODED</code>, is not supported. For WSDL | |
documents that implement a Document/Literal wrapped | |
pattern, a root element is declared in the XML schema and | |
is used as an operation wrapper for a message flow. | |
Separate wrapper element definitions exist for both the | |
request and the response.<br /> | |
<br /> | |
To ensure the wsgen command does not miss inherited | |
methods on a service endpoint implementation bean, you | |
must either add the <code>@WebService</code> annotation | |
to the desired superclass or you can override the | |
inherited method in the implementation class with a call | |
to the superclass method. Implementation classes only | |
expose methods from superclasses that are annotated with | |
the <code>@WebService</code> annotation.<br /> | |
<br /> | |
Note: The <b>wsgen</b> command does not differentiate the | |
XML namespace between multiple <code>XMLType</code> | |
annotations that have the same <code>@XMLType</code> name | |
defined within different Java packages. When this | |
scenario occurs, the following error is produced: | |
<pre> | |
Error: Two classes have the same XML type name .... | |
Use @XmlType.name and @XmlType.namespace to assign different names to them... | |
</pre>This error indicates you have class names or | |
<code>@XMLType.name</code> values that have the same name, but | |
exist within different Java packages. To prevent this error, add | |
the <code>@XML.Type.namespace</code> class to the existing <code> | |
@XMLType</code> annotation to differentiate between the | |
XML types. | |
</li> | |
<li>Develop the Java artifacts.</li> | |
<li>Package and deploy your service.</li> | |
</ol> | |
<h3><a name="TopDownService" id="TopDownService">Developing a | |
JAX-WS Web service from a WSDL document (top-down | |
development)</a></h3>You can use a top-down development | |
approach to create a JAX-WS Web service with an existing WSDL | |
file using JavaBeans.<br /> | |
<br /> | |
You can use the JAX-WS tool, <b>wsimport</b>, to process a | |
WSDL file and generate portable Java artifacts that are used | |
to create a Web service. The portable Java artifacts created | |
using the <b>wsimport</b> tool are: | |
<ul> | |
<li>Service endpoint interface (SEI)</li> | |
<li>Service class</li> | |
<li>Exception class that is mapped from the | |
<code>wsdl:fault</code> class (if any)</li> | |
<li>Java Architecture for XML Binding (JAXB) generated type | |
values which are Java classes mapped from XML schema | |
types</li> | |
</ul><br /> | |
Run the | |
<pre> | |
wsimport -keep -verbose <i>wsdl_URL</i> | |
</pre>command to generate the portable artifacts. The | |
<code>-keep</code> option tells the tool not to delete the | |
generated files, and the <code>-verbose</code> option tells it to | |
list the files that were created. The ObjectFactory.java file that | |
is created contains factory methods for each Java content interface | |
and Java element interface generated in the associated package. The | |
package-info.java file takes the <code>targetNamespace</code> value | |
and creates the directory structure.<br /> | |
<br /> | |
You must now provide an implementation for the SEI created by | |
the tool. | |
<h2><a name="DeployService" id="DeployService">Packaging and | |
deploying a JAX-WS service</a></h2>Axis2 provides two | |
mechanisms for deploying JAX-WS services: | |
<ol> | |
<li>The service may be packaged and deployed as an AAR, | |
just like any other service within Axis2. Like with all | |
AARs, a services.xml file containing the relevant metadata | |
is required for the service to deploy correctly.</li> | |
<li>The service may be packaged in a jar file and placed | |
into the <code>servicejars</code> directory. The | |
<code>JAXWSDeployer</code> will examine all jars within | |
that directory and deploy those classes that have JAX-WS | |
annotations which identify them as Web services.</li> | |
</ol> | |
<h2><a name="DevelopClient" id="DevelopClient">Developing | |
JAX-WS clients</a></h2>The Java API for XML-Based Web | |
Services (JAX-WS) Web service client programming model | |
supports both the Dispatch client API and the Dynamic Proxy | |
client API. The Dispatch client API is a dynamic client | |
programming model, whereas the static client programming | |
model for JAX-WS is the Dynamic Proxy client. The Dispatch | |
and Dynamic Proxy clients enable both synchronous and | |
asynchronous invocation of JAX-WS Web services.<br /> | |
<br /> | |
<ul> | |
<li>Dispatch client: Use this client when you want to work | |
at the XML message level or when you want to work without | |
any generated artifacts at the JAX-WS level.</li> | |
<li>Dynamic Proxy client: Use this client when you want to | |
invoke a Web service based on a service endpoint | |
interface.</li> | |
</ul> | |
<h4>Dispatch client</h4>XML-based Web services use XML | |
messages for communications between Web services and Web | |
services clients. The JAX-WS APIs provide high-level methods | |
to simplify and hide the details of converting between Java | |
method invocations and their associated XML messages. | |
However, in some cases, you might desire to work at the XML | |
message level. Support for invoking services at the XML | |
message level is provided by the Dispatch client API. The | |
Dispatch client API, <code>javax.xml.ws.Dispatch</code>, is a | |
dynamic JAX-WS client programming interface. To write a | |
Dispatch client, you must have expertise with the Dispatch | |
client APIs, the supported object types, and knowledge of the | |
message representations for the associated WSDL file. The | |
Dispatch client can send data in either <code>MESSAGE</code> | |
or <code>PAYLOAD</code> mode. When using the | |
<code>javax.xml.ws.Service.Mode.MESSAGE</code> mode, the | |
Dispatch client is responsible for providing the entire SOAP | |
envelope including the <code><soap:Envelope></code>, | |
<code><soap:Header></code>, and | |
<code><soap:Body></code> elements. When using the | |
<code>javax.xml.ws.Service.Mode.PAYLOAD</code> mode, the | |
Dispatch client is only responsible for providing the | |
contents of the <code><soap:Body></code> and JAX-WS | |
includes the payload in a <code><soap:Envelope></code> | |
element.<br /> | |
<br /> | |
The Dispatch client API requires application clients to | |
construct messages or payloads as XML which requires a | |
detailed knowledge of the message or message payload. The | |
Dispatch client supports the following types of objects: | |
<ul> | |
<li><code>javax.xml.transform.Source</code>: Use | |
<code>Source</code> objects to enable clients to use XML | |
APIs directly. You can use <code>Source</code> objects with | |
SOAP or HTTP bindings.</li> | |
<li>JAXB objects: Use JAXB objects so that clients can use | |
JAXB objects that are generated from an XML schema to | |
create and manipulate XML with JAX-WS applications. JAXB | |
objects can only be used with SOAP or HTTP bindings.</li> | |
<li><code>javax.xml.soap.SOAPMessage</code>: Use | |
<code>SOAPMessage</code> objects so that clients can work | |
with SOAP messages. You can only use | |
<code>SOAPMessage</code> objects with SOAP bindings.</li> | |
<li><code>javax.activation.DataSource</code>: Use | |
<code>DataSource</code> objects so that clients can work | |
with Multipurpose Internet Mail Extension (MIME) messages. | |
Use <code>DataSource</code> only with HTTP bindings.</li> | |
</ul><br /> | |
For example, if the input parameter type is | |
javax.xml.transform.Source, the call to the Dispatch client | |
API is similar to the following code example: | |
<pre>Dispatch<strong><Source></strong> dispatch = … create a Dispatch<strong><Source></strong> | |
Source request = … create a Source object | |
Source response = dispatch.invoke(request);</pre>The Dispatch parameter value determines the return type of | |
the <code>invoke()</code> method.<br /> | |
<br /> | |
The Dispatch client is invoked in one of three ways:<br /> | |
<ul> | |
<li>Synchronous invocation for requests and responses using | |
the <code>invoke</code> method</li> | |
<li>Asynchronous invocation for requests and responses | |
using the <code>invokeAsync</code> method with a callback | |
or polling object</li> | |
<li>One-way invocation using the <code>invokeOneWay</code> | |
methods</li> | |
</ul><br /> | |
Refer to Chapter 4, section 3 of the JAX-WS 2.0 specification | |
for more information on using a Dispatch client. | |
<h4>Dynamic Proxy client</h4>The static client programming | |
model for JAX-WS is the called the Dynamic Proxy client. The | |
Dynamic Proxy client invokes a Web service based on a Service | |
Endpoint Interface (SEI) which must be provided. The Dynamic | |
Proxy client is similar to the stub client in the Java API | |
for XML-based RPC (JAX-RPC) programming model. Although the | |
JAX-WS Dynamic Proxy client and the JAX-RPC stub client are | |
both based on the Service Endpoint Interface (SEI) that is | |
generated from a WSDL file , there is a major difference. The | |
Dynamic Proxy client is dynamically generated at run time | |
using the Java 5 Dynamic Proxy functionality, while the | |
JAX-RPC-based stub client is a non-portable Java file that is | |
generated by tooling. Unlike the JAX-RPC stub clients, the | |
Dynamic Proxy client does not require you to regenerate a | |
stub prior to running the client on an application server for | |
a different vendor because the generated interface does not | |
require the specific vendor information.<br /> | |
<br /> | |
The Dynamic Proxy instances extend the | |
<code>java.lang.reflect.Proxy</code> class and leverage the | |
Dynamic Proxy function in the base Java Runtime Environment | |
Version 5. The client application can then provide an | |
interface that is used to create the proxy instance while the | |
runtime is responsible for dynamically creating a Java object | |
that represents the SEI.<br /> | |
<br /> | |
The Dynamic Proxy client is invoked in one of three | |
ways:<br /> | |
<ul> | |
<li>Synchronous invocation for requests and responses using | |
the <code>invoke</code> method</li> | |
<li>Asynchronous invocation for requests and responses | |
using the <code>invokeAsync</code> method with a callback | |
or polling object</li> | |
<li>One-way invocation using the <code>invokeOneWay</code> | |
methods</li> | |
</ul><br /> | |
Refer to Chapter 4 of the JAX-WS 2.0 specification for more | |
information on using Dynamic Proxy clients. | |
<h3><a name="ProxyClient" id="ProxyClient">Developing a | |
JAX-WS client from a WSDL document</a></h3>Java API for | |
XML-Based Web Services (JAX-WS) tooling supports generating | |
Java artifacts you need to develop static JAX-WS Web services | |
clients when starting with a Web Services Description | |
Language (WSDL) file.<br /> | |
<br /> | |
The static client programming model for JAX-WS is the called | |
the dynamic proxy client. The dynamic proxy client invokes a | |
Web service based on a service endpoint interface that is | |
provided. After you create the proxy, the client application | |
can invoke methods on the proxy just like a standard | |
implementation of those interfaces. For JAX-WS Web service | |
clients using the dynamic proxy programming model, use the | |
JAX-WS tool, <b>wsimport</b>, to process a WSDL file and | |
generate portable Java artifacts that are used to create a | |
Web service client.<br /> | |
<br /> | |
Create the following portable Java artifacts using the | |
wsimport tool: | |
<ul> | |
<li>Service endpoint interface (SEI)</li> | |
<li>Service class</li> | |
<li>Exception class that is mapped from the wsdl:fault | |
class (if any)</li> | |
<li>Java Architecture for XML Binding (JAXB) generated type | |
values which are Java classes mapped from XML schema | |
types</li> | |
</ul><br /> | |
The steps to creating a dynamic proxy client are: | |
<ol> | |
<li>(Optional) If you are using WSDL or schema | |
customizations, use the <b>-b</b> option with the | |
<b>wsimport</b> command to specify an external binding | |
files that contain your customizations.<br /> | |
<br /> | |
For example: <b>wsimport -b <i>binding.xml | |
wsdlfile.wsdl</i></b>.<br /> | |
<br /> | |
You can customize the bindings in your WSDL file to enable | |
asynchronous mappings or attachments. To generate | |
asynchronous interfaces, add the client-side only | |
customization <code>enableAsyncMapping</code> binding | |
declaration to the <code>wsdl:definitions</code> element or | |
in an external binding file that is defined in the WSDL | |
file. Use the <code>enableMIMEContent</code> binding | |
declaration in your custom client or server binding file to | |
enable or disable the default <code>mime:content</code> | |
mapping rules. For additional information on custom binding | |
declarations, see chapter 8 the JAX-WS specification.</li> | |
<li style="list-style: none"><br /></li> | |
<li>Run the <b>wsimport -keep <i>wsdl_UR</i>L</b> command | |
to generate the portable client artifacts. Use the | |
<b>-verbose</b> option to see a list of generated files | |
when you run the command.<br /> | |
<br /> | |
Best practice: When you run the <b>wsimport</b> tool, the | |
location of your WSDL file must either be omitted or point | |
to a valid WSDL document. A best practice for ensuring that | |
you produce a JAX-WS Web services client that is portable | |
to other systems is to package the WSDL document within the | |
application module such as a Web services client Java | |
archive (JAR) file or a Web archive (WAR) file. You can | |
specify a relative URI for the location of your WSDL file | |
by using the<code>-wsdllocation</code> annotation | |
attribute. For example, if your MyService.wsdl file is | |
located in the META-INF/wsdl/ directory, then run the | |
wsimport tool and use the <code>-wsdllocation</code> option | |
to specify the value to be used for the location of the | |
WSDL file.<br /> | |
<br /> | |
<code>wsimport -keep | |
-wsdllocation=META-INF/wsdl/MyService.wsdl</code></li> | |
</ol> | |
<h3><a name="DispatchClient" id="DispatchClient">Developing a | |
dynamic client using JAX-WS APIs</a></h3>JAX-WS provides a | |
new dynamic Dispatch client API that is more generic and | |
offers more flexibility than the existing Java API for | |
XML-based RPC (JAX-RPC)-based Dynamic Invocation Interface | |
(DII). The Dispatch client interface, | |
<code>javax.xml.ws.Dispatch</code>, is an XML messaging | |
oriented client that is intended for advanced XML developers | |
who prefer to work at the XML level using XML constructs. To | |
write a Dispatch client, you must have expertise with the | |
Dispatch client APIs, the supported object types, and | |
knowledge of the message representations for the associated | |
WSDL file.<br /> | |
<br /> | |
The Dispatch API can send data in either <code>PAYLOAD</code> | |
or <code>MESSAGE</code> mode. When using the | |
<code>PAYLOAD</code> mode, the Dispatch client is only | |
responsible for providing the contents of the | |
<code><soap:Body></code> and JAX-WS includes the input | |
payload in a <code><soap:Envelope></code> element. When | |
using the <code>MESSAGE</code> mode, the Dispatch client is | |
responsible for providing the entire SOAP envelope.<br /> | |
<br /> | |
The Dispatch client API requires application clients to | |
construct messages or payloads as XML and requires a detailed | |
knowledge of the message or message payload. The Dispatch | |
client can use HTTP bindings when using <code>Source</code> | |
objects, Java Architecture for XML Binding (JAXB) objects, or | |
data source objects. The Dispatch client supports the | |
following types of objects:<br /> | |
<br /> | |
<ul> | |
<li><code>javax.xml.transform.Source</code>: Use | |
<code>Source</code> objects to enable clients to use XML | |
APIs directly. You can use <code>Source</code> objects with | |
SOAP and HTTP bindings.</li> | |
<li>JAXB objects: Use JAXB objects so that clients can use | |
JAXB objects that are generated from an XML schema to | |
create and manipulate XML with JAX-WS applications. JAXB | |
objects can only be used with SOAP and HTTP bindings.</li> | |
<li><code>javax.xml.soap.SOAPMessage</code>: Use | |
<code>SOAPMessage</code> objects so that clients can work | |
with SOAP messages. You can only use | |
<code>SOAPMessage</code> objects with SOAP version 1.1 or | |
SOAP version 1.2 bindings.</li> | |
<li><code>javax.activation.DataSource</code>: Use | |
<code>DataSource</code> objects so that clients can work | |
with Multipurpose Internet Mail Extension (MIME) messages. | |
Use <code>DataSource</code> only with HTTP bindings.</li> | |
</ul><br /> | |
The Dispatch API uses the concept of generics that are | |
introduced in Java Runtime Environment Version 5. For each of | |
the invoke() methods on the Dispatch interface, generics are | |
used to determine the return type.<br /> | |
<br /> | |
The steps to creating a dynamic client are: | |
<ol> | |
<li>Determine if you want your dynamic client to send data | |
in <code>PAYLOAD</code> or <code>MESSAGE</code> mode.</li> | |
<li>Create a service instance and add at least one port to | |
it. The port carries the protocol binding and service | |
endpoint address information.</li> | |
<li>Create a <code>Dispatch<T></code> object using | |
either the <code>Service.Mode.PAYLOAD</code> method or the | |
<code>Service.Mode.MESSAGE</code> method.</li> | |
<li>Configure the request context properties on the | |
<code>javax.xml.ws.BindingProvider</code> interface. Use | |
the request context to specify additional properties such | |
as enabling HTTP authentication or specifying the endpoint | |
address.</li> | |
<li>Compose the client request message for the dynamic | |
client.</li> | |
<li>Invoke the service endpoint with the Dispatch client | |
either synchronously or asynchronously.</li> | |
<li>Process the response message from the service.</li> | |
</ol><br /> | |
The following example illustrates the steps to create a | |
Dispatch client and invoke a sample EchoService service | |
endpoint. | |
<pre> | |
String endpointUrl = ...; | |
QName serviceName = new QName("http://org/apache/ws/axis2/sample/echo/", | |
"EchoService"); | |
QName portName = new QName("http://org/apache/ws/axis2/sample/echo/", | |
"EchoServicePort"); | |
/** Create a service and add at least one port to it. **/ | |
Service service = Service.create(serviceName); | |
service.addPort(portName, SOAPBinding.SOAP11HTTP_BINDING, endpointUrl); | |
/** Create a Dispatch instance from a service.**/ | |
Dispatch<SOAPMessage> dispatch = service.createDispatch(portName, | |
SOAPMessage.class, Service.Mode.MESSAGE); | |
/** Create SOAPMessage request. **/ | |
// compose a request message | |
MessageFactory mf = MessageFactory.newInstance(SOAPConstants.SOAP_1_1_PROTOCOL); | |
// Create a message. This example works with the SOAPPART. | |
SOAPMessage request = mf.createMessage(); | |
SOAPPart part = request.getSOAPPart(); | |
// Obtain the SOAPEnvelope and header and body elements. | |
SOAPEnvelope env = part.getEnvelope(); | |
SOAPHeader header = env.getHeader(); | |
SOAPBody body = env.getBody(); | |
// Construct the message payload. | |
SOAPElement operation = body.addChildElement("invoke", "ns1", | |
"http://org/apache/ws/axis2/sample/echo/"); | |
SOAPElement value = operation.addChildElement("arg0"); | |
value.addTextNode("ping"); | |
request.saveChanges(); | |
/** Invoke the service endpoint. **/ | |
SOAPMessage response = dispatch.invoke(request); | |
/** Process the response. **/ | |
</pre> | |
<h2><a name="RunClient" id="RunClient">Running a JAX-WS | |
client</a></h2>A JAX-WS client may be started from the | |
command line like any other Axis2-based client, including | |
through the use of the <code>axis2</code> shell scripts in | |
the <code>bin</code> directory of the installed runtime. | |
<h2><a name="Async" id="Async">Invoking JAX-WS Web services | |
asynchronously</a></h2>Java API for XML-Based Web Services | |
(JAX-WS) provides support for invoking Web services using an | |
asynchronous client invocation. JAX-WS provides support for | |
both a callback and polling model when calling Web services | |
asynchronously. Both the callback model and the polling model | |
are available on the Dispatch client and the Dynamic Proxy | |
client.<br /> | |
<br /> | |
An asynchronous invocation of a Web service sends a request | |
to the service endpoint and then immediately returns control | |
to the client program without waiting for the response to | |
return from the service. JAX-WS asynchronous Web service | |
clients consume Web services using either the callback | |
approach or the polling approach. Using a polling model, a | |
client can issue a request and receive a response object that | |
is polled to determine if the server has responded. When the | |
server responds, the actual response is retrieved. Using the | |
callback model, the client provides a callback handler to | |
accept and process the inbound response object. The | |
<code>handleResponse()</code> method of the handler is called | |
when the result is available. Both the polling and callback | |
models enable the client to focus on continuing to process | |
work without waiting for a response to return, while | |
providing for a more dynamic and efficient model to invoke | |
Web services. | |
<h3>Using the callback asynchronous invocation model</h3>To | |
implement an asynchronous invocation that uses the callback | |
model, the client provides an <code>AsynchHandler</code> | |
callback handler to accept and process the inbound response | |
object. The client callback handler implements the | |
<code>javax.xml.ws.AsynchHandler</code> interface, which | |
contains the application code that is executed when an | |
asynchronous response is received from the server. The | |
<code>javax.xml.ws.AsynchHandler</code> interface contains | |
the <code>handleResponse(java.xml.ws.Response)</code> method | |
that is called after the run time has received and processed | |
the asynchronous response from the server. The response is | |
delivered to the callback handler in the form of a | |
<code>javax.xml.ws.Response</code> object. The response | |
object returns the response content when the | |
<code>get()</code> method is called. Additionally, if an | |
error was received, then an exception is returned to the | |
client during that call. The response method is then invoked | |
according to the threading model used by the executor method, | |
<code>java.util.concurrent.Executor</code> on the client's | |
<code>java.xml.ws.Service</code> instance that was used to | |
create the Dynamic Proxy or Dispatch client instance. The | |
executor is used to invoke any asynchronous callbacks | |
registered by the application. Use the | |
<code>setExecutor</code> and <code>getExecutor</code> methods | |
to modify and retrieve the executor configured for your | |
service. | |
<h3>Using the polling asynchronous invocation model</h3>Using | |
the polling model, a client can issue a request and receive a | |
response object that can subsequently be polled to determine | |
if the server has responded. When the server responds, the | |
actual response can then be retrieved. The response object | |
returns the response content when the <code>get()</code> | |
method is called. The client receives an object of type | |
<code>javax.xml.ws.Response</code> from the | |
<code>invokeAsync</code> method. That <code>Response</code> | |
object is used to monitor the status of the request to the | |
server, determine when the operation has completed, and to | |
retrieve the response results. | |
<h3>Using an asynchronous message exchange</h3>By default, | |
asynchronous client invocations do not have asynchronous | |
behavior of the message exchange pattern on the wire. The | |
programming model is asynchronous; however, the exchange of | |
request or response messages with the server is not | |
asynchronous. To use an asynchronous message exchange, the | |
org.apache.axis2.jaxws.use.async.mep property must be set on | |
the client request context with a boolean value of true. When | |
this property is enabled, the messages exchanged between the | |
client and server are different from messages exchanged | |
synchronously. With an asynchronous exchange, the request and | |
response messages have WS-Addressing headers added that | |
provide additional routing information for the messages. | |
Another major difference between asynchronous and synchronous | |
message exchange is that the response is delivered to an | |
asynchronous listener that then delivers that response back | |
to the client. For asynchronous exchanges, there is no | |
timeout that is sent to notify the client to stop listening | |
for a response. To force the client to stop waiting for a | |
response, issue a <code>Response.cancel()</code> method on | |
the object returned from a polling invocation or a | |
<code>Future.cancel()</code> method on the object returned | |
from a callback invocation. The cancel response does not | |
affect the server when processing a request.<br /> | |
<br /> | |
The steps necessary to invoke a Web service asynchronously | |
are: | |
<ol> | |
<li>Determine if you want to implement the callback method | |
or the polling method for the client to asynchronously | |
invoke the Web service.</li> | |
<li>(Optional) Configure the client request context. Add | |
the<br /> | |
<br /> | |
<code>org.apache.axis2.jaxws.use.async.mep</code><br /> | |
<br /> | |
property to the request context to enable asynchronous | |
messaging for the Web services client. Using this | |
property requires that the service endpoint supports | |
WS-Addressing which is supported by default for the | |
application server. The following example demonstrates | |
how to set this property: | |
<pre> | |
Map<String, Object> rc = ((BindingProvider) port).getRequestContext(); | |
rc.put("org.apache.axis2.jaxws.use.async.mep", Boolean.TRUE); | |
</pre> | |
</li> | |
<li>To implement the asynchronous callback method, perform | |
the following steps. | |
<ol> | |
<li>Find the asynchronous callback method on the SEI or | |
<code>javax.xml.ws.Dispatch</code> interface. For an | |
SEI, the method name ends in <code>Async</code> and has | |
one more parameter than the synchronous method of type | |
<code>javax.xml.ws.AsyncHandler</code>. The | |
<code>invokeAsync(Object, AsyncHandler)</code> method | |
is the one that is used on the Dispatch interface.</li> | |
<li>(Optional) Add the <code>service.setExecutor</code> | |
methods to the client application. Adding the executor | |
methods gives the client control of the scheduling | |
methods for processing the response. You can also | |
choose to use the <code>java.current.Executors</code> | |
class factory to obtain packaged executors or implement | |
your own executor class. See the JAX-WS specification | |
for more information on using executor class methods | |
with your client.</li> | |
<li>Implement the | |
<code>javax.xml.ws.AsynchHandler</code> interface. The | |
<code>javax.xml.ws.AsynchHandler</code> interface only | |
has the | |
<code>handleResponse(javax.xml.ws.Response)</code> | |
method. The method must contain the logic for | |
processing the response or possibly an exception. The | |
method is called after the client run time has received | |
and processed the asynchronous response from the | |
server.</li> | |
<li>Invoke the asynchronous callback method with the | |
parameter data and the callback handler.</li> | |
<li>The <code>handleResponse(Response)</code> method is | |
invoked on the callback object when the response is | |
available. The <code>Response.get()</code> method is | |
called within this method to deliver the response.</li> | |
</ol> | |
</li> | |
<li>To implement the polling method, | |
<ol> | |
<li>Find the asynchronous polling method on the SEI or | |
<code>javax.xml.ws.Dispatch</code> interface. For an | |
SEI, the method name ends in <code>Async</code> and has | |
a return type of <code>javax.xml.ws.Response</code>. | |
The <code>invokeAsync(Object)</code> method is used on | |
the Dispatch interface.</li> | |
<li>Invoke the asynchronous polling method with the | |
parameter data.</li> | |
<li>The client receives the object type, | |
<code>javax.xml.ws.Response</code>, that is used to | |
monitor the status of the request to the server. The | |
<code>isDone()</code> method indicates whether the | |
invocation has completed. When the | |
<code>isDone()</code> method returns a value of true, | |
call the <code>get()</code> method to retrieve the | |
response object.</li> | |
</ol> | |
</li> | |
<li>Use the <code>cancel()</code> method for the callback | |
or polling method if the client needs to stop waiting for a | |
response from the service. If the <code>cancel()</code> | |
method is invoked by the client, the endpoint continues to | |
process the request. However, the wait and response | |
processing for the client is stopped.</li> | |
</ol><br /> | |
When developing Dynamic Proxy clients, after you generate the | |
portable client artifacts from a WSDL file using the | |
<b>wsimport</b> command, the generated service endpoint | |
interface (SEI) does not have asynchronous methods included | |
in the interface. Use JAX-WS bindings to add the asynchronous | |
callback or polling methods on the interface for the Dynamic | |
Proxy client. To enable asynchronous mappings, you can add | |
the <code>jaxws:enableAsyncMapping</code> binding declaration | |
to the WSDL file. For more information on adding binding | |
customizations to generate an asynchronous interface, see | |
chapter 8 of the JAX-WS specification.<br /> | |
<br /> | |
Note: When you run the <b>wsimport</b> tool and enable | |
asynchronous invocation through the use of the JAX-WS | |
<code>enableAsyncMapping</code> binding declaration, ensure | |
that the corresponding response message your WSDL file does | |
not contain parts. When a response message does not contain | |
parts, the request acts as a two-way request, but the actual | |
response that is sent back is empty. The <b>wsimport</b> tool | |
does not correctly handle a void response. To avoid this | |
scenario, you can remove the output message from the | |
operation which makes your operation a one-way operation or | |
you can add a <wsdl:part> to your message. For more | |
information on the usage, syntax and parameters for the | |
<b>wsimport</b> tool, see the <b>wsimport</b> command for | |
JAX-WS applications documentation.<br /> | |
<br /> | |
The following example illustrates a Web service interface | |
with methods for asynchronous requests from the client. | |
<pre> | |
@WebService | |
public interface CreditRatingService { | |
// Synchronous operation. | |
Score getCreditScore(Customer customer); | |
// Asynchronous operation with polling. | |
<b>Response<Score></b> getCreditScoreAsync(Customer customer); | |
// Asynchronous operation with callback. | |
<b>Future<?></b> getQuoteAsync(Customer customer, | |
<b>AsyncHandler<Score></b> handler); | |
} | |
</pre>Using the callback method The callback method requires a | |
callback handler that is shown in the following example. When using | |
the callback procedure, after a request is made, the callback | |
handler is responsible for handling the response. The response | |
value is a response or possibly an exception. The | |
<code>Future<?></code> method represents the result of an | |
asynchronous computation and is checked to see if the computation | |
is complete. When you want the application to find out if the | |
request is completed, invoke the <code>Future.isDone()</code> | |
method. Note that the <code>Future.get()</code> method does not | |
provide a meaningful response and is not similar to the <code> | |
Response.get()</code> method. | |
<pre> | |
CreditRatingService svc = ...; | |
<b>Future<?></b> invocation = svc.getCreditScoreAsync(customerTom, | |
<b>new AsyncHandler<Score>() { | |
public void handleResponse ( | |
Response<Score> response) | |
{ | |
score = response.get(); | |
// process the request... | |
} | |
}</b> | |
); | |
</pre>Using the polling method The following example illustrates an | |
asynchronous polling client: | |
<pre> | |
CreditRatingService svc = ...; | |
<b>Response<Score> response</b> = svc.getCreditScoreAsync(customerTom); | |
while (<b>!response.isDone()</b>) { | |
// Do something while we wait. | |
} | |
score = <b>response.get()</b>; | |
</pre> | |
<h2><a name="Handlers" id="Handlers">Using handlers in JAX-WS | |
Web services</a></h2>As in the Java API for XML-based RPC | |
(JAX-RPC) programming model, the JAX-WS programming model | |
provides an application handler facility that enables you to | |
manipulate a message on either an inbound or an outbound | |
flow. You can add handlers into the JAX-WS runtime | |
environment to perform additional processing of request and | |
response messages. You can use handlers for a variety of | |
purposes such as capturing and logging information and adding | |
security or other information to a message. Because of the | |
support for additional protocols beyond SOAP, JAX-WS provides | |
two different classifications for handlers. One type of | |
handler is a logical handler that is protocol independent and | |
can obtain the message in the flow as an extensible markup | |
language (XML) message. The logical handlers operate on | |
message context properties and message payload. These | |
handlers must implement the | |
<code>javax.xml.ws.handler.LogicalHandler</code> interface. A | |
logical handler receives a <code>LogicalMessageContext</code> | |
object from which the handler can get the message | |
information. Logical handlers can exist on both SOAP and | |
XML/HTTP-based configurations.<br /> | |
<br /> | |
The second type of handler is a protocol handler. The | |
protocol handlers operate on message context properties and | |
protocol-specific messages. Protocol handlers are limited to | |
SOAP-based configurations and must implement the | |
<code>javax.xml.ws.handler.soap.SOAPHandler</code> interface. | |
Protocol handlers receive the message as a | |
<code>javax.xml.soap.SOAPMessage</code> to read the message | |
data.<br /> | |
<br /> | |
The JAX-WS runtime makes no distinction between server-side | |
and client-side handler classes. The runtime does not | |
distinguish between inbound or outbound flow when a | |
<code>handleMessage(MessageContext)</code> method or | |
<code>handleFault(MessageContext)</code> method for a | |
specific handler is invoked. You must configure the handlers | |
for the server or client, and implement sufficient logic | |
within these methods to detect the inbound or outbound | |
direction of the current message.<br /> | |
<br /> | |
To use handlers with Web services client applications, you | |
must add the <code>@HandlerChain</code> annotation to the | |
service endpoint interface or the generated service class and | |
provide the handler chain configuration file. The | |
<code>@HandlerChain</code> annotation contains a file | |
attribute that points to a handler chain configuration file | |
that you create. For Web services client applications, you | |
can also configure the handler chain programmatically using | |
the Binding API. To modify the <code>handlerchain</code> | |
class programmatically, use either the default implementation | |
or a custom implementation of the | |
<code>HandlerResolver</code> method.<br /> | |
<br /> | |
To use handlers with your server application, you must set | |
the <code>@HandlerChain</code> annotation on either the | |
service endpoint interface or the endpoint implementation | |
class, and provide the associated handler chain configuration | |
file. Handlers for the server are only configured by setting | |
the <code>@HandlerChain</code> annotation on the service | |
endpoint implementation or the implementation class. The | |
handler classes must be included in the deployed | |
artifact.<br /> | |
<br /> | |
For both server and client implementations of handlers using | |
the <code>@HandlerChain</code> annotation, you must specify | |
the location of the handler configuration as either a | |
relative path from the annotated file or as an absolute URL. | |
For example:<br /> | |
<br /> | |
<pre> | |
@HandlerChain(file="../../common/handlers/myhandlers.xml") | |
</pre>or | |
<pre> | |
@HandlerChain(file="http://foo.com/myhandlers.xml") | |
</pre>For more information on the schema of the handler | |
configuration file, see the JSR 181 specification.<br /> | |
<br /> | |
For more information regarding JAX-WS handlers, see chapter 9 | |
of the JAX-WS specification.<br /> | |
<br /> | |
To create a JAX-WS handler: | |
<ol> | |
<li>Determine if you want to implement JAX-WS handlers on | |
the service or the client. | |
<ol> | |
<li>Use the default implementation of a handler | |
resolver. The runtime now uses the | |
<code>@HandlerChain</code> annotation and the default | |
implementation of <code>HandlerResolver</code> class to | |
build the handler chain. You can obtain the existing | |
handler chain from the <code>Binding</code>, add or | |
remove handlers, and then return the modified handler | |
chain to the <code>Binding</code> object.</li> | |
<li>To use a custom implementation of a handler | |
resolver, set the custom <code>HandlerResolver</code> | |
class on the <code>Service</code> instance. The runtime | |
uses your custom implementation of the | |
<code>HandlerResolver</code> class to build the handler | |
chain, and the default runtime implementation is not | |
used. In this scenario, the <code>@HandlerChain</code> | |
annotation is not read when retrieving the handler | |
chain from the binding after the custom | |
<code>HandlerResolver</code> instance is registered on | |
the <code>Service</code> instance. You can obtain the | |
existing handler chain from the <code>Binding</code>, | |
add or remove handlers, and then return the modified | |
handler chain to the <code>Binding</code> object.</li> | |
</ol> | |
</li> | |
<li>Configure the client handlers by setting the | |
<code>@HandlerChain</code> annotation on the service | |
instance or service endpoint interface, or you can modify | |
the handler chain programmatically to control how the | |
handler chain is built in the runtime. If you choose to | |
modify the handler chain programmatically, then you must | |
determine if you will use the default handler resolver or | |
use a custom implementation of a handler resolver that is | |
registered on the service instance. A service instance uses | |
a handler resolver when creating binding providers. When | |
the binding providers are created, the handler resolver | |
that is registered with a service is used to create a | |
handler chain and the handler chain is subsequently used to | |
configure the binding provider.</li> | |
<li>Configure the server handlers by setting the | |
<code>@HandlerChain</code> annotation on the service | |
endpoint interface or implementation class. When the | |
<code>@HandlerChain</code> annotation is configured on both | |
the service endpoint interface and the implementation | |
class, the implementation class takes priority.</li> | |
<li>Create the handler chain configuration XML file. You | |
must create a handler chain configuration XML file for the | |
<code>@HandlerChain</code> to reference.</li> | |
<li>Add the handler chain configuration XML file in the | |
class path for the service endpoint interface when | |
configuring the server or client handlers using the | |
<code>@HandlerChain</code> annotation. You must also | |
include the handler classes contained in the configuration | |
XML file in your class path.</li> | |
<li>Write your handler implementation.</li> | |
</ol><br /> | |
The following example illustrates the steps necessary to | |
configure JAX-WS handlers on a service endpoint interface | |
using the <code>@HandlerChain</code> annotation.<br /> | |
<br /> | |
The <code>@HandlerChain</code> annotation has a file | |
attribute that points to a handler chain configuration XML | |
file that you create. The following file illustrates a | |
typical handler configuration file. The | |
<code>protocol-bindings</code>, | |
<code>port-name-pattern</code>, and | |
<code>service-name-pattern</code> elements are all filters | |
that are used to restrict which services can apply the | |
handlers. | |
<pre> | |
<?xml version="1.0" encoding="UTF-8"?> | |
<jws:handler-chains xmlns:jws="http://java.sun.com/xml/ns/javaee"> | |
<!-- Note: The '*" denotes a wildcard. --> | |
<jws:handler-chain name="MyHandlerChain"> | |
<jws:protocol-bindings>##SOAP11_HTTP ##ANOTHER_BINDING</jws:protocol-bindings> | |
<jws:port-name-pattern | |
xmlns:ns1="http://handlersample.samples.apache.org/">ns1:MySampl*</jws:port-name-pattern> | |
<jws:service-name-pattern | |
xmlns:ns1="http://handlersample.samples.apache.org/">ns1:*</jws:service-name-pattern> | |
<jws:handler> | |
<jws:handler-class>org.apache.samples.handlersample.SampleLogicalHandler</jws:handler-class> | |
</jws:handler> | |
<jws:handler> | |
<jws:handler-class>org.apache.samples.handlersample.SampleProtocolHandler2</jws:handler-class> | |
</jws:handler> | |
<jws:handler> | |
<jws:handler-class>org.apache.samples.handlersample.SampleLogicalHandler</jws:handler-class> | |
</jws:handler> | |
<jws:handler> | |
<jws:handler-class>org.apache.samples.handlersample.SampleProtocolHandler2</jws:handler-class> | |
</jws:handler> | |
</jws:handler-chain> | |
</jws:handler-chains> | |
</pre>Make sure that you add the handler.xml file and the handler | |
classes contained in the handler.xml file in your class path.<br /> | |
<br /> | |
The following example demonstrates a handler implementation: | |
<pre> | |
package org.apache.samples.handlersample; | |
import java.util.Set; | |
import javax.xml.namespace.QName; | |
import javax.xml.ws.handler.MessageContext; | |
import javax.xml.ws.handler.soap.SOAPMessageContext; | |
public class SampleProtocolHandler implements | |
javax.xml.ws.handler.soap.SOAPHandler<SOAPMessageContext> { | |
public void close(MessageContext messagecontext) { | |
} | |
public Set<QName> getHeaders() { | |
return null; | |
} | |
public boolean handleFault(SOAPMessageContext messagecontext) { | |
return true; | |
} | |
public boolean handleMessage(SOAPMessageContext messagecontext) { | |
Boolean outbound = (Boolean) messagecontext.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY); | |
if (outbound) { | |
// Include your steps for the outbound flow. | |
} | |
return true; | |
} | |
} | |
</pre> | |
<h2><a name="HTTPSession" id="HTTPSession">Enabling HTTP | |
session management support for JAX-WS | |
applications</a></h2>You can use HTTP session management to | |
maintain user state information on the server, while passing | |
minimal information back to the user to track the session. | |
You can implement HTTP session management on the application | |
server using either session cookies or URL rewriting.<br /> | |
<br /> | |
The interaction between the browser, application server, and | |
application is transparent to the user and the application | |
program. The application and the user are typically not aware | |
of the session identifier provided by the server. | |
<h3>Session cookies</h3>The HTTP maintain session feature | |
uses a single cookie, <code>JSESSIONID</code>, and this | |
cookie contains the session identifier. This cookie is used | |
to associate the request with information stored on the | |
server for that session. On subsequent requests from the | |
JAX-WS application, the session ID is transmitted as part of | |
the request header, which enables the application to | |
associate each request for a given session ID with prior | |
requests from that user. The JAX-WS client applications | |
retrieve the session ID from the HTTP response headers and | |
then use those IDs in subsequent requests by setting the | |
session ID in the HTTP request headers. | |
<h3>URL rewriting</h3>URL rewriting works like a redirected | |
URL as it stores the session identifier in the URL. The | |
session identifier is encoded as a parameter on any link or | |
form that is submitted from a Web page. This encoded URL is | |
used for subsequent requests to the same server.<br /> | |
<br /> | |
To enable HTTP session management: | |
<ol> | |
<li>Configure the server to enable session tracking.</li> | |
<li>Enable session management on the client by setting the | |
JAX-WS property, | |
<code>javax.xml.ws.session.maintain</code>, to true on the | |
<code>BindingProvider</code>. | |
<pre> | |
Map<String, Object> rc = ((BindingProvider) port).getRequestContext(); | |
... | |
... | |
rc.put(BindingProvider.SESSION_MAINTAIN_PROPERTY, Boolean.TRUE); | |
... | |
... | |
</pre> | |
</li> | |
</ol> | |
<h2><a name="MTOM" id="MTOM">Enabling MTOM</a></h2>JAX-WS | |
supports the use of SOAP Message Transmission Optimized | |
Mechanism (MTOM) for sending binary attachment data. By | |
enabling MTOM, you can send and receive binary data optimally | |
without incurring the cost of data encoding to ensure the | |
data is included in the XML document.<br /> | |
<br /> | |
JAX-WS applications can send binary data as base64 or | |
hexBinary encoded data contained within the XML document. | |
However, to take advantage of the optimizations provided by | |
MTOM, enable MTOM to send binary base64 data as attachments | |
contained outside the XML document. MTOM optimization is only | |
available for the xs:base64Binary data type. The MTOM option | |
is not enabled by default. JAX-WS applications require | |
separate configuration of both the client and the server | |
artifacts to enable MTOM support. For the server, MTOM can be | |
enabled on a JAX-WS JavaBeans endpoint only and not on a | |
provider-based endpoint.<br /> | |
<br /> | |
To enable MTOM on an endpoint, use the @BindingType | |
(javax.xml.ws.BindingType) annotation on a server endpoint | |
implementation class to specify that the endpoint supports | |
one of the MTOM binding types so that the response messages | |
are MTOM-enabled. The javax.xml.ws.SOAPBinding class defines | |
two different constants, SOAP11HTTP_MTOM_BINDING and | |
SOAP12HTTP_MTOM_BINDING that you can use for the value of the | |
@BindingType annotation. For example: | |
<pre> | |
// for SOAP version 1.1 | |
@BindingType(value = SOAPBinding.SOAP11HTTP_MTOM_BINDING) | |
// for SOAP version 1.2 | |
@BindingType(value = SOAPBinding.SOAP12HTTP_MTOM_BINDING) | |
</pre><br /> | |
Enable MTOM on the client by using the | |
javax.xml.ws.soap.SOAPBinding client-side API. Enabling MTOM | |
on the client optimizes the binary messages that are sent to | |
the server. | |
<ul> | |
<li>Enable MTOM on a Dispatch client.</li> | |
<li style="list-style: none">The following example uses | |
SOAP version 1.1: | |
<ul> | |
<li>First method: Using | |
SOAPBinding.setMTOMEnabled()</li> | |
<li style="list-style: none; display: inline"> | |
<pre> | |
SOAPBinding binding = (SOAPBinding)dispatch.getBinding(); | |
binding.setMTOMEnabled(true); | |
</pre> | |
</li> | |
<li>Second method: Using Service.addPort()</li> | |
<li style="list-style: none; display: inline"> | |
<pre> | |
Service svc = Service.create(serviceName); | |
svc.addPort(portName,SOAPBinding.SOAP11HTTP_MTOM_BINDING,endpointUrl); | |
</pre> | |
</li> | |
</ul> | |
</li> | |
<li>Enable MTOM on a Dynamic Proxy client.</li> | |
<li style="list-style: none; display: inline"> | |
<pre> | |
// Create a BindingProvider bp from a proxy port. | |
Service svc = Service.create(serviceName); | |
MtomSample proxy = svc.getPort(portName, MtomSample.class); | |
BindingProvider bp = (BindingProvider) proxy; | |
//Enable MTOM | |
SOAPBinding binding = (SOAPBinding) bp.getBinding(); | |
binding.setMTOMEnabled(true); | |
</pre> | |
</li> | |
</ul> | |
</li> | |
</ul> | |
</body> | |
</html> |