Red Hat Training

A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform

16.6. JAX-WS Development Reference

16.6.1. Enable Web Services Addressing (WS-Addressing)


  • Your application must have an existing JAX-WS service and client configuration.

Procedure 16.2. Annotate and Update client code

  1. Annotate the service endpoint

    Add the @Addressing annotation to the application's endpoint code.

    Example 16.28. @Addressing annotation

    This example demonstrates a regular JAX-WS endpoint with the @Addressing annotation added.
    import javax.jws.WebService;
       portName = "AddressingServicePort",
       serviceName = "AddressingService",
       wsdlLocation = "WEB-INF/wsdl/AddressingService.wsdl",
       targetNamespace = "",
       endpointInterface = ""
    @Addressing(enabled=true, required=true)
    public class ServiceImpl implements ServiceIface
       public String sayHello()
          return "Hello World!";
  2. Update client code

    Update the client code in the application so that it configures WS-Addressing.

    Example 16.29. Client configuration for WS-Addressing

    This example demonstrates a regular JAX-WS client updated to configure WS-Addressing.
    import javax.xml.namespace.QName;
    public final class AddressingTestCase
       private final String serviceURL = 
       public static void main(String[] args) throws Exception
          // construct proxy
          QName serviceName = 
              new QName("",
          URL wsdlURL = new URL(serviceURL + "?wsdl");
          Service service = Service.create(wsdlURL, serviceName);
          ServiceIface proxy = 
                                            new AddressingFeature());
          // invoke method

The client and endpoint are now communicating using WS-Addressing.

16.6.2. JAX-WS Common API Reference

Several JAX-WS development concepts are shared between Web Service endpoints and clients. These include the handler framework, message context, and fault handling.
Handler Framework

The handler framework is implemented by a JAX-WS protocol binding in the runtime of the client and the endpoint, which is the server component. 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 before the binding provider processes them. Outbound messages are processed by handlers after the binding provider processes them.
Handlers are invoked with a message context which provides methods to access and modify inbound and outbound messages and to manage a set of properties. Message context properties facilitate communication between individual handlers, as well as between handlers and client and service implementations. Different types of handlers are invoked with different types of message contexts.

Types of Message Handlers

Logical Handler
Logical handlers only operate on message context properties and message payloads. Logical handlers are protocol-independent and cannot affect protocol-specific parts of a message. Logical handlers implement interface
Protocol Handler
Protocol handlers operate on message context properties and protocol-specific messages. Protocol handlers are specific to a particular protocol and may access and change protocol-specific aspects of a message. Protocol handlers implement any interface derived from except
Service Endpoint Handler
On a service endpoint, handlers are defined using the @HandlerChain annotation. The location of the handler chain file can be either an absolute in externalForm or a relative path from the source file or class file.

Example 16.30. Example Service Endpoint Handler

@HandlerChain(file = "jaxws-server-source-handlers.xml")
public class SOAPEndpointSourceImpl

Service Client Handler
On a JAX-WS client, handlers are defined either by using the @HandlerChain annotation, as in service endpoints, or dynamically, using the JAX-WS API.

Example 16.31. Defining a Service Client Handler Using the API

Service service = Service.create(wsdlURL, serviceName);
Endpoint port = (Endpoint)service.getPort(Endpoint.class);
BindingProvider bindingProvider = (BindingProvider)port;
List<Handler> handlerChain = new ArrayList<Handler>();
handlerChain.add(new LogHandler());
handlerChain.add(new AuthorizationHandler());
handlerChain.add(new RoutingHandler());
The call to the setHandlerChain method is required.
Message Context

The MessageContext interface 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 into the message context. One or more other handlers in the handler chain may subsequently obtain the message via the get method.

Properties are scoped as either APPLICATION or HANDLER. All properties are available to all handlers for an instance of a message exchange pattern (MEP) of a particular endpoint. For instance, if a logical handler puts a property into the message context, that property is also available to any protocol handlers in the chain during the execution of an MEP instance.


An asynchronous Message Exchange Pattern (MEP) allows for sending and receiving messages asynchronously at the HTTP connection level. You can enable it by setting additional properties in the request context.
Properties scoped at the APPLICATION level are also made available to client applications and service endpoint implementations. The defaultscope for a property is HANDLER.
Logical amd SOAP messages use different contexts.
Logical Message Context
When logical handlers are invoked, they receive a message context of type LogicalMessageContext. LogicalMessageContext extends MessageContext with methods which obtain and modify the message payload. It does not provide access to the protocol-specific aspects of a message. A protocol binding defines which components of a message are available via a logical message context. A logical handler deployed in a SOAP binding can access the contents of the SOAP body but not the SOAP headers. On the other hand, the XML/HTTP binding defines that a logical handler can access the entire XML payload of a message.
SOAP Message Context
When SOAP handlers are invoked, they receive a SOAPMessageContext. SOAPMessageContext extends MessageContext with methods which obtain and modify the SOAP message payload.
Fault Handling

An application may throw a SOAPFaultException or an application-specific user exception. In the case of the latter, the required fault wrapper beans are generated at run-time if they are not already part of the deployment.

Example 16.32. Fault Handling Examples

public void throwSoapFaultException()
   SOAPFactory factory = SOAPFactory.newInstance();
   SOAPFault fault = factory.createFault("this is a fault string!", new QName("http://foo", "FooCode"));
   throw new SOAPFaultException(fault);
public void throwApplicationException() throws UserException
   throw new UserException("validation", 123, "Some validation error");
JAX-WS Annotations

The annotations available via the JAX-WS API are defined in JSR-224, which can be found at These annotations are in package

The annotations available via the JWS API are defined in JSR-181, which can be found at These annotations are in package javax.jws.