JBoss.orgCommunity Documentation

Chapter 3. JAX-WS User Guide

3.1. Web Service Endpoints
3.1.1. Plain old Java Object (POJO)
3.1.2. EJB3 Stateless Session Bean (SLSB)
3.1.3. Endpoint Provider
3.2. Web Service Clients
3.2.1. Service
3.2.2. Dynamic Proxy
3.2.3. WebServiceRef
3.2.4. Dispatch
3.2.5. Asynchronous Invocations
3.2.6. Oneway Invocations
3.2.7. Timeout Configuration
3.3. Common API
3.3.1. Handler Framework
3.3.2. Message Context
3.3.3. Fault Handling
3.4. WS Annotations
3.4.1. javax.xml.ws.ServiceMode
3.4.2. javax.xml.ws.WebFault
3.4.3. javax.xml.ws.RequestWrapper
3.4.4. javax.xml.ws.ResponseWrapper
3.4.5. javax.xml.ws.WebServiceClient
3.4.6. javax.xml.ws.WebEndpoint
3.4.7. javax.xml.ws.WebServiceProvider
3.4.8. javax.xml.ws.BindingType
3.4.9. javax.xml.ws.WebServiceRef
3.4.10. javax.xml.ws.WebServiceRefs
3.4.11. javax.xml.ws.Action
3.4.12. javax.xml.ws.FaultAction
3.5. 181 Annotations
3.5.1. javax.jws.WebService
3.5.2. javax.jws.WebMethod
3.5.3. javax.jws.OneWay
3.5.4. javax.jws.WebParam
3.5.5. javax.jws.WebResult
3.5.6. javax.jws.SOAPBinding
3.5.7. javax.jws.HandlerChain

The Java API for XML-Based Web Services (JAX-WS / JSR-224) defines the mapping between WSDL and Java as well as the classes to be used for accessing webservices and publishing them. JBossWS implements the latest JAX-WS specification, hence users can reference it for any vendor agnostic webservice usage need. Below is a brief overview of the most basic functionalities.

JAX-WS simplifies the development model for a web service endpoint a great deal. In short, an endpoint implementation bean is annotated with JAX-WS annotations and deployed to the server. The server automatically generates and publishes the abstract contract (i.e. wsdl+schema) for client consumption. All marshalling/unmarshalling is delegated to JAXB .

Let's take a look at simple POJO endpoint implementation. All endpoint associated metadata is provided via JSR-181 annotations

@WebService
@SOAPBinding(style = SOAPBinding.Style.RPC)
public class JSEBean01
{
   @WebMethod
   public String echo(String input)
   {
      ...
   }
}

Service is an abstraction that represents a WSDL service. A WSDL service is a collection of related ports, each of which consists of a port type bound to a particular protocol and available at a particular endpoint address.

For most clients, you will start with a set of stubs generated from the WSDL. One of these will be the service, and you will create objects of that class in order to work with the service (see "static case" below).

Most clients will start with a WSDL file, and generate some stubs using JBossWS tools like wsconsume . This usually gives a mass of files, one of which is the top of the tree. This is the service implementation class.

The generated implementation class can be recognised as it will have two public constructors, one with no arguments and one with two arguments, representing the wsdl location (a java.net.URL ) and the service name (a javax.xml.namespace.QName ) respectively.

Usually you will use the no-argument constructor. In this case the WSDL location and service name are those found in the WSDL. These are set implicitly from the @WebServiceClient annotation that decorates the generated class.

The following code snippet shows the generated constructors from the generated class:

Section Dynamic Proxy explains how to obtain a port from the service and how to invoke an operation on the port. If you need to work with the XML payload directly or with the XML representation of the entire SOAP message, have a look at Dispatch .

You can create an instance of a client proxy using one of getPort methods on the Service .

The service endpoint interface (SEI) is usually generated using tools. For details see Top Down (WSDL to Java)

A generated static Service usually also offers typed methods to get ports. These methods also return dynamic proxies that implement the SEI.

The @WebServiceRef annotation is used to declare a reference to a Web service. It follows the resource pattern exemplified by the javax.annotation.Resource annotation in JSR-250 .

There are two uses to the WebServiceRef annotation:

  1. To define a reference whose type is a generated service class. In this case, the type and value element will both refer to the generated service class type. Moreover, if the reference type can be inferred by the field/method declaration the annotation is applied to, the type and value elements MAY have the default value (Object.class, that is). If the type cannot be inferred, then at least the type element MUST be present with a non-default value.

  2. To define a reference whose type is a SEI. In this case, the type element MAY be present with its default value if the type of the reference can be inferred from the annotated field/method declaration, but the value element MUST always be present and refer to a generated service class type (a subtype of javax.xml.ws.Service). The wsdlLocation element, if present, overrides theWSDL location information specified in the WebService annotation of the referenced generated service class.

    public class EJB3Client implements EJB3Remote
    {
       @WebServiceRef
       public TestEndpointService service4;
    
       @WebServiceRef
       public TestEndpoint port3;

We offer a number of overrides and extensions to the WebServiceRef annotation. These include

For details please see service-ref_5_0.dtd .

XMLWeb Services use XML messages for communication between services and service clients. The higher level JAX-WS APIs are designed to hide the details of converting between Java method invocations and the corresponding XML messages, but in some cases operating at the XML message level is desirable. The Dispatch interface provides support for this mode of interaction.

Dispatch supports two usage modes, identified by the constants javax.xml.ws.Service.Mode.MESSAGE and javax.xml.ws.Service.Mode.PAYLOAD respectively:

Message In this mode, client applications work directly with protocol-specific message structures. E.g., when used with a SOAP protocol binding, a client application would work directly with a SOAP message.

Message Payload In this mode, client applications work with the payload of messages rather than the messages themselves. E.g., when used with a SOAP protocol binding, a client application would work with the contents of the SOAP Body rather than the SOAP message as a whole.

Dispatch is a low level API that requires clients to construct messages or message payloads as XML and requires an intimate knowledge of the desired message or payload structure. Dispatch is a generic class that supports input and output of messages or message payloads of any type.

This sections describes concepts that apply equally to Web Service Endpoints and Web Service Clients.

The handler framework is implemented by a JAX-WS protocol binding in both client and server side runtimes. Proxies, and Dispatch instances, known collectively as binding providers, each use protocol bindings to bind their abstract functionality to specific protocols.

Client and server-side handlers are organized into an ordered list known as a handler chain. The handlers within a handler chain are invoked each time a message is sent or received. Inbound messages are processed by handlers prior to binding provider processing. Outbound messages are processed by handlers after any binding provider processing.

Handlers are invoked with a message context that provides methods to access and modify inbound and outbound messages and to manage a set of properties. Message context properties may be used to facilitate communication between individual handlers and between handlers and client and service implementations. Different types of handlers are invoked with different types of message context.

MessageContext is the super interface for all JAX-WS message contexts. It extends Map<String,Object> with additional methods and constants to manage a set of properties that enable handlers in a handler chain to share processing related state. For example, a handler may use the put method to insert a property in the message context that one or more other handlers in the handler chain may subsequently obtain via the get method.

Properties are scoped as either APPLICATION or HANDLER. All properties are available to all handlers for an instance of an MEP on a particular endpoint. E.g., if a logical handler puts a property in the message context, that property will also be available to any protocol handlers in the chain during the execution of an MEP instance. APPLICATION scoped properties are also made available to client applications (see section 4.2.1) and service endpoint implementations. The defaultscope for a property is HANDLER.

For details, see JSR-224 - Java API for XML-Based Web Services (JAX-WS) 2.2

JSR-181 defines the syntax and semantics of Java Web Service (JWS) metadata and default values.

For details, see JSR 181 - Web Services Metadata for the Java Platform .