+ JAX-WS Guide

JAX-WS Guide

Introduction to JAX-WS +
Introduction to JAXB +
Developing JAX-WS Web services +
1. From a JavaBean + (bottom-up) +
2. From a WSDL document + (top-down) +
+
Packaging and deploying a JAX-WS + service +
1. Developing a JAX-WS client from + a WSDL document +
2. Developing a dynamic client + using JAX-WS APIs +
+
Developing JAX-WS clients +
Running a JAX-WS client +
Invoking JAX-WS Web services + asynchronously +
Using handlers in JAX-WS Web + services +
Enabling HTTP session management + support for JAX-WS applications +
Enabling MTOM +

Introduction to + JAX-WS +

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: + +

Better platform independence for Java applications.
+ + 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.
+
+
Annotations
+ + 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.
+
+ + For example, you can embed a simple @WebService tag in the + Java source to expose the bean as a Web service. +
```
+      @WebService 
+
+      public class QuoteBean implements StockQuote {
+
+             public float getQuote(String sym) { ... }
+
+      }
+
```
The @WebService 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.
+ + 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.
+
+
Invoking Web services asynchronously
+ + 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.
+
+ + For example, a Web service interface might have methods for + both synchronous and asynchronous requests. Asynchronous + requests are identified in bold below: +
```
+      @WebService
+      public interface CreditRatingService {
+            // sync operation
+            Score      getCreditScore(Customer customer);
+            // async operation with polling
+            Response<Score>
+ getCreditScoreAsync(Customer customer);
+            // async operation with callback
+            Future<?>
+ getCreditScoreAsync(Customer customer, 
+               AsyncHandler<Score>
+ handler);
+      }
+
```
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: +
```
+      CreditRatingService svc = ...;
+
+      Future<?>
+ invocation = svc.getCreditScoreAsync(customerFred,
+        new AsyncHandler<Score>() {
+           public void handleResponse (
+               Response<Score> response)
+             {
+               Score score = response.get();
+               // do work here...
+             }
+         }
+
+      );
+
```
The following is a code example for an asynchronous polling +client: +
```
+      CreditRatingService svc = ...;
+      Response<Score> response
+ = svc.getCreditScoreAsync(customerFred);
+
+      while (!response.isDone()
+) {
+                // do something while we wait
+      }
+
+      // no cast needed, thanks to generics
+      Score score = response.get()
+;
+
```
+
+
Using resource injection
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.
+ + Axis2 supports the JAX-WS usage of the @Resource + annotation for resource injection. The @Resource + 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 @Resource + annotation on a service endpoint implementation, you can + request a resource injection and collect the + javax.xml.ws.WebServiceContext interface related + to that particular endpoint invocation. When the endpoint + sees the @Resource annotation, the endpoint adds + the annotated variable with an appropriate value before the + servlet is placed into service. From the + WebServiceContext interface, you can collect the + MessageContext for the request associated with + the particular method call using the + getMessageContext() method.
+
+ + The following example illustrates using the + @Resource annotation for resource injection: +
```
@WebService
+public class MyService {
+    
+    @Resource
+    private WebServiceContext ctx;
+
+    public String echo (String input) {
+        ?
+    }
+     
+}
+
```
Refer to sections 5.2.1 and 5.3 of the JAX-WS 2.0 +specification for more information on resource injection.
+
+
Data binding with Java Architecture for XML Binding (JAXB) + 2.0
+ + 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.
+
+
Dynamic and static clients
+ + The dynamic client API for JAX-WS is called the dispatch client + (javax.xml.ws.Dispatch). The dispatch client is an + XML messaging oriented client. The data is sent in either + PAYLOAD or MESSAGE mode. When using + the PAYLOAD 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 + MESSAGE 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.
+ + 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.
+
+
Support for Message Transmission Optimized Mechanism + (MTOM)
+ + 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).
+
+
Multiple data binding technologies
+ + 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 + SOAPMessage object across the interface. JAX-WS + leverages the JAXB 2.0 support as the data binding technology + of choice between Java and XML.
+
+
Support for SOAP 1.2
+ + 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.
+
+
New development tools
+ + JAX-WS provides the wsgen + and wsimport + + 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. + +
Introduction to + JAXB +
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.
+
+ + Axis2 provides JAXB 2.0 standards.
+
+ + 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.
+
+ + JAXB provides the xjc + schema compiler tool, the + schemagen + schema generator tool, and a runtime + framework. You can use the xjc + 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 schemagen + 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.
+
+ + 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.
+
+ + 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.
+
+ + 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.
+
+ + The following diagram illustrates the JAXB + architecture.
+
Developing + JAX-WS Web services +
Developing + a JAX-WS Web service from a JavaBean (bottom-up + development) +
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 @WebService + 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.
+
+
1. Develop a service endpoint interface.
2. + + 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 + Provider 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.
  +
  + + 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.
  +
  + + 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.
  +
  + + To develop a JAX-WS Web service, you must annotate your + Java class with the javax.jws.WebService + annotation for JavaBeans endpoints or the + javax.jws.WebServiceProvider 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.
  +
  + + All JavaBeans endpoints are required to have the + @WebService (javax.jws.WebService) + 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.
  +
  + + The JAX-WS programming model introduces the new Provider + API, javax.xml.ws.Provider, as an + alternative to service endpoint interfaces. The + Provider interface supports a more messaging + oriented approach to Web services. With the + Provider interface, you can create a Java + class that implements a simple interface to produce a + generic service implementation class. The + Provider 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 @WebServiceProvider + (javax.xml.ws.WebServiceProvider) annotation. A + service implementation cannot specify the + @WebService annotation if it implements the + javax.xml.ws.Provider interface.
  +
  + + So the steps involved are: + +
  1. Identify your service endpoint requirements for + your Web services application.
  2. + + 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.
    + + A Java class that implements a Web service must + specify either the javax.jws.WebService + or javax.xml.ws.WebServiceProvider + annotation. Both annotations must not be present on a + Java class. The + javax.xml.ws.WebServiceProvider + annotation is only supported on classes that + implement the javax.xml.ws.Provider + interface. + +
    - 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 + javax.jws.WebService annotation. You + can add the @WebMethod 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 @WebMethod + annotation is specified or not. It is incorrect to + have an @WebMethod annotation on an + service endpoint interface that contains the + exclude attribute.
    - If you have an implicit service endpoint + interface with the Java class, then the + javax.jws.WebService annotation will + use the default values for the + serviceName, portName, + and targetNamespace parameters. To + override these default values, specify values for + these parameters in the @WebService + annotation. If the @WebMethod + annotation is not specified, all public methods are + exposed including the inherited methods with the + exception of methods inherited from + java.lang.Object. The + exclude parameter of the + @WebMethod annotation can be used to + control which methods are exposed.
    - If you are using the Provider + interface, use the + javax.xml.ws.WebServiceProvider + annotation on the Provider endpoint.
    +
  3. Annotate the service endpoints.
  4. Implement your service.
  +
  +
  + + 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: + +
  - 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 + @ResponseWrapper annotation for a wrapped + method.
  - a WSDL file if the optional -wsdl + 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.
  +
  + + 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 LITERAL are supported while the + value, ENCODED, 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.
  +
  + + To ensure the wsgen command does not miss inherited + methods on a service endpoint implementation bean, you + must either add the @WebService 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 @WebService annotation.
  +
  + + Note: The wsgen + command does not differentiate the + XML namespace between multiple XMLType + annotations that have the same @XMLType name + defined within different Java packages. When this + scenario occurs, the following error is produced: +
```
+   Error: Two classes have the same XML type name ....
+   Use @XmlType.name and @XmlType.namespace to assign different names to them...
+
```
  This error indicates you have class names or +@XMLType.name values that have the same name, but +exist within different Java packages. To prevent this error, add +the @XML.Type.namespace class to the existing + @XMLType annotation to differentiate between the + XML types. +
3. Develop the Java artifacts.
4. Package and deploy your service.
+
Developing a + JAX-WS Web service from a WSDL document (top-down + development) +
You can use a top-down development + approach to create a JAX-WS Web service with an existing WSDL + file using JavaBeans.
+
+ + You can use the JAX-WS tool, wsimport +, 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 wsimport + tool are: + +
- Service endpoint interface (SEI)
- Service class
- Exception class that is mapped from the + wsdl:fault class (if any)
- Java Architecture for XML Binding (JAXB) generated type + values which are Java classes mapped from XML schema + types
+
+ + Run the +
```
+wsimport -keep -verbose wsdl_URL
+
```
command to generate the portable artifacts. The +-keep option tells the tool not to delete the +generated files, and the -verbose 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 targetNamespace value +and creates the directory structure.
+
+ + You must now provide an implementation for the SEI created by + the tool. + +
Packaging and + deploying a JAX-WS service +
Axis2 provides two + mechanisms for deploying JAX-WS services: + +
1. 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.
2. The service may be packaged in a jar file and placed + into the servicejars directory. The + JAXWSDeployer will examine all jars within + that directory and deploy those classes that have JAX-WS + annotations which identify them as Web services.
+
Developing + JAX-WS clients +
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.
+
+
- 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.
- Dynamic Proxy client: Use this client when you want to + invoke a Web service based on a service endpoint + interface.
+
Dispatch client
+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, javax.xml.ws.Dispatch, 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 MESSAGE + or PAYLOAD mode. When using the + javax.xml.ws.Service.Mode.MESSAGE mode, the + Dispatch client is responsible for providing the entire SOAP + envelope including the <soap:Envelope>, + <soap:Header>, and + <soap:Body> elements. When using the + javax.xml.ws.Service.Mode.PAYLOAD mode, the + Dispatch client is only responsible for providing the + contents of the <soap:Body> and JAX-WS + includes the payload in a <soap:Envelope> + element.
+
+ + 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: + +
- javax.xml.transform.Source: Use + Source objects to enable clients to use XML + APIs directly. You can use Source objects with + SOAP or HTTP bindings.
- 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.
- javax.xml.soap.SOAPMessage: Use + SOAPMessage objects so that clients can work + with SOAP messages. You can only use + SOAPMessage objects with SOAP bindings.
- javax.activation.DataSource: Use + DataSource objects so that clients can work + with Multipurpose Internet Mail Extension (MIME) messages. + Use DataSource only with HTTP bindings.
+
+ + 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: +
```
Dispatch<Source> dispatch = ? create a Dispatch<Source>
+Source request = ? create a Source object
+Source response = dispatch.invoke(request);
```
The Dispatch parameter value determines the return type of +the invoke() method.
+
+ + The Dispatch client is invoked in one of three ways:
+
- Synchronous invocation for requests and responses using + the invoke method
- Asynchronous invocation for requests and responses + using the invokeAsync method with a callback + or polling object
- One-way invocation using the invokeOneWay + methods
+
+ + Refer to Chapter 4, section 3 of the JAX-WS 2.0 specification + for more information on using a Dispatch client. + +
Dynamic Proxy client
+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.
+
+ + The Dynamic Proxy instances extend the + java.lang.reflect.Proxy 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.
+
+ + The Dynamic Proxy client is invoked in one of three + ways:
+
- Synchronous invocation for requests and responses using + the invoke method
- Asynchronous invocation for requests and responses + using the invokeAsync method with a callback + or polling object
- One-way invocation using the invokeOneWay + methods
+
+ + Refer to Chapter 4 of the JAX-WS 2.0 specification for more + information on using Dynamic Proxy clients. + +
Developing a + JAX-WS client from a WSDL document +
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.
+
+ + 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, wsimport +, to process a WSDL file and + generate portable Java artifacts that are used to create a + Web service client.
+
+ + Create the following portable Java artifacts using the + wsimport tool: + +
- Service endpoint interface (SEI)
- Service class
- Exception class that is mapped from the wsdl:fault + class (if any)
- Java Architecture for XML Binding (JAXB) generated type + values which are Java classes mapped from XML schema + types
+
+ + The steps to creating a dynamic proxy client are: + +
1. (Optional) If you are using WSDL or schema + customizations, use the -b + option with the + wsimport + command to specify an external binding + files that contain your customizations.
  +
  + + For example: wsimport -b binding.xml + wsdlfile.wsdl + +.
  +
  + + 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 enableAsyncMapping binding + declaration to the wsdl:definitions element or + in an external binding file that is defined in the WSDL + file. Use the enableMIMEContent binding + declaration in your custom client or server binding file to + enable or disable the default mime:content + mapping rules. For additional information on custom binding + declarations, see chapter 8 the JAX-WS specification.
2. +
3. Run the wsimport -keep wsdl_UR +L + command + to generate the portable client artifacts. Use the + -verbose + option to see a list of generated files + when you run the command.
  +
  + + Best practice: When you run the wsimport + 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-wsdllocation 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 -wsdllocation option + to specify the value to be used for the location of the + WSDL file.
  +
  +wsimport -keep + -wsdllocation=META-INF/wsdl/MyService.wsdl
+
Developing a + dynamic client using JAX-WS APIs +
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, + javax.xml.ws.Dispatch, 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.
+
+ + The Dispatch API can send data in either PAYLOAD + or MESSAGE mode. When using the + PAYLOAD mode, the Dispatch client is only + responsible for providing the contents of the + <soap:Body> and JAX-WS includes the input + payload in a <soap:Envelope> element. When + using the MESSAGE mode, the Dispatch client is + responsible for providing the entire SOAP envelope.
+
+ + 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 Source + objects, Java Architecture for XML Binding (JAXB) objects, or + data source objects. The Dispatch client supports the + following types of objects:
+
+
- javax.xml.transform.Source: Use + Source objects to enable clients to use XML + APIs directly. You can use Source objects with + SOAP and HTTP bindings.
- 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.
- javax.xml.soap.SOAPMessage: Use + SOAPMessage objects so that clients can work + with SOAP messages. You can only use + SOAPMessage objects with SOAP version 1.1 or + SOAP version 1.2 bindings.
- javax.activation.DataSource: Use + DataSource objects so that clients can work + with Multipurpose Internet Mail Extension (MIME) messages. + Use DataSource only with HTTP bindings.
+
+ + 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.
+
+ + The steps to creating a dynamic client are: + +
1. Determine if you want your dynamic client to send data + in PAYLOAD or MESSAGE mode.
2. Create a service instance and add at least one port to + it. The port carries the protocol binding and service + endpoint address information.
3. Create a Dispatch<T> object using + either the Service.Mode.PAYLOAD method or the + Service.Mode.MESSAGE method.
4. Configure the request context properties on the + javax.xml.ws.BindingProvider interface. Use + the request context to specify additional properties such + as enabling HTTP authentication or specifying the endpoint + address.
5. Compose the client request message for the dynamic + client.
6. Invoke the service endpoint with the Dispatch client + either synchronously or asynchronously.
7. Process the response message from the service.
+
+ + The following example illustrates the steps to create a + Dispatch client and invoke a sample EchoService service + endpoint. +
```
+   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. **/
+
```
Running a JAX-WS + client +
A JAX-WS client may be started from the + command line like any other Axis2-based client, including + through the use of the axis2 shell scripts in + the bin directory of the installed runtime. + +
Invoking JAX-WS Web services + asynchronously +
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.
+
+ + 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 + handleResponse() 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. + +
Using the callback asynchronous invocation model
To + implement an asynchronous invocation that uses the callback + model, the client provides an AsynchHandler + callback handler to accept and process the inbound response + object. The client callback handler implements the + javax.xml.ws.AsynchHandler interface, which + contains the application code that is executed when an + asynchronous response is received from the server. The + javax.xml.ws.AsynchHandler interface contains + the handleResponse(java.xml.ws.Response) 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 + javax.xml.ws.Response object. The response + object returns the response content when the + get() 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, + java.util.concurrent.Executor on the client's + java.xml.ws.Service 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 + setExecutor and getExecutor methods + to modify and retrieve the executor configured for your + service. + +
Using the polling asynchronous invocation model
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 get() + method is called. The client receives an object of type + javax.xml.ws.Response from the + invokeAsync method. That Response + 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. + +
Using an asynchronous message exchange
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 Response.cancel() method on + the object returned from a polling invocation or a + Future.cancel() method on the object returned + from a callback invocation. The cancel response does not + affect the server when processing a request.
+
+ + The steps necessary to invoke a Web service asynchronously + are: + +
1. Determine if you want to implement the callback method + or the polling method for the client to asynchronously + invoke the Web service.
2. (Optional) Configure the client request context. Add + the
  +
  +org.apache.axis2.jaxws.use.async.mep
  +
  + + 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: +
```
+           Map<String, Object> rc = ((BindingProvider) port).getRequestContext();
+           rc.put("org.apache.axis2.jaxws.use.async.mep", Boolean.TRUE);
+
```
3. To implement the asynchronous callback method, perform + the following steps. + +
  1. Find the asynchronous callback method on the SEI or + javax.xml.ws.Dispatch interface. For an + SEI, the method name ends in Async and has + one more parameter than the synchronous method of type + javax.xml.ws.AsyncHandler. The + invokeAsync(Object, AsyncHandler) method + is the one that is used on the Dispatch interface.
  2. (Optional) Add the service.setExecutor + 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 java.current.Executors + 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.
  3. Implement the + javax.xml.ws.AsynchHandler interface. The + javax.xml.ws.AsynchHandler interface only + has the + handleResponse(javax.xml.ws.Response) + 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.
  4. Invoke the asynchronous callback method with the + parameter data and the callback handler.
  5. The handleResponse(Response) method is + invoked on the callback object when the response is + available. The Response.get() method is + called within this method to deliver the response.
  +
4. To implement the polling method, + +
  1. Find the asynchronous polling method on the SEI or + javax.xml.ws.Dispatch interface. For an + SEI, the method name ends in Async and has + a return type of javax.xml.ws.Response. + The invokeAsync(Object) method is used on + the Dispatch interface.
  2. Invoke the asynchronous polling method with the + parameter data.
  3. The client receives the object type, + javax.xml.ws.Response, that is used to + monitor the status of the request to the server. The + isDone() method indicates whether the + invocation has completed. When the + isDone() method returns a value of true, + call the get() method to retrieve the + response object.
  +
5. Use the cancel() method for the callback + or polling method if the client needs to stop waiting for a + response from the service. If the cancel() + method is invoked by the client, the endpoint continues to + process the request. However, the wait and response + processing for the client is stopped.
+
+ + When developing Dynamic Proxy clients, after you generate the + portable client artifacts from a WSDL file using the + wsimport + 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 jaxws:enableAsyncMapping 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.
+
+ + Note: When you run the wsimport + tool and enable + asynchronous invocation through the use of the JAX-WS + enableAsyncMapping 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 wsimport + 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 + wsimport + tool, see the wsimport + command for + JAX-WS applications documentation.
+
+ + The following example illustrates a Web service interface + with methods for asynchronous requests from the client. +
```
+   @WebService
+
+   public interface CreditRatingService {
+          // Synchronous operation.
+          Score getCreditScore(Customer     customer);
+          // Asynchronous operation with polling.
+          Response<Score>
+ getCreditScoreAsync(Customer customer);
+          // Asynchronous operation with callback.
+          Future<?>
+ getQuoteAsync(Customer customer, 
+                 AsyncHandler<Score>
+ handler);
+   }
+
```
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 +Future<?> 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 Future.isDone() +method. Note that the Future.get() method does not +provide a meaningful response and is not similar to the + Response.get() method. +
```
+   CreditRatingService svc = ...;
+ 
+   Future<?>
+ invocation = svc.getCreditScoreAsync(customerTom,
+          new AsyncHandler<Score>() {
+                 public void handleResponse (
+                        Response<Score> response)
+                     {
+                        score = response.get();
+                        // process the request...
+                     }
+       }
+
+  );
+
```
Using the polling method The following example illustrates an +asynchronous polling client: +
```
+   CreditRatingService svc = ...;
+   Response<Score> response
+ = svc.getCreditScoreAsync(customerTom);
+ 
+   while (!response.isDone()
+) {
+          // Do something while we wait.
+   }
+ 
+
+   score = response.get()
+;
+
```
Using handlers in JAX-WS + Web services +
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 + javax.xml.ws.handler.LogicalHandler interface. A + logical handler receives a LogicalMessageContext + object from which the handler can get the message + information. Logical handlers can exist on both SOAP and + XML/HTTP-based configurations.
+
+ + 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 + javax.xml.ws.handler.soap.SOAPHandler interface. + Protocol handlers receive the message as a + javax.xml.soap.SOAPMessage to read the message + data.
+
+ + 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 + handleMessage(MessageContext) method or + handleFault(MessageContext) 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.
+
+ + To use handlers with Web services client applications, you + must add the @HandlerChain annotation to the + service endpoint interface or the generated service class and + provide the handler chain configuration file. The + @HandlerChain 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 handlerchain + class programmatically, use either the default implementation + or a custom implementation of the + HandlerResolver method.
+
+ + To use handlers with your server application, you must set + the @HandlerChain 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 @HandlerChain annotation on the service + endpoint implementation or the implementation class. The + handler classes must be included in the deployed + artifact.
+
+ + For both server and client implementations of handlers using + the @HandlerChain 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:
+
+
```
+   @HandlerChain(file="../../common/handlers/myhandlers.xml")
+
```
or +
```
+   @HandlerChain(file="http://foo.com/myhandlers.xml")
+
```
For more information on the schema of the handler +configuration file, see the JSR 181 specification.
+
+ + For more information regarding JAX-WS handlers, see chapter 9 + of the JAX-WS specification.
+
+ + To create a JAX-WS handler: + +
1. Determine if you want to implement JAX-WS handlers on + the service or the client. + +
  1. Use the default implementation of a handler + resolver. The runtime now uses the + @HandlerChain annotation and the default + implementation of HandlerResolver class to + build the handler chain. You can obtain the existing + handler chain from the Binding, add or + remove handlers, and then return the modified handler + chain to the Binding object.
  2. To use a custom implementation of a handler + resolver, set the custom HandlerResolver + class on the Service instance. The runtime + uses your custom implementation of the + HandlerResolver class to build the handler + chain, and the default runtime implementation is not + used. In this scenario, the @HandlerChain + annotation is not read when retrieving the handler + chain from the binding after the custom + HandlerResolver instance is registered on + the Service instance. You can obtain the + existing handler chain from the Binding, + add or remove handlers, and then return the modified + handler chain to the Binding object.
  +
2. Configure the client handlers by setting the + @HandlerChain 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.
3. Configure the server handlers by setting the + @HandlerChain annotation on the service + endpoint interface or implementation class. When the + @HandlerChain annotation is configured on both + the service endpoint interface and the implementation + class, the implementation class takes priority.
4. Create the handler chain configuration XML file. You + must create a handler chain configuration XML file for the + @HandlerChain to reference.
5. 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 + @HandlerChain annotation. You must also + include the handler classes contained in the configuration + XML file in your class path.
6. Write your handler implementation.
+
+ + The following example illustrates the steps necessary to + configure JAX-WS handlers on a service endpoint interface + using the @HandlerChain annotation.
+
+ + The @HandlerChain 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 + protocol-bindings, + port-name-pattern, and + service-name-pattern elements are all filters + that are used to restrict which services can apply the + handlers. +
```
+   <?xml version="1.0" encoding="UTF-8"?>
+
+   <jws:handler-chains xmlns:jws="http://java.sun.com/xml/ns/javaee">
+   
+
+        <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>
+
```
Make sure that you add the handler.xml file and the handler +classes contained in the handler.xml file in your class path.
+
+ + The following example demonstrates a handler implementation: +
```
+   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;
+       }
+
+   }
+
```
Enabling HTTP + session management support for JAX-WS + applications +
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.
+
+ + 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. + +
Session cookies
The HTTP maintain session feature + uses a single cookie, JSESSIONID, 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. + +
URL rewriting
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.
+
+ + To enable HTTP session management: + +
1. Configure the server to enable session tracking.
2. Enable session management on the client by setting the + JAX-WS property, + javax.xml.ws.session.maintain, to true on the + BindingProvider. +
```
+      Map<String, Object> rc = ((BindingProvider) port).getRequestContext();
+      ...
+      ...
+      rc.put(BindingProvider.SESSION_MAINTAIN_PROPERTY, Boolean.TRUE);
+      ...
+      ...
+   
+
```
+
Enabling MTOM +
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.
+
+ + 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.
+
+ + 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: +
```
+   // for SOAP version 1.1
+   @BindingType(value = SOAPBinding.SOAP11HTTP_MTOM_BINDING)
+   // for SOAP version 1.2
+   @BindingType(value = SOAPBinding.SOAP12HTTP_MTOM_BINDING)
+
```
+ + 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. + +
- Enable MTOM on a Dispatch client.
- The following example uses + SOAP version 1.1: + +
  - First method: Using + SOAPBinding.setMTOMEnabled()
  - ```
  +             SOAPBinding binding = (SOAPBinding)dispatch.getBinding();
  +             binding.setMTOMEnabled(true);
  +         
  +
```
- Second method: Using Service.addPort()
- ```
+ 
+             Service svc = Service.create(serviceName);
+             svc.addPort(portName,SOAPBinding.SOAP11HTTP_MTOM_BINDING,endpointUrl);
+         
+
```
  +
- Enable MTOM on a Dynamic Proxy client.
- ```
+          // 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);
+      
+
```
+

+ +

Axis2/Java

Downloads

Documentation

Resources

Get Involved

Project Information

JAX-WS Guide

Table of Contents

Introduction to + JAX-WS +

Introduction to + JAXB +

Developing + JAX-WS Web services +

Developing + a JAX-WS Web service from a JavaBean (bottom-up + development) +

Developing a + JAX-WS Web service from a WSDL document (top-down + development) +

Packaging and + deploying a JAX-WS service +

Developing + JAX-WS clients +

Dispatch client

Dynamic Proxy client

Developing a + JAX-WS client from a WSDL document +

Developing a + dynamic client using JAX-WS APIs +

Running a JAX-WS + client +

Invoking JAX-WS Web services + asynchronously +

Using the callback asynchronous invocation model

Using the polling asynchronous invocation model

Using an asynchronous message exchange

Using handlers in JAX-WS + Web services +

Enabling HTTP + session management support for JAX-WS + applications +

Session cookies

URL rewriting

Enabling MTOM +