Users Guide

Jakarta XML Web Services 4.0 is a new Release of XML-WS API and it has the following new features from Jakarta XML Web Services 4.0 specification:

Jakarta XML Web Services 4.0 has the following features from Jakarta XML Web Services specification:

JAX-RPC users should note that Jakarta XML Web Services is a completely different technology than JAX-RPC and thus cannot run JAX-RPC applications on top of Jakarta XML Web Services. If you have an existing JAX-RPC application it must be converted to work with Jakarta XML Web Services.

In Jakarta XML Web Services, all artifacts generated by annotationProcessing, wsimport and wsgen are portable. Jakarta XML Web Services uses the annotations within the SEI to aid in marshalling/unmarshalling messages. Because we no longer generated non-portable artifacts, we were able to get rid of tools like JAX-RPC's wsdeploy. The user now can create their own deployable WAR file. To learn more about creating a WAR file and the deployment descriptor, see WAR File Packaging. It should also be noted that JAX-RPC's wscompile tool has been replaced by two new tools: wsimport and wsgen. wsimport is used for importing WSDLs and generating the portable artifacts. wsgen processes a compiled SEI and generates the portable artifacts. Unlike JAX-RPC's wscompile Jakarta XML Web Services's wsgen does not generate WSDL at tool-time, the WSDL is now generated when the endpoint is deployed. There however is an option on wsgen to generate the WSDL for developement purposes.

MTOM and swaRef support was added in Eclipse Implementation of XML Web Services release. MTOM and swaref support is required by the Jakarta XML Web Services specification. This means that the MTOM or swaref solution developed with Eclipse Implementation of XML Web Services will be fully portable with any Jakarta XML Web Services compliant implementation.

MTOM implementation was completely re-written to allow streaming attachment support and just like rest of the Eclipse Implementation of XML Web Services runtime its written for better performance. This implementation was released as part of Eclipse Implementation of XML Web Services release.

Eclipse Implementation of XML Web Services brings in support for optimized transmission of binary data as specified by MTOM (SOAP Message Transmission Optimization Mechanism)/ XOP (XML Binary Optimized Packaing) and swaRef (SOAP Attachment References specified by WS-I Attachment Profile 1.0).

For details on MTOM and swaRef features refer to MTOM and Swaref.

SOAP 1.2 support is added to Eclipse Implementation of XML Web Services. For details refer to SOAP 1.2.

Support for XML/HTTP binding is added to Jakarta XML Web Services. One can directly send XML over HTTP using Provider and Dispatch implementations. This enables support for REST style Web Services in Jakarta XML Web Services. For details refer to restful sample.

Eclipse Implementation of XML Web Services 4.0.0 uses Jakarta XML Binding 4.0 for data-binding between Java and XML which enables features such as separate compilation, type substitution and other improvements.

Eclipse Implementation of XML Web Services 4.0.0 supports for W3C Core, SOAP Binding and Addressing 1.0 - Metadata specifications and defines standard API and annotations to enable/disable W3C WS-Addressing on the client and service endpoint. In addition to that, Eclipse Implementation of XML Web Services also supports Member Submission version of WS-Addressing. The member submission version is supported in an implementation specific way. For compatility Eclipse Implementation of XML Web Services also supports wsdls conforming to WSDL Binding specification.

Refer to WS-Addressing for more details. See WS-Addressing samples fromjava-wsaddressing, fromwsdl-wsaddressing-policy and fromwsdl-wsaddressing with the Eclipse Implementation of XML Web Services 4.0.0 for details on the WS-Addressing programming model.

Jakarta XML Web Services 4.0 relies heavily on the use of annotations as provided by A Metadata Facility for the Java Programming Language (JSR 175) and Jakarta Web Services Metadata (link) as well as additional annotations defined by Jakarta XML Web Services 4.0. These annotations are used to customize the mapping from Java to XML schema/WSDL and are used at runtime to alleviate the need for non-portable serializers/deserializers that were generated in JAX-RPC 1.x. (JSR 269) Pluggable Annotation Processing API comes as replacement of apt

The Eclipse Implementation of XML Web Services utilizes an javac Pluggable Annotation Processing API functionality that was introduced in Java SE 6. javac allows the SI to process Java source files directly to generate the portable artifacts specified by the Jakarta XML Web Services specification. javac comes as replacement of deprecated apt. More documentation about javac can be found in section Annotation Processing Deprecated apt will be covered in more detail in section apt.

For more information on the annotations used by Jakarta XML Web Services 2.0 please refer to Annotations.

Eclipse Implementation of XML Web Services 4.0.0 carries forward customization support introduced in Jakarta XML Web Services.

Jakarta XML Web Services specification defines standard XML based customization for a WSDL file to Java mapping and to control certain features. These customizations, or binding declarations, can customize almost all WSDL components that can be mapped to Java, such as the service endpoint interface class, method name, parameter name, exception class, etc. The other important thing you can do with these binding declarations is to control certain features, such as asynchrony, provider, wrapper style, and additional headers. For example, a client application can enable asynchrony for a particular operation in a portType, all operations in a portType, or all portType operations defined in the WSDL file.

These binding declarations can be inlined in a WSDL file or can live outside as an external file. The binding declarations closely align with the Jakarta XML Binding binding declarations. An application importing a WSDL file can inline Jakarta XML Binding bindings inside Jakarta XML Web Services binding declarations to customize the inlined schema declared in the WSDL file. Schema files that are imported from a WSDL file can be customized using Jakarta XML Binding binding files and can be passed to wscompile using the -b option switch.

These are the main customization features:

The following WSDL component's mapped Java names can be modified:

XML Schema Java mapping can be customized using standard Jakarta XML Binding customizations.

For more information on the customizations used by Jakarta XML Web Services please refer to WSDL Customization.

Jakarta XML Web Services specification defines two types of handlers: logical and protocol handlers. While protocol handlers have access to an entire message such as a SOAP message, logical handlers deal only with the payload of a message and are independent of the protocol being used. Handler chains can now be configured on a per-port, per-protocol, or per-service basis. A new framework of context objects has been added to allow client code to share information easily with handlers.

For more information on the handler framework in Eclipse Implementation of XML Web Services 4.0.0 please refer to Handler.

Web service endpoints may choose to work at the XML message level by implementing the Provider interface. Here the endpoints access messages or message payloads using this low level, generic API.

For more information on providers in Eclipse Implementation of XML Web Services 4.0.0 please refer to Provider.

The Dispatch API is intended for advanced XML developers who prefer to use XML constructs at the java.lang.transform.Source or jakarta.xml.soap.SOAPMessage level. For added convenience use of the Dispatch API with Jakarta XML Binding data-bound objects is supported. The Dispatch API can be used in both Message and Payload modes.

For more information on the Dispatch  please refer to Dispatch.

For more information on asynchronous clients in Eclipse Implementation of XML Web Services 4.0.0 please refer to Asynchronous Client.

When developing a web service endpoint, a developer may either start from a Java endpoint implementation class or from a WSDL file. A WSDL (Web Services Description Language) document describes the contract between the web service endpoint and the client. A WSDL document may include and/or import XML schema files used to describe the data types used by the web service. When starting from a Java class, the tools generate any portable artifacts as mandated by the spec. When starting from a WSDL file and schemas, the tools generate a service endpoint interface.

There is a trade-off when starting from a Java class or from a WSDL file. If you start from a Java class, you can make sure that the endpoint implementation class has the desirable Java data types, but the developer has less control of the generated XML schema. When starting from a WSDL file and schema, the developer has total control over what XML schema is used, but has less control over what the generated service endpoint and the classes it uses will contain.

package fromjava.server;

import jakarta.jws.WebService;

@WebService
public class AddNumbersImpl {
    /**
     * @param number1
     * @param number2
     * @return The sum
     * @throws AddNumbersException if any of the numbers to be added is 
     * negative.
     */
    public int addNumbers(int number1, int number2) throws 
            AddNumbersException {
        if (number1 < 0 || number2 < 0) {
            throw new AddNumbersException("Negative number cant be " +
                    "added!", "Numbers: " + number1 + ", " + number2);
        }
        return number1 + number2;
    }
}

<annotationProcessing
        debug="${debug}"
        verbose="${verbose}"
        destdir="${build.classes.home}"
        sourceDestDir="${build.classes.home}"
        srcdir="${basedir}/src"
        includes="**/server/*.java"
        sourcepath="${basedir}/src">
    
    <classpath refid="jax-ws.classpath"/>
</annotationProcessing>

AddNumbers.class
AddNumbers.java
AddNumbersExceptionBean.class
AddNumbersExceptionBean.java
AddNumbersResponse.class
AddNumbersResponse.java

<?xml version="1.0" encoding="UTF-8"?>
<endpoints xmlns='http://java.sun.com/xml/ns/jax-ws/ri/runtime'
        version='2.0'>
    <endpoint name='fromjava'
            implementation='fromjava.server.AddNumbersImpl'
            url-pattern='/addnumbers'/>
</endpoints>

META-INF/MANIFEST.MF
WEB-INF/sun-jaxws.xml
WEB-INF/web.xml
WEB-INF/classes/fromjava/server/AddNumbersException.class
WEB-INF/classes/fromjava/server/AddNumbersImpl.class
WEB-INF/classes/fromjava/server/jaxws/AddNumbers.class
WEB-INF/classes/fromjava/server/jaxws/AddNumbersExceptionBean.class
WEB-INF/classes/fromjava/server/jaxws/AddNumbersResponse.class

<wsimport
        debug="${debug}"
        verbose="${verbose}"
        keep="${keep}"
        destdir="${build.classes.home}"
        wsdl="${server.wsdl}">
    
    <binding dir="${basedir}/etc"
            includes="${server.binding}"/>
</wsimport>

wsimport.sh etc/AddNumbers.wsdl -b custom-server.xml

package fromwsdl.server;

@jakarta.jws.WebService(
        name = "AddNumbersPortType",
        serviceName = "AddNumbersService",
        targetNamespace = "http://duke.example.org")
@jakarta.jws.soap.SOAPBinding(
        style = jakarta.jws.soap.SOAPBinding.Style.DOCUMENT,
        use = jakarta.jws.soap.SOAPBinding.Use.LITERAL,
        parameterStyle = jakarta.jws.soap.SOAPBinding.ParameterStyle.WRAPPED)
public interface AddNumbersPortType extends java.rmi.Remote {
    @jakarta.jws.WebMethod(operationName = "addNumbers")
    @jakarta.jws.WebResult(name = "return")
    public int addNumbers(@jakarta.jws.WebParam(name = "arg0") int arg0,
                          @jakarta.jws.WebParam(name = "arg1") int arg1)
            throws fromwsdl.server.AddNumbersFault_Exception, java.rmi.RemoteException;
}

package fromwsdl.server;

@WebService(endpointInterface = "fromwsdl.server.AddNumbersPortType")
public class AddNumbersImpl implements AddNumbersPortType {
    /**
     * @param number1
     * @param number2
     * @return The sum
     * @throws AddNumbersException if any of the numbers to be added is 
     * negative.
     */
    public int addNumbers(int number1, int number2) throws 
            AddNumbersFault_Exception {
        ...
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<endpoints xmlns="http://java.sun.com/xml/ns/jax-ws/ri/runtime"
        version="2.0">
    <endpoint name="fromwsdl"
            interface="fromwsdl.server.AddNumbersPortType"
            implementation="fromwsdl.server.AddNumbersImpl"
            wsdl="WEB-INF/wsdl/AddNumbers.wsdl"
            service="{http://duke.example.org}AddNumbersService"
            port="{http://duke.example.org}AddNumbersPort"
            url-pattern="/addnumbers"/>
</endpoints>

A client application can access a remote web service endpoint in one of two ways: port and dispatch.

<wsimport
        debug="${debug}"
        verbose="${verbose}"
        keep="${keep}"
        destdir="${build.classes.home}"
        wsdl="${client.wsdl}">
    <classpath>
        <path refid="jax-ws.classpath"/>
        <pathelement location="${build.classes.home}"/>
    </classpath>
    <binding dir="${basedir}/etc" includes="${client.binding}"/>
</wsimport>

wsimport.sh -classpath client_classpath -d dest_dir -s src_dir \
    -b custom-client.xml http://localhost:8080/jax-ws-fromwsdl/addnumbers?WSDL

//get the port
AddNumbersPortType port = new AddNumbersService().getAddNumbersPort();

//invoke the remote method
int result = port.addNumbers(10, 20);

The jakarta.xml.ws.Service acts as a factory for the creation of a dynamic Service. When created for use with Dispatch<T> APIs the Service created can be either a Service that has knowledge of the binding information of a known Service or no knowledge of any specific Service.

That is, when the Service is created with a WSDL file the port(s) binding ID, QName, and endpoint address are known to the Service.

The methods to create a dynamic Service are shown here:

Service service = Service.create(QName serviceQName);
Service service = Service.create(URL wsdlLocation, QName serviceQName);

A Dispatch<T> instance must be bound to a specific port and endpoint before use. The service has an addPort(QName portName, URI bindingID, String endpointAddress) method that the client program can invoke for Dispatch<T> objects. Ports created using this method can only be used with Dispatch<T> instances.

If the Service has been created with WSDL binding information the the port need not be added as the Dispatch<T> instance will be created specific for the binding information provided in the supplied WSDL file.

Developers who have used web service applications in the past are familiar with the port QName and endpoint address parameters of this method. Eclipse Implementation of XML Web Services 4.0.0 supports three Binding URI's, that of the SOAP 1.1, the SOAP 1.2 and XML/HTTP Binding. For more information on SOAP 1.2 support please refer to the SOAP 1.2 documents. For the XML/HTTP binding please see chapter 11 of the Jakarta XML Web Services Specification.

The addition of the SOAP 1.1 port using the Service API is shown here:

service.addPort(QName portName, String SOAPBinding.SOAP11HTTP_BINDING,
        String endpointAddress);

SOAP 1.2 support has been implemented for Dispatch. This requires only one change in the programming model. The addition of the SOAP 1.2 port using the Service API is shown here:

service.addPort(QName portName, String SOAPBinding.SOAP12HTTP_BINDING,
        String endpointAddress);

XML/HTTP binding support has been implemented for Dispatch. The creation of the XML/HTTP port using the Service API is shown here:

service.addPort(QName portName, String HTTPBinding.HTTP_BINDING,
        String endpointAddress);

The Dispatch<T> object can be created using either of these two Service methods:

Dispatch dispatch = service.createDispatch(QName portName, 
        Class clazz, Service.Mode mode);
Dispatch dispatch = service.createDispatch(QName portName, 
        JAXBContext jaxbcontext, Service.Mode mode);

For a javax.xml.transform.Source and Jakarta XML Binding data binding java.lang.Object Dispatch<T> can be created in both Service.Mode.PAYLOAD and Service.Mode.MESSAGE modes. A jakarta.xml.soap.SOAPMessage can only be created in Service.Mode.MESSAGE mode. The first form of the createDispatch method is used to create a javax.xml.transform.Source or jakarta.xml.soap.SOAPMessage specific to the Dispatch<T> instance.

A Jakarta XML Binding object-specific instance can only be created using the second method listed above.

It is important to note that once the Dispatch<T> instance is created it is static. That is, its Service.Mode or request type can not be changed. The instance can be reused given the caveat that if it is a Jakarta XML Binding-specific Dispatch<T> it must be reused with objects known to the same JAXBContext.

The Dispatch<T> interface extends the jakarta.xml.ws.BindingProvider interface. The BindingProvider interface defines accessor methods for the request and response context maps. Standard BindingProvider properties are defined by the Jakarta XML Web Services specification and the client program may set and get these properties. The application may also define application-specific properties, but the specification discourages this for portability reasons.

This is the client developer's responsibility. For examples of how to prepare specific request types refer to the Dispatch<T> sample applications.

Four types of invocation MEPs are supported using the methods below. In methods that produce a response, the type of Object returned will be of the same type as the request. For example, a SOAPMessage request will return a SOAPMessage response.

Object response = dispatch.invoke(T);
dispatch.invokeOneway(T);
Response<T> response = dispatch.invokeAsync(T);
Future<?> response = dispatch.invokeAsync(T, AsyncHandler);

//async polling Method
public Response<AddNumbersResponse> addNumbers(int number1, int number2);

Typically a client application will invoke the async polling operation on the stub and check for a response on the returned Response object. The response is available when Response.isDone returns true.

jakarta.xml.ws.Response<AddNumbersResponse> resp = port
        .addNumbersAsync(10, 20);
while (!resp.isDone()) {
    //do something
}
System.out.println("The sum is: " + resp.get().getReturn());

...

//async callback Method
public Future<?> addNumbers(int number1, int number2, AsyncHandler<AddNumbersResponse>);

Here the client application provides an AsyncHandler by implementing the jakarta.xml.ws.AsyncHandler<T> interface.

/**
 * Async callback handler
 */
class AddNumbersCallbackHandler implements 
        AsyncHandler<AddNumbersResponse> {
    private AddNumbersResponse output;

    /**
     * @see jakarta.xml.ws.AsyncHandler#handleResponse(jakarta.xml.ws.Response)
     */
    public void handleResponse(Response<AddNumbersResponse> response) {
        try {
            output = response.get();
        } catch (ExecutionException e) {
            e.printStackTrace();
        } catch (InterruptedException e) {
            e.printStackTrace();
        }
    }

    AddNumbersResponse getResponse() {
        return output;
    }
}

The async handler is then passed as the last parameter of the async callback method:

//instantiates the callback handler
AddNumbersCallbackHandler callbackHandler = new 
        AddNumbersCallbackHandler();

//invoke the async callback method
Future<?> resp = port.addNumbersAsync(number1, number2, callbackHandler);
while (!resp.isDone()) {
    //do something
}
System.out.println("The sum is: " + callbackHandler.getResponse().getReturn());

Starting from a WSDL file, handler chain configuration is through WSDL customizations as defined by Jakarta Enterprise Web Services. A <handler-chains> element is added to the customization file. The following is a simple handler chain with one handler (customization may be on server or client side):

<-- excerpt from customization file -->
<bindings xmlns="https://jakarta.ee/xml/ns/jaxws">
    <handler-chains xmlns="https://jakarta.ee/xml/ns/jakartaee">
        <handler-chain>
            <handler>
                <handler-class>fromwsdl.handler_simple.common.TestHandler
                </handler-class>
            </handler>
        </handler-chain>
    </handler-chains>
</bindings>

Multiple handler-chain elements may exist within the handler-chains element. These may optionally use a service name, port name, or protocol pattern in their description to apply some chains to certain ports and protocols and not to others. For instance (note the wildcard character used in the service name):

<-- excerpt -->
<handler-chains xmlns="https://jakarta.ee/xml/ns/jakartaee">
    <handler-chain>
        <service-name-pattern xmlns:ns1="urn:namespace">ns1:My*Service
        </service-name-pattern>
        <handler>...</handler>
    </handler-chain>

    <handler-chain>
        <port-name-pattern xmlns:ns1="urn:namespace">ns1:HelloPort
        </port-name-pattern>
        <handler>...</handler>
    </handler-chain>

    <handler-chain>
        <protocol-bindings>##SOAP11_HTTP</protocol-bindings>
        <handler>...</handler>
    </handler-chain>
</handler-chains>

Handlers will appear in the final handler chain in the order that they are included in the customization file. However, logical handlers will be sorted out and called before protocol handlers during execution.

Starting from a Java class, annotations are used to describe the handler chain as defined by Jakarta Web Services Metadata. The following example uses the @HandlerChain annotation to refer to a file describing the chain.

import jakarta.jws.HandlerChain;
import jakarta.jws.WebService;

@WebService
@HandlerChain(file = "handlers.xml")
public class MyServiceImpl {
    // implementation of class
}

An example handlers.xml file is shown below. The schema is the same that is used for the customization.

<?xml version="1.0" encoding="UTF-8"?>
<jws:handler-chains xmlns:jws="https://jakarta.ee/xml/ns/jakartaee">
    <jws:handler-chain>
        <jws:handler>
            <jws:handler-class>fromjava.handler_simple.common.TestHandler
            </jws:handler-class>
        </jws:handler>
    </jws:handler-chain>
</jws:handler-chains>

When packaging the service, the handlers.xml file must be in the classpath within the WAR file, either directly under WEB-INF/classes or further down in the same package as the service class file.

On the server side, the handlers may be configured in the sun-jaxws.xmldeployment descriptor as well. A handler chain specified here will override handlers in WSDL customizations or annotated classes. The schema for the handler section is the same as in the previous examples:

<endpoints ...>
    <endpoint...>
        <handler-chains xmlns="https://jakarta.ee/xml/ns/jakartaee">
            <handler-chain>
                ...
            </handler-chain>
        </handler-chains>
    </endpoint>
</endpoints>

Handler chains may be configured on the client side at runtime by setting a chain directly on a BindingProvider (e.g., a Dispatch object or a port proxy) or by using a HandlerResolver. This example shows how to add a handler chain to a port proxy:

// given proxy interface HelloPortType
HelloPortType myProxy = // create proxy

Binding binding = ((BindingProvider) myProxy).getBinding();

// can create new list or use existing one
List<Handler> handlerList = binding.getHandlerChain();

handlerList.add(new MyHandler());
binding.setHandlerChain(handlerList);

To configure the handlers that are added to newly created Binding objects, add a handler resolver to the service with setHandlerResolver(). The new resolver will be used whenever a BindingProvider is created from the service. An example resolver is as follows:

/*
 * Add handlers to the returned list based on the information
 * in info.getBindingID(), getPortName(), and/or getServiceName().
 */
public class MyResolver implements HandlerResolver {
    
    public List<Handler> getHandlerChain(PortInfo info) {
        List<Handler> handlers = new ArrayList<Handler>();
        // add handlers to list based on PortInfo information
        return handlers;
    }
    
}

A resolver that modifies the initially configured handler chains could be written by calling service.getHandlerResolver() and passing the original resolver to a new one:

// original HandlerResolver passed in constructor or setter method
public List<Handler> getHandlerChain(PortInfo info) {
    List<Handler> handlers = originalResolver.getHandlerChain(info);
    // alter list based on PortInfo information
    return handlers;
}

An schema element of type xs:bas64Binary or xs:hexBinary can be annotated by using attribute reference using xmime:expectedContentType Jakarta XML Binding specification defines xmime:expectedContentType to Java type mapping in Table 3, “xmime:expectedContentType to Java type mapping”. Here is this table:

<element name="image" type="base64Binary"/>

is mapped to byte[]

<element name="image" type="base64Binary"
        xmime:expectedContentTypes="image/jpeg"
        xmlns:xmime="http://www.w3.org/2005/05/xmlmime"/>

is mapped to java.awt.Image

xmime:contentType schema annotation indicates the content-type of an XML element content whose type is xs:base64Binary or xs:hexBinary. The value of the attribute is a valid content-type string (e.g., "text/xml; charset=utf-16"). This attribute specifies the content-type of the element content on which it occurs. This annotation can be primarily used to indicate the Content-Type of binary data.

For example the schema type

<element name="TestMtomXmimeContentType" type="types:PictureType"/>
<complexType name="PictureType">
    <simpleContent>
        <restriction base="xmime:base64Binary">
            <attribute ref="xmime:contentType" use="required"/>
        </restriction>
    </simpleContent>
</complexType>

Here xmime:base64Binary is defined by Describing Media Content of Binary Data in XML.

Gets mapped to PicutreType bean by wsimport:

 PictureType req = new PictureType();
req.setValue(name.getBytes());
req.setContentType("application/xml"); 

On the wire this is how it looks:

 <?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv=" http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:xsd=" http://www.w3.org/2001/XMLSchema"
        xmlns:ns1=" http://example.org/mtom/data"
        xmlns:ns2="http://www.w3.org/2005/05/xmlmime">
    <soapenv:Body>
        <ns1:TestMtomXmimeContentTypeResponse
                ns2:contentType="application/xml">
            <xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include"
                    href="c id:193ed174-d313-4325-8eed-16cc25595e4e@example.org"/>
        </ns1:TestMtomXmimeContentTypeResponse>
    </soapenv:Body>
</soapenv:Envelope> 

Enabling MTOM on Server:

Enabling MTOM on Client:

As defined by Jakarta XML Binding specification xs:base64Binary and xs:hexBinary mapping to java is byte[]. Eclipse Implementation of XML Web Services has set a threshold of 1KB of byte[] size. This threshold can be modified using implementation specific property com.sun.xml.ws.developer.JAXWSProperties.MTOM_THRESHOLD_VALUE in the RequestContext on the client side and in the MessageContext on the server side. If the byte[] that is being sent is less than this threshold (default is 1KB) then the binary data is base64 encoded by Jakarta XML Binding and in lined inside the SOAP Body otherwise the binary data is sent as attachment mime part in Multipart/Related package and XML infoset for the binary data is XOP encoded by Jakarta XML Binding

<xop:Include href=...>

is used to reference the attachment. The XOP encoding and packaging is done as per described by the XOP packaging rules. The href is the the Content-ID of the attachment and is encoded as per CID URI scheme defined in RFC 2111. xmime:contentType attribute may appear on the element that includes binary data to indicate preferred media type as annotated on the corresponding schema.

Jakarta XML Binding defines mapping of wsi:swaRef schema type to javax.activation.DataHandler. An application will construct the DataHandler with the data and the appropriate MIME type and Jakarta XML Web Services will coordinate with Jakarta XML Binding and Jakarta SOAP with Attachments to send it as attachment MIME part.

An XML element of type wsi:swaRef is mapped to a DataHandler and is sent as attachment over the wire. For example,

<element name="claimForm" type="wsi:swaRef"
        xmlns:wsi="http://ws-i.org/profiles/basic/1.1/xsd"/>

will be sent over the wire as :

Content-Type: Multipart/Related; start-info="text/xml"; type="application/xop+xml";
    boundary="----=_Part_4_32542424.1118953563492"
Content-Length: 1193
SOAPAction: ""

------=_Part_5_32550604.1118953563502
Content-Type: application/xop+xml; type="text/xml"; charset=utf-8

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <claimForm xmlns="http://example.org/mtom/data">
            cid:b0a597fd-5ef7-4f0c-9d85-6666239f1d25@example.jaxws.sun.com
        </claimForm>
    </soapenv:Body>
</soapenv:Envelope>

------=_Part_5_32550604.1118953563502
Content-Type: application/xml
Content-ID: <b0a597fd-5ef7-4f0c-9d85-6666239f1d25@example.jaxws.sun.com>

<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://java.sun.com/xml/ns/j2ee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocaption="http://java.sun.com/xml/ns/j2ee
    http://java.sun.com/xml/ns/j2ee/application_1_4.xsd" version="1.4">
    <display-name>Simple example of application</display-name>
    <description>Simple example</description>
    <module>
        <ejb>ejb1.jar</ejb>
    </module>
    <module>
        <ejb>ejb2.jar</ejb>
    </module>
    <module>
        <web>
            <web-uri>web.war</web-uri>
            <context-root>web</context-root>
        </web>
    </module>
</application>

Refer to swaRef sample testSwaRef() method in samples/mime/src/mime/client/MimeApp.java

External binding files are semantically equivalent to embedded binding declarations. When wsimport processes the WSDL document for which there is an external binding file, it internalizes the binding declarations defined in the external binding file on the nodes in the WSDL document they target using the wsdlLocation attribute. The embedded binding declarations can exist in a WSDL file and an external binding file targeting that WSDL, but wsimport may give an error if, upon embedding the binding declarations defined in the external binding files, the resulting WSDL document contains conflicting binding declarations.

<jaxws:bindings
        wsdlLocation="http://localhost:8080/jaxws-external-customize/addnumbers?WSDL"
        jaxws:xmlns="https://jakarta.ee/xml/ns/jaxws">
    
    ...

</jaxws:bindings>

<jaxws:bindings
        wsdlLocation="http://localhost:8080/jaxws-external-customize/addnumbers?WSDL"
        jaxws:xmlns="https://jakarta.ee/xml/ns/jaxws">
    <jaxws:bindings node="wsdl:definitions"
            xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
        <jaxws:package name="external_customize.client"/>
        
        ...
        
    </jaxws:bindings>
</jaxws:bindings>

Embedded binding declarations directly inside the WSDL follow different rules compared to the binding declarations declared in the external binding file. Here are some important facts and rules as defined in the Jakarta XML Web Services specification:

Here's an example of embedded binding declarations in the WSDL AddNumbers.wsdl from the inline-customize sample:

<wsdl:portType name="AddNumbersImpl">
    <!-- wsdl:portType customizations -->
    <jaxws:bindings xmlns:jaxws="https://jakarta.ee/xml/ns/jaxws">
        <!-- rename the generated SEI from AddNumbersImpl to MathUtil -->
        <jaxws:class name="MathUtil"/>
        ...
    </jaxws:bindings>
    <wsdl:operation name="addNumber">
        ...
    </wsdl:operation>
</wsdl:portType>

The above WSDL file excerpt shows the wsdl:portType customization. jaxws:bindings appears as extension element of portType. It customizes the class name of the generated service endpoint interface. Without this customization, or by default, the service endpoint interface class is named after the wsdl:portType name. The binding declaration jaxws:class customizes the generated class to be named MathUtil instead of AddNumberImpl.

In the following section, all the possible standard customizations and their scope is described. Global customizations can be specified under <wsdl:definitions> element and other customizations can be specified  under the node of its scope.

The global customizations are the customizations that applies to the entire scope of wsdl:definition in the wsdl referenced by the root jaxws:bindings@wsdlLocation.Following customizations have the global scopes:

<jaxws:package name="..."/>

<jaxws:enableWrapperStyle/>

<jaxws:enableAsyncMapping/>

These can appear as direct child of the Root Binding Element declarations in the external customization file. For example:

<bindings xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
        wsdlLocation="http://localhost:8080/jaxws-external-customize/addnumbers?WSDL"
        xmlns="https://jakarta.ee/xml/ns/jaxws">
    
    <package name="external_customize.client"/>
    <enableWrapperStyle>true</enableWrapperStyle>
    <enableAsyncMapping>false</enableAsyncMapping>
</bindings>

In embedded usage, the global customization can be specified under <wsdl:definitions> node of the wsdl.

By default wscompile generates WSDL artifacts in a package computed from the WSDL targetNamespace. For example, a WSDL file with the targetNamespace http://duke.example.org without any package customization will be mapped to the org.duke package. To customize the default package mapping you would use a jaxws:package customization on the wsdl:definitions node or it can directly appear inside the top level bindings element.

An important thing to note is that -p option on commandline wsimport.sh tool (package attribute on wsimport ant task), overrides the jaxws:package customization,it also overrides the schema package customization specified using jaxb schema customization.

For example:

<bindings xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
        wsdlLocation="http://localhost:8080/jaxws-external-customize/addnumbers?WSDL"
        xmlns="https://jakarta.ee/xml/ns/jaxws">
    <package name="external_customize.client">
        <javadoc>Mathutil package</javadoc>
    </package>
    
    ...
    
</bindings>

or

<bindings xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
        wsdlLocation="http://localhost:8080/jaxws-external-customize/addnumbers?WSDL"
        xmlns="https://jakarta.ee/xml/ns/jaxws">
    <bindings node="wsdl:definitions">
        <package name="external_customize.client">
            <javadoc>Mathutil package</javadoc>
        </package>
        
        ...
        
    </bindings>
    
    ...
    
</bindings>

wsimport by default applies wrapper style rules to the abstract operation defined in the wsdl:portType, and if an operation qualifies the Java method signature is generated accordingly. Wrapper style Java method generation can be disabled by using jaxws:enableWrapperStyle.

jaxws:enableWrapperStyle can appear on the toplevel bindings element (with @wsdlLocation attribute), it can also appear on the following target nodes:

For example:

<bindings xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
        wsdlLocation="http://localhost:8080/jaxws-external-customize/addnumbers?WSDL"
        xmlns="https://jakarta.ee/xml/ns/jaxws">
    
    <!-- applies to wsdl:definitions node, that would mean the entire wsdl -->
    <enableWrapperStyle>true</enableWrapperStyle>
    <!-- wsdl:portType operation customization -->
    <bindings
            node="wsdl:definitions/wsdl:portType[@name='AddNumbersImpl']/wsdl:operation[@name='addNumbers']">
        <!-- change java method name from addNumbers() to add() -->
        <enableWrapperStyle>false</enableWrapperStyle>
        
        ...
        
    </bindings>
    
    ...
    
</bindings>

In the example above the wrapper style is disabled for the addNumbers operation in AddNumbersImpl portType .This is because wsimport processes this binding in the following order: first wsdl:operation, then its parent wsdl:portType, and finally wsdl:definitions. Here wsdl:operation addNumbers has this customization disabled so this is what is applied by wsimport to generate a bare Java method signature.

A client application can use the jaxws:enableAsyncMapping binding declaration so that wsimport will generate async polling and callback operations along with the normal synchronous method when it compiles a WSDL file.

It has the same target nodes as the wrapper style binding declaration described above in section 2.2.

Example :

<bindings xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
        wsdlLocation="http://localhost:8080/jaxws-external-customize/addnumbers?WSDL"
        xmlns="https://jakarta.ee/xml/ns/jaxws">
    
    <!-- applies to wsdl:definitions node, that would mean the entire wsdl -->
    <enableAsyncMapping>false</enableAsyncMapping>
    <!-- wsdl:portType operation customization -->
    <bindings
            node="wsdl:definitions/wsdl:portType[@name='AddNumbersImpl']/wsdl:operation[@name='addNumbers']">
        <!-- change java method name from addNumbers() to add() -->
        <enableAsyncMapping>true</enableAsyncMapping>

        ...

    </bindings>

    ...

</bindings>

In the above example wsimport will generate async polling and callback methods for the addNumbers operation. In the wsdl:definition node, the async customization is disabled or false but the wsdl:operation node has it enabled or true, and so wsimport generates the async methods of the wsdl:operation addNumbers.

This is how the generated signatures look (annotations are removed from synchronous method for reading simplicity):

//synchronous method
public int addNumbers(int number1, int number2)
        throws org.duke.AddNumbersFault_Exception, java.rmi.RemoteException;

//async polling Method
public Response<AddNumbersResponse> addNumbers(int number1, int number2);

//async callback Method
public Future<?> addNumbers(int number1, int number2,
                            AsyncHandler<AddNumbersResponse>);

...

By default the value of jaxws:provider binding is false. That is, provider interface generation is disabled. In order to mark a port as provider interface this binding declaration should refer to the wsdl:port node using an XPath expression. Please note that provider binding declaration applies only when developing a server starting from a WSDL file.

The generated class for wsdl:portType, wsdl:fault, soap:headerfault, and wsdl:server can be customized using the jaxws:class binding declaration. Refer to the external binding declaration file custom-client.xml in the external-customize sample.

<!-- wsdl:portType customization -->
<bindings node="wsdl:definitions/wsdl:portType[@name='AddNumbersImpl']">
    <!-- change the generated SEI class -->
    <class name="MathUtil">
        <javadoc>Perform mathematical computations</javadoc>
    </class>
</bindings>

<!-- change the generated exception class name -->
<bindings
        node="wsdl:definitions/wsdl:portType[@name='AddNumbersImpl']/wsdl:operation[@name='addNumbers']/wsdl:fault[@name='AddNumbersException']">
    <class name="MathUtilException">
        <javadoc>Exception generated during computation</javadoc>
    </class>
</bindings>

<!-- wsdl:service customization -->
<bindings node="wsdl:definitions/wsdl:service[@name='AddNumbersService']">
    <!-- change the generated service class -->
    <class name="MathUtilService">
        <javadoc>Service to perform mathematical computations</javadoc>
    </class>
</bindings>

The jaxws:method binding declaration is used to customize the generated Java method name of a service endpoint interface and to customize the port accessor method in the generated Service class. Refer to the external binding declaration file custom-client.xml in the external-customize sample.

<!-- wsdl:portType operation customization -->
<bindings
        node="wsdl:definitions/wsdl:portType[@name='AddNumbersImpl']/wsdl:operation[@name='addNumbers']">
    <!-- change java method name from addNumbers() to add() -->
    <method name="add">
        <javadoc>Adds the numbers</javadoc>
    </method>
</bindings>

<!-- change the port accessor method -->
<bindings
        node="wsdl:definitions/wsdl:service[@name='AddNumbersService']/wsdl:port[@name='AddNumbersImplPort']">
    <method name="getMathUtil">
        <javadoc>Returns MathUtil port</javadoc>
    </method>
</bindings>

The jaxws:parameter binding declaration is used to change the parameter name of generated Java methods. It can be used to change the method parameter of a wsdl:operation in a wsdl:portType. Refer to the external binding declaration file custom-client.xml of the external-customize sample.

<bindings
        node="wsdl:definitions/wsdl:portType[@name='AddNumbersImpl']/wsdl:operation[@name='addNumbers']">
    <!-- rename method parameters-->
    <parameter
            part="definitions/message[@name='addNumbers']/part[@name='parameters']"
            element="tns:number1" name="num1"/>
    
    ...
    
</bindings>

The above sample renames the default parameter name of the Java method addNumbers from number1 to num1.

jaxws:javadoc customization can be used to specify javadoc text for java package, class(SEI, Service or Exception class) and on the methods in SEI and service class. Inorder to do it,it should appear on the corresponding wsdl nodes.

For package level javadoc:

<jaxws:package name="xs:string">
    <jaxws:javadoc>xs:string</jaxws:javadoc>
</jaxws:package>

For class level javadoc:

<jaxws:class name="xs:string">
    <jaxws:javadoc>xs:string</jaxws:javadoc>
</jaxws:class>

For method level javadoc:

<jaxws:method name="xs:string">
    <jaxws:javadoc>xs:string</jaxws:javadoc>
</jaxws:method> 

For specific samples on javadoc customization for class, refer The Service Endpoint Interface Class, The Exception Class and The Service Class customization. For javadoc customization on method refer Service Endpoint Interface Methods and Port Accessor Methods in the Service Class customization and for package level customization refer Package Customization.

An XML schema inlined inside a compiled WSDL file can be customized by using standard Jakarta XML Binding bindings. These Jakarta XML Binding bindings can live inside the schema or as the child of a jaxws:bindings element in an external binding declaration file:

<jaxws:bindings
        node="wsdl:definitions/wsdl:types/xsd:schema[@targetNamespace='http://duke.example.org']">
    <jaxb:schemaBindings>
        <jaxb:package name="fromwsdl.server"/>
    </jaxb:schemaBindings>
</jaxws:bindings>

External XML schema files imported by the WSDL file can be customized using a Jakarta XML Binding external binding declaration file:

<jxb:bindings xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:jxb="https://jakarta.ee/xml/ns/jaxb" version="3.0">
    <jxb:bindings
            schemaLocation="http://localhost:8080/jaxws-external-customize/schema1.xsd"
            node="/xsd:schema">
        <jxb:schemaBindings>
            <jxb:package name="fromjava.client"/>
        </jxb:schemaBindings>
    </jxb:bindings>
    
    ...
    
</jxb:bindings>

The external Jakarta XML Binding binding declaration file can be passed to wsimport using the -b switch. See the Jakarta XML Web Services wsimport documentation for details.

jaxws:bindings customization can be used to customize or add handlers. All that is needed is to inline a handler chain configuration conforming to Jakarta Web Services Metadata Handler Chain configuration schema inside jaxws:bindings element.

Below is a sample Jakarta XML Web Services binding declaration file with JSR 181 handler chain configuration:

<jaxws:bindings xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:jaxb="https://jakarta.ee/xml/ns/jaxb"
        xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
        wsdlLocation="http://localhost:8080/jaxws-fromwsdlhandler/addnumbers?WSDL"
        xmlns:jaxws="https://jakarta.ee/xml/ns/jaxws"
        xmlns:jee="https://jakarta.ee/xml/ns/jakartaee">
    <jaxws:bindings node="wsdl:definitions">
        <jee:handler-chain>
            <jee:handler-chain-name>LoggingHandlers
            </jee:handler-chain-name>
            
            <jee:handler>
                <jee:handler-name>Logger</jee:handler-name>
                <jee:handler-class>fromwsdlhandler.common.LoggingHandler
                </jee:handler-class>
            </jee:handler>
        </jee:handler-chain>
    </jaxws:bindings>
</jaxws:bindings>

When this customization file is passed on to wsimport tool using -b switch together with the WSDL, wsimport generates all the artifacts togather with a handler configuration file which has everything inside jaxws:bindings element enclosing the jws:handler-chain element. It also add @jakarta.jws.HandlerChain annotation in the generated SEI class. Eclipse Implementation of XML Web Services runtime uses the @HandlerChain annotation from the SEI to find the handlers that has to be added into the handle chain.

The purpose of this annotation is to mark an endpoint implementation as implementing a web service or to mark that a service endpoint interface as defining a web service interface. All endpoint implementation classes MUST have a WebService annotation and must meet the requirements of section 3.3 of the Jakarta XML Web Services specification.

@Retention(value = RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE})
public @interface WebService {
    String name() default "";

    String targetNamespace() default "";

    String serviceName() default "";

    String wsdlLocation() default "";

    String endpointInterface() default "";

    String portName() default "";
}

@WebService(name = "AddNumbers",
        targetNamespace = "http://duke.example.org")
public class AddNumbersImpl {
    /**
     * @param number1
     * @param number2
     * @return The sum
     * @throws AddNumbersException if any of the numbers to be added is
     *                             negative.
     */
    public int addNumbers(int number1, int number2) throws 
            AddNumbersException {
        if (number1 < 0 || number2 < 0) {
            throw new AddNumbersException("Negative number cant be added " +
                    "!", "Numbers: " + number1 + ", " + number2);
        }
        return number1 + number2;
    }
}

@WebService(endpointInterface = "annotations.server.AddNumbersIF")
public class AddNumbersImpl {
    /**
     * @param number1
     * @param number2
     * @return The sum
     * @throws AddNumbersException if any of the numbers to be added is 
     * negative.
     */
    public int addNumbers(int number1, int number2) throws 
            AddNumbersException {
        if (number1 < 0 || number2 < 0) {
            throw new AddNumbersException("Negative number cant be " +
                    "added!", "Numbers: " + number1 + ", " + number2);
        } return number1 + number2;
    }
}

@WebService(targetNamespace = "http://duke.example.org",
        name = "AddNumbers")
public interface AddNumbersIF extends Remote {

    public int addNumbers(int number1, int number2) throws 
            RemoteException, AddNumbersException;

}

The purpose of this annotation is to expose a method as a web service operation. The method must meet all the requirements of section 3.4 of the Jakarta XML Web Services specification.

@Retention(value = RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
public @interface WebMethod {
    String operationName() default "";

    String action() default "";

    boolean exclude() default false;
}

@WebService(targetNamespace = "http://duke.example.org",
        name = "AddNumbers")
public interface AddNumbersIF extends Remote {

    @WebMethod(operationName = "add", action = "urn:addNumbers")
    public int addNumbers(int number1, int number2) throws 
            RemoteException, AddNumbersException;

}

The purpose of this annotation is to mark a method as a web service one-way operation. The method must meet all the requirements of section 3.4.1 of the Jakarta XML Web Services spec.

There are no properties on the OneWay annotation.

@Retention(value = RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
public @interface Oneway {
}

@WebService(name = "CheckIn")
public class CheckInIF {
    
    @WebMethod
    @OneWay
    public void checkIn(String name);

}

This annotation is used to customize the mapping of a single parameter to a message part or element.

@Retention(value = RetentionPolicy.RUNTIME)
@Target({ElementType.PARAMETER})
public @interface WebParam {

    public enum Mode {
        IN,
        OUT,
        INOUT
    }

    String name() default "";

    String targetNamespace() default "";

    Mode mode() default Mode.IN;

    boolean header() default false;

    String partName() default "";
}

@WebService(targetNamespace = "http://duke.example.org",
        name = "AddNumbers")
public interface AddNumbersIF extends Remote {
 
    @WebMethod(operationName = "add", action = "urn:addNumbers")
    @WebResult(name = "return")
    public int addNumbers(@WebParam(name = "num1") int number1, 
                          @WebParam(name = "num2") int number2) throws 
            RemoteException, AddNumbersException;

}

@WebService(targetNamespace = "http://duke.example.org",
        name = "AddNumbers")
public interface AddNumbersIF extends Remote {

    @WebMethod(operationName = "add", action = "urn:addNumbers")
    @WebResult(name = "return")
    public void addNumbers(@WebParam(name = "num1") int number1, 
                           @WebParam(name = "num2") int number2, 
                           @WebParam(name = "result",
            mode = WebParam.Mode.OUT) Holder<Integer> result) throws RemoteException, AddNumbersException;


}

This annotation is used to customize the mapping of the method return value to a WSDL part or XML element.

@Retention(value = RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
public @interface WebResult {

    String name() default "return";

    String targetNamespace() default "";

    boolean header() default false;

    String partName() default "";
}

@WebService(targetNamespace = "http://duke.example.org",
        name = "AddNumbers")
public interface AddNumbersIF extends Remote {
 
    @WebMethod(operationName = "add", action = "urn:addNumbers")
    @WebResult(name = "return")
    public int addNumbers(@WebParam(name = "num1") int number1, 
                          @WebParam(name = "num2") int number2) throws 
            RemoteException, AddNumbersException;

}

This annotation is used to specified an externally defined handler chain.

@Retention(value = RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE})
public @interface HandlerChain {
    
    String file();

    @Deprecated String name() default "";

}

@WebService
@HandlerChain(file = "handlers.xml")
public class AddNumbersImpl {
    /**
     * @param number1
     * @param number2
     * @return The sum
     * @throws AddNumbersException if any of the numbers to be added is
     *                             negative.
     */
    public int addNumbers(int number1, int number2) throws 
            AddNumbersException {
        if (number1 < 0 || number2 < 0) {
            throw new AddNumbersException("Negative number cant be added " +
                    "!", "Numbers: " + number1 + ", " + number2);
        }
        return number1 + number2;
    }

}

<jws:handler-config xmlns:jws="https://jakarta.ee/xml/ns/jakartaee">
    <jws:handler-chains>
        <jws:handler-chain>
            <jws:handler>
                <jws:handler-class>fromjavahandler.common.LoggingHandler
                </jws:handler-class>
            </jws:handler>
        </jws:handler-chain>
    </jws:handler-chains>
</jws:handler-config>

Jakarta Web Services Metadata also allows you to specify a SOAPBinding annotation on an endpoint implementation or service endpoint interface. This annotation lets the developer choose between DOCUMENT\LITERAL WRAPPED, DOCUMENT\LITERAL BARE, RPC\LITERAL and RPC\ENCODED endpoints with the default being DOCUMENT\LITERAL WRAPPED. Jakarta XML Web Services 4.0 does not support RPC\ENCODED. The main difference between DOCUMENT\LITERAL BARE and DOCUMENT\LITERAL WRAPPED is that methods on a DOCUMENT\LITERAL WRAPPED endpoint can have multiple parameters bound to the body of a SOAP message, while a DOCUMENT\LITERAL BARE can only have one such parameter. The main difference between DOCUMENT\LITERAL WRAPPED and RPC\LITERAL is that a DOCUMENT\LITERAL invocation can be fully validated by a standard validating XML parser, while an RPC\LITERAL invocation cannot because of the implied wrapper element around the invocation body.

@Retention(value = RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
public @interface SOAPBinding {
    
    public enum Style {
        DOCUMENT,
        RPC,
    }

    public enum Use {
        LITERAL,
        ENCODED,
    }

    public enum ParameterStyle {
        BARE,
        WRAPPED,
    }

    Style style() default Style.DOCUMENT;

    Use use() default Use.LITERAL;

    ParameterStyle parameterStyle() default ParameterStyle.WRAPPED;

}

@WebService(targetNamespace = "http://duke.example.org",
        name = "AddNumbers")
@SOAPBinding(style = SOAPBinding.Style.RPC,
        use = SOAPBinding.Use.LITERAL)
public interface AddNumbersIF extends Remote {
 
    @WebMethod(operationName = "add", action = "urn:addNumbers")
    @WebResult(name = "return")
    public int addNumbers(@WebParam(name = "num1") int number1, 
                          @WebParam(name = "num2") int number2) throws 
            RemoteException, AddNumbersException;

}

The BindingType annotation is used to specify the binding to use for a web service endpoint implementation class. As well as specify additional features that may be enabled.

This annotation may be overriden programmatically or via deployment descriptors, depending on the platform in use.

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface BindingType {
    /**
     * A binding identifier (a URI).
     * If not specified, the default is the SOAP 1.1 / HTTP
     * binding.
     * <p/>
     * See the
     * SOAPBinding and
     * HTTPBinding
     * for the definition of the standard binding identifiers.
     *
     * @see jakarta.xml.ws.Binding
     * @see jakarta.xml.ws.soap.SOAPBinding#SOAP11HTTP_BINDING
     * @see jakarta.xml.ws.soap.SOAPBinding#SOAP12HTTP_BINDING
     * @see jakarta.xml.ws.http.HTTPBinding#HTTP_BINDING
     */
    String value() default "";

    /**
     * An array of Features to enable/disable on the specified
     * binding.
     * If not specified, features will be enabled/disabled based
     * on their own rules. Refer to the documentation of the
     * feature
     * to determine when it will be automatically enabled.
     * <p/>
     * See the
     * SOAPBinding
     * for the definition of the standard feature identifiers.
     *
     * @see jakarta.xml.ws.RespectBindingFeature
     * @see jakarta.xml.ws.soap.AddressingFeature
     * @see jakarta.xml.ws.soap.MTOMFeature
     * @since JAX-WS 2.1
     */
    Feature[] features() default {};
}

@WebService
@BindingType(value = "http://www.w3.org/2003/05/soap/bindings/HTTP/")
public class AddNumbersImpl {
    /**
     * @param number1
     * @param number2
     * @return The sum
     * @throws AddNumbersException if any of the numbers to be added is
     *                             negative.
     */
    public int addNumbers(int number1, int number2) throws 
            AddNumbersException {
        if (number1 < 0 || number2 < 0) {
            throw new AddNumbersException("Negative number cant be " + 
                    "added!", "Numbers: " + number1 +
                    ", " + number2);
        }
        return number1 + number2;
    }
}

This annotation annotates methods in the Service Endpoint Interface with the request wrapper bean to be used at runtime.

When starting from Java this annotation is used to resolve overloading conflicts in DOCUMENT\LITERAL mode. Only the className is required in this case.

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface RequestWrapper {
    /**
     * Elements local name.
     */
    public String localName() default "";

    /**
     * Elements namespace name.
     */
    public String targetNamespace() default "";

    /**
     * Request wrapper bean name.
     */
    public String className() default "";
}

public interface AddNumbersImpl {
    /**
     * @param arg1
     * @param arg0
     * @return returns int
     * @throws AddNumbersException_Exception
     */
    @WebMethod
    @WebResult(targetNamespace = "")
    @RequestWrapper(localName = "addNumbers", 
            targetNamespace = "http://server.fromjava/", 
            className = "fromjava.client.AddNumbers")
    @ResponseWrapper(localName = "addNumbersResponse",
            targetNamespace = "http://server.fromjava/", 
            className = "fromjava.client.AddNumbersResponse")
    public int addNumbers(@WebParam(name = "arg0", targetNamespace = "") 
                              int arg0, @WebParam(name = "arg1", targetNamespace = "") int arg1) throws AddNumbersException_Exception;
}

This annotation annotates methods in the Service Endpoint Interface with the response wrapper bean to be used at runtime.

When starting from Java this annotation is used to resolve overloading conflicts in DOCUMENT\LITERAL mode. Only the className is required in this case.

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ResponseWrapper {
    /**
     * Elements local name.
     */
    public String localName() default "";

    /**
     * Elements namespace name.
     */
    public String targetNamespace() default "";

    /**
     * Request wrapper bean name.
     */
    public String className() default "";
}

public interface AddNumbersImpl {
    /**
     * @param arg1
     * @param arg0
     * @return returns int
     * @throws AddNumbersException_Exception
     */
    @WebMethod
    @WebResult(targetNamespace = "")
    @RequestWrapper(localName = "addNumbers", 
            targetNamespace = "http://server.fromjava/", 
            className = "fromjava.client.AddNumbers")
    @ResponseWrapper(localName = "addNumbersResponse",
            targetNamespace = "http://server.fromjava/", 
            className = "fromjava.client.AddNumbersResponse")
    public int addNumbers(@WebParam(name = "arg0", targetNamespace = "") 
                              int arg0, @WebParam(name = "arg1", targetNamespace = "") int arg1) throws AddNumbersException_Exception;
}

This annotation allows the Provider developer to indicate whether a Provider implementation wishes to work with entire protocol messages or just with protocol message payloads.

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
@Documented
public @interface ServiceMode {
    /**
     * Service mode. <code>PAYLOAD</code> indicates that the 
     * <code>Provider</code> implementation
     * wishes to work with protocol message payloads only. 
     * <code>MESSAGE</code> indicates
     * that the <code>Provider</code> implementation wishes to work with 
     * entire protocol
     * messages.
     */
    public Service.Mode value() default Service.Mode.PAYLOAD;
}

@ServiceMode(value = Service.Mode.PAYLOAD)
public class AddNumbersImpl implements Provider<Source> {
    public Source invoke(Source source) throws RemoteException {
        try {
            DOMResult dom = new DOMResult();
            Transformer trans = TransformerFactory.newInstance()
                    .newTransformer();
            trans.transform(source, dom);
            Node node = dom.getNode();
            Node root = node.getFirstChild();
            Node first = root.getFirstChild();
            int number1 = Integer.decode(first.getFirstChild()
                    .getNodeValue());
            Node second = first.getNextSibling();
            int number2 = Integer.decode(second.getFirstChild()
                    .getNodeValue());
            return sendSource(number1, number2);
        } catch (Exception e) {
            e.printStackTrace();
            throw new RemoteException("Error in provider endpoint");
        }
    }

    private Source sendSource(int number1, int number2) {
        int sum = number1 + number2;
        String body = "<ns:addNumbersResponse xmlns:ns =\"http://duke" +
                ".example.org\"><return>" + sum +
                "</return></ns:addNumbersResponse>";
        Source source = new StreamSource(new ByteArrayInputStream(body.getBytes()));
        return source;
    }
}

Used to annotate the getPortName() methods of a generated service interface.

The information specified in this annotation is sufficient to uniquely identify a wsdl:port element inside a wsdl:service. The latter is determined based on the value of the WebServiceClient annotation on the generated service interface itself.

/**
 * Used to annotate the <code>get<em>PortName</em>()</code>
 * methods of a generated service interface.
 * <p/>
 * <p>The information specified in this annotation is sufficient
 * to uniquely identify a <code>wsdl:port</code> element
 * inside a <code>wsdl:service</code>. The latter is
 * determined based on the value of the <code>WebServiceClient</code>
 * annotation on the generated service interface itself.
 *
 * @see jakarta.xml.ws.WebServiceClient
 * @since JAX-WS 2.0
 */
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface WebEndpoint {
    /**
     * The local name of the endpoint.
     */
    String name() default "";
}

@WebServiceClient(name = "AddNumbersImplService", 
        targetNamespace = "http://server.fromjava/", 
        wsdlLocation = "http://localhost:8080/jaxws-fromjava/addnumbers" +
                "?wsdl")
public class AddNumbersImplService extends Service {
    private final static URL WSDL_LOCATION;
    private final static QName ADDNUMBERSIMPLSERVICE = new QName
            ("http://server.fromjava/", "AddNumbersImplService");
    private final static QName ADDNUMBERSIMPLPORT = new QName
            ("http://server.fromjava/", "AddNumbersImplPort");

    static {
        URL url = null;
        try {
            url = new URL("http://localhost:8080/jaxws-fromjava" +
                    "/addnumbers?wsdl");
        } catch (MalformedURLException e) {
            e.printStackTrace();
        }
        WSDL_LOCATION = url;
    }

    public AddNumbersImplService(URL wsdlLocation, QName serviceName) {
        super(wsdlLocation, serviceName);
    }

    public AddNumbersImplService() {
        super(WSDL_LOCATION, ADDNUMBERSIMPLSERVICE);
    }

    /**
     * @return returns AddNumbersImpl
     */
    @WebEndpoint(name = "AddNumbersImplPort")
    public AddNumbersImpl getAddNumbersImplPort() {
        return (AddNumbersImpl) super.getPort(ADDNUMBERSIMPLPORT, AddNumbersImpl.class);
    }
}

This annotation is generated by the Jakarta XML Web Services tools into service specific exception classes generated from a WSDL to customize the local and namespace name of the fault element and the name of the fault bean and to mark the service specific exception as one generated from WSDL. The reason that the Jakarta XML Web Services needs to know if a service specific exception is generated from a WSDL or not is because these exceptions will already have a fault bean generated for them. The name of this fault bean is not the same name as the one generated from a Java service specific exception class. For more information on this topic, please refer to section 3.6 of the Jakarta XML Web Services specification.

/**
 * Used to annotate service specific exception classes to customize
 * to the local and namespace name of the fault element and the name
 * of the fault bean.
 *
 * @since JAX-WS 2.0
 */
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface WebFault {
    /**
     * Element's local name.
     */
    public String name() default "";

    /**
     * Element's namespace name.
     */
    public String targetNamespace() default "";

    /**
     * Fault bean name.
     */
    public String faultBean() default "";


    /**
     * wsdl:Message's name. Default name is the exception's class name.
     *
     * @since JAX-WS 2.2
     */
    public String messageName() default "";
}

@jakarta.xml.ws.WebFault(name = "AddNumbersException",
        targetNamespace = "http://server.fromjava/jaxws")
public class AddNumbersException_Exception extends Exception {
    private fromjava.client.AddNumbersException faultInfo;

    public AddNumbersException_Exception(String message, 
                                         fromjava.client.AddNumbersException faultInfo) {
        super(message);
        this.faultInfo = faultInfo;
    }

    public AddNumbersException_Exception(String message, 
                                         fromjava.client
                                                 .AddNumbersException faultInfo, Throwable cause) {
        super(message, cause);
        this.faultInfo = faultInfo;
    }

    public fromjava.client.AddNumbersException getFaultInfo() {
        return faultInfo;
    }

}

The information specified in this annotation is sufficient to uniquely identify a wsdl:service element inside a WSDL document. This wsdl:service element represents the Web service for which the generated service interface provides a client view.

/**
 * Used to annotate a generated service interface.
 * <p/>
 * <p>The information specified in this annotation is sufficient
 * to uniquely identify a <code>wsdl:service</code>
 * element inside a WSDL document. This <code>wsdl:service</code>
 * element represents the Web service for which the generated
 * service interface provides a client view.
 *
 * @since JAX-WS 2.0
 */
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface WebServiceClient {
    /**
     * The local name of the Web service.
     */
    String name() default "";

    /**
     * The namespace for the Web service.
     */
    String targetNamespace() default "";

    /**
     * The location of the WSDL document for the service (a URL).
     */
    String wsdlLocation() default "";
}

@WebServiceClient(name = "AddNumbersImplService", 
        targetNamespace = "http://server.fromjava/", 
        wsdlLocation = "http://localhost:8080/jaxws-fromjava/addnumbers" +
                "?wsdl")
public class AddNumbersImplService extends Service {
    private final static URL WSDL_LOCATION;
    private final static QName ADDNUMBERSIMPLSERVICE = new QName
            ("http://server.fromjava/", "AddNumbersImplService");
    private final static QName ADDNUMBERSIMPLPORT = new QName
            ("http://server.fromjava/", "AddNumbersImplPort");

    static {
        URL url = null;
        try {
            url = new URL("http://localhost:8080/jaxws-fromjava" +
                    "/addnumbers?wsdl");
        } catch (MalformedURLException e) {
            e.printStackTrace();
        }
        WSDL_LOCATION = url;
    }

    public AddNumbersImplService(URL wsdlLocation, QName serviceName) {
        super(wsdlLocation, serviceName);
    }

    public AddNumbersImplService() {
        super(WSDL_LOCATION, ADDNUMBERSIMPLSERVICE);
    }

    /**
     * @return returns AddNumbersImpl
     */
    @WebEndpoint(name = "AddNumbersImplPort")
    public AddNumbersImpl getAddNumbersImplPort() {
        return (AddNumbersImpl) super.getPort(ADDNUMBERSIMPLPORT, AddNumbersImpl.class);
    }
}

Annotation used to annotate a Provider implementation class.

/**
 * Used to annotate a Provider implementation class.
 *
 * @since JAX-WS 2.0
 * @see jakarta.xml.ws.Provider
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface WebServiceProvider {
    /**
     * Location of the WSDL description for the service.
     */
    String wsdlLocation() default "";    
    
    /**
     * Service name.
     */
    String serviceName() default "";
    
    /**
     * Target namespace for the service
     */
    String targetNamespace() default "";

    /**
     * Port name.
     */
    String portName() default "";
}

@ServiceMode(value = Service.Mode.PAYLOAD)
@WebServiceProvider(wsdlLocation = "WEB-INF/wsdl/AddNumbers.wsdl")
public class AddNumbersImpl implements Provider {
    public Source invoke(Source source) {
        try {
            DOMResult dom = new DOMResult();
            Transformer trans = TransformerFactory.newInstance()
                    .newTransformer();
            trans.transform(source, dom);
            Node node = dom.getNode();
            Node root = node.getFirstChild();
            Node first = root.getFirstChild();
            int number1 = Integer.decode(first.getFirstChild()
                    .getNodeValue());
            Node second = first.getNextSibling();
            int number2 = Integer.decode(second.getFirstChild()
                    .getNodeValue());
            return sendSource(number1, number2);
        } catch (Exception e) {
            e.printStackTrace();
            throw new RuntimeException("Error in provider endpoint", e);
        }
    }

    private Source sendSource(int number1, int number2) {
        int sum = number1 + number2;
        String body = "" + sum + "";
        Source source = new StreamSource(new ByteArrayInputStream(body.getBytes()));
        return source;
    }
}

The WebServiceRef annotation is used to define a reference to a web service and (optionally) an injection target for it. Web service references are resources in the Jakarta EE sense.

/**
 * The <code>WebServiceRef</code> annotation is used to
 * define a reference to a web service and
 * (optionally) an injection target for it.
 * It can be used to inject both service and proxy
 * instances. These injected references are not thread safe.
 * If the references are accessed by multiple threads,
 * usual synchronization techinques can be used to
 * support multiple threads.
 * <p/>
 * Web service references are resources in the Jakarta EE sense.
 * The annotations (for example, {@link Addressing}) annotated with
 * meta-annotation {@link WebServiceFeatureAnnotation}
 * can be used in conjunction with <code>WebServiceRef</code>.
 * The created reference MUST be configured with annotation's web service
 * feature.
 * <p/>
 * If a Jakarta XML Web Services implementation encounters an unsupported or unrecognized
 * annotation annotated with the <code>WebServiceFeatureAnnotation</code>
 * that is specified with <code>WebServiceRef</code>, 
 * an ERROR MUST be given.
 *
 * @see jakarta.annotation.Resource
 * @see WebServiceFeatureAnnotation
 * @since JAX-WS 2.0
 */
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface WebServiceRef {
    /**
     * The JNDI name of the resource.  For field annotations,
     * the default is the field name.  For method annotations,
     * the default is the JavaBeans property name corresponding
     * to the method.  For class annotations, there is no default
     * and this MUST be specified.
     * <p/>
     * The JNDI name can be absolute(with any logical namespace) or 
     * relative
     * to JNDI <code>java:comp/env</code> namespace.
     */
    String name() default "";

    /**
     * The Java type of the resource.  For field annotations,
     * the default is the type of the field.  For method annotations,
     * the default is the type of the JavaBeans property.
     * For class annotations, there is no default and this MUST be
     * specified.
     */
    Class<?> type() default Object.class;

    /**
     * A product specific name that this resource should be mapped to.
     * The name of this resource, as defined by the <code>name</code>
     * element or defaulted, is a name that is local to the application
     * component using the resource.  (When a relative JNDI name
     * is specified, then it's a name in the JNDI
     * <code>java:comp/env</code> namespace.)  Many application servers
     * provide a way to map these local names to names of resources
     * known to the application server.  This mapped name is often a
     * <i>global</i> JNDI name, but may be a name of any form.
     * <p/>
     * Application servers are not required to support any particular
     * form or type of mapped name, nor the ability to use mapped names.
     * The mapped name is product-dependent and often 
     * installation-dependent.
     * No use of a mapped name is portable.
     */
    String mappedName() default "";

    /**
     * The service class, alwiays a type extending
     * <code>jakarta.xml.ws.Service</code>. This element MUST be specified
     * whenever the type of the reference is a service endpoint interface.
     */
    // 2.1 has Class value() default Object.class;
    // Fixing this raw Class type correctly in 2.2 API. This shouldn't 
    // cause
    // any compatibility issues for applications.
    Class<? extends Service> value() default Service.class;

    /**
     * A URL pointing to the WSDL document for the web service.
     * If not specified, the WSDL location specified by annotations
     * on the resource type is used instead.
     */
    String wsdlLocation() default "";

    /**
     * A portable JNDI lookup name that resolves to the target
     * web service reference.
     *
     * @since JAX-WS 2.2
     */
    String lookup() default "";

}

The Action annotation allows explicit association of Action message addressing property with input, output, and fault messages of the mapped WSDL operation.

This annotation can be specified on each method of a service endpoint interface or implementation. For such a method, the mapped operation in the generated WSDL contains explicit wsaw:Action attribute on the WSDL input, output and fault messages of the WSDL operation based upon which attributes of the Action annotation have been specified.

/**
 * The <code>Action</code> annotation allows explicit association of a
 * WS-Addressing <code>Action</code> message addressing property with
 * <code>input</code>, <code>output</code>, and
 * <code>fault</code> messages of the mapped WSDL operation.
 * <p/>
 * This annotation can be specified on each method of a service endpoint 
 * interface.
 * For such a method, the mapped operation in the generated WSDL's
 * <code>wsam:Action</code> attribute on the WSDL <code>input</code>,
 * <code>output</code> and <code>fault</code> messages of the WSDL 
 * <code>operation</code>
 * is based upon which attributes of the <code>Action</code> annotation 
 * have been specified.
 * For the exact computation of <code>wsam:Action</code> values for the 
 * messages, refer
 * to the algorithm in the Jakarta XML Web Services specification.
 *
 * @see FaultAction
 * @since JAX-WS 2.1
 */

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Action {
    /**
     * Explicit value of the WS-Addressing <code>Action</code> message 
     * addressing property for the <code>input</code>
     * message of the operation.
     */
    String input() default "";

    /**
     * Explicit value of the WS-Addressing <code>Action</code> message 
     * addressing property for the <code>output</code>
     * message of the operation.
     */
    String output() default "";

    /**
     * Explicit value of the WS-Addressing <code>Action</code> message 
     * addressing property for the <code>fault</code>
     * message(s) of the operation. Each exception that is mapped to a 
     * fault and requires an explicit WS-Addressing
     * <code>Action</code> message addressing property, 
     * needs to be specified as a value in this property
     * using {@link FaultAction} annotation.
     */
    FaultAction[] fault() default {};
}

@jakarta.jws.WebService
public class AddNumbersImpl {
    @jakarta.xml.ws.Action(
            input = "http://example.com/inputAction",
            output = "http://example.com/outputAction")
    public int addNumbers(int number1, int number2) {
        return number1 + number2;
    }
}

<definitions targetNamespace="http://example.com/numbers" ...>

    ...
    
    <portType name="AddNumbersPortType">
        <operation name="AddNumbers">
            <input message="tns:AddNumbersInput" name="Parameters"
                    wsaw:Action="http://example.com/inputAction"/>
            <output message="tns:AddNumbersOutput" name="Result"
                    wsaw:Action="http://example.com/outputAction"/>
        </operation>
    </portType>

    ...

</definitions>

@jakarta.jws.WebService
public class AddNumbersImpl {
    @jakarta.xml.ws.Action(input = "http://example.com/inputAction")
    public int addNumbers(int number1, int number2) {
        return number1 + number2;
    }
}

<definitions targetNamespace="http://example.com/numbers" ...>

    ...
    
    <portType name="AddNumbersPortType">
        <operation name="AddNumbers">
            <input message="tns:AddNumbersInput" name="Parameters"
                    wsaw:Action="http://example.com/inputAction"/>
            <output message="tns:AddNumbersOutput" name="Result"/>
        </operation>
    </portType>
    
    ...
    
</definitions>

The FaultAction annotation is used inside an Action annotation to allow an explicit association of Action message addressing property with the fault messages of the WSDL operation mapped from the exception class.

The fault message in the generated WSDL operation mapped for className class contains explicit wsaw:Action attribute.

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface FaultAction {
    /**
     * Name of the exception class
     */
    Class<? extends Exception> className();

    /**
     * Value of WS-Addressing <code>Action</code> message addressing 
     * property for the exception
     */
    String value() default "";
}

@jakarta.jws.WebService
public class AddNumbersImpl {
    @jakarta.xml.ws.Action(
            input = "http://example.com/inputAction",
            output = "http://example.com/outputAction",
            fault = {
                    @jakarta.xml.ws.FaultAction(className =
                            AddNumbersException.class,
                            value = "http://example.com/faultAction")})
    public int addNumbers(int number1, int number2) throws 
            AddNumbersException {
        return number1 + number2;
    }
}

<definitions targetNamespace="http://example.com/numbers" ...>

    ...
    
    <portType name="AddNumbersPortType">
        <operation name="AddNumbers">
            <input message="tns:AddNumbersInput" name="Parameters"
                    wsaw:Action="http://example.com/inputAction"/>
            <output message="tns:AddNumbersOutput" name="Result"
                    wsaw:Action="http://example.com/outputAction"/>
            <fault message="tns:AddNumbersException"
                    name="AddNumbersException"
                    wsaw:Action="http://example.com/faultAction"/>
        </operation>
    </portType>
    
    ...
    
</definitions>

@jakarta.jws.WebService
public class AddNumbersImpl {
    @jakarta.xml.ws.Action(
            fault = {@jakarta.xml.ws.FaultAction(className =
                    AddNumbersException.class,
                    value = "http://example.com/faultAction")})
    public int addNumbers(int number1, int number2) throws 
            AddNumbersException {
        return number1 + number2;
    }
}

<definitions targetNamespace="http://example.com/numbers" ...>
    
    ...
    
    <portType name="AddNumbersPortType">
        <operation name="AddNumbers">
            <input message="tns:AddNumbersInput" name="Parameters"/>
            <output message="tns:AddNumbersOutput" name="Result"/>
            <fault message="tns:addNumbersFault" name="InvalidNumbers"
                    wsa:Action="http://example.com/addnumbers/fault"/>
        </operation>
    </portType>
    
    ...
    
</definitions>

@jakarta.jws.WebService
public class AddNumbersImpl {
    @jakarta.xml.ws.Action(
            fault = {@jakarta.xml.ws.FaultAction(className =
                    AddNumbersException.class,
                    value = "http://example.com/addFaultAction"),

                    @jakarta.xml.ws.FaultAction(className =
                            TooBigNumbersException.class,
                            value = "http://example" +
                                    ".com/toobigFaultAction")})
    public int addNumbers(int number1, int number2) throws AddNumbersException, TooBigNumbersException {
        return number1 + number2;
    }
}

<definitions targetNamespace="http://example.com/numbers" ...>
    
    ...
    
    <portType name="AddNumbersPortType">
        <operation name="AddNumbers">
            <input message="tns:AddNumbersInput" name="Parameters"/>
            <output message="tns:AddNumbersOutput" name="Result"/>
            <fault message="tns:addNumbersFault" name="AddNumbersException"
                    wsa:Action="http://example.com/addnumbers/fault"/>
            <fault message="tns:tooBigNumbersFault"
                    name="TooBigNumbersException"
                    wsa:Action="http://example.com/toobigFaultAction"/>
        </operation>
    </portType>
    
    ...
    
</definitions>

This annotation is used to map a top level class to a global element in the XML schema used by the WSDL of the web service.

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE})
public @interface XmlRootElement {
    /**
     * namespace name of the XML element.
     * <p/>
     * If the value is "##default", then the XML namespace name is
     * derived
     * from the package of the class ( {@link XmlSchema} ). If the
     * package is unnamed, then the XML namespace is the default
     * empty
     * namespace.
     */
    String namespace() default "##default";

    /**
     * local name of the XML element.
     * <p/>
     * If the value is "##default", then the name is derived from
     * the
     * class name.
     */
    String name() default "##default";

}

@XmlRootElement(name = "addNumbers", namespace = "http://server.fromjava/")
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "addNumbers", namespace = "http://server.fromjava/", 
        propOrder = {"arg0", "arg1"})
public class AddNumbers {

    @XmlElement(name = "arg0", namespace = "")
    private int arg0;
    @XmlElement(name = "arg1", namespace = "")
    private int arg1;

    public int getArg0() {
        return this.arg0;
    }

    public void setArg0(int arg0) {
        this.arg0 = arg0;
    }

    public int getArg1() {
        return this.arg1;
    }

    public void setArg1(int arg1) {
        this.arg1 = arg1;
    }
}

This annotation is used to specify whether fields or properties are serialized by default.

@Inherited
@Retention(RUNTIME)
@Target({PACKAGE, TYPE})
public @interface XmlAccessorType {

    /**
     * Specifies whether fields or properties are serialized.
     *
     * @see XmlAccessType
     */
    XmlAccessType value() default XmlAccessType.PUBLIC_MEMBER;
}

/**
 * Used by XmlAccessorType to control serialization of fields or
 * properties.
 */
public enum XmlAccessType {
    /**
     * Every getter/setter pair in a Jakarta XML Binding-bound class will be
     * automatically
     * bound to XML, unless annotated by {@link XmlTransient}.
     * <p/>
     * Fields are bound to XML only when they are explicitly
     * annotated
     * by some of the Jakarta XML Binding annotations.
     */
    PROPERTY,
    /**
     * Every non static, non transient field in a Jakarta XML Binding-bound class
     * will be automatically
     * bound to XML, unless annotated by {@link XmlTransient}.
     * <p/>
     * Getter/setter pairs are bound to XML only when they are
     * explicitly annotated
     * by some of the Jakarta XML Binding annotations.
     */
    FIELD,
    /**
     * Every public getter/setter pair and every public field will
     * be
     * automatically bound to XML, unless annotated by {@link
     * XmlTransient}.
     * <p/>
     * Fields or getter/setter pairs that are private, protected,
     * or
     * defaulted to package-only access are bound to XML only when
     * they are
     * explicitly annotated by the appropriate Jakarta XML Binding annotations.
     */
    PUBLIC_MEMBER,
    /**
     * None of the fields or properties is bound to XML unless they
     * are specifically  annotated with some of the Jakarta XML Binding
     * annotations.
     */
    NONE
}

@XmlRootElement(name = "addNumbers", namespace = "http://server.fromjava/")
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "addNumbers", namespace = "http://server.fromjava/", 
        propOrder = {"arg0", "arg1"})
public class AddNumbers {

    @XmlElement(name = "arg0", namespace = "")
    private int arg0;
    @XmlElement(name = "arg1", namespace = "")
    private int arg1;

    public int getArg0() {
        return this.arg0;
    }

    public void setArg0(int arg0) {
        this.arg0 = arg0;
    }

    public int getArg1() {
        return this.arg1;
    }

    public void setArg1(int arg1) {
        this.arg1 = arg1;
    }
}

This annotation is used to map a value class to an XML Schema type. A value class is a data container for values represented by properties and fields. A schema type is a data container for values represented by schema components within a schema type's content model (e.g. Model groups, attributes etc).

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE})
public @interface XmlType {
    /**
     * Name of the XML Schema type which the class is mapped.
     */
    String name() default "##default";

    /**
     * Specifies the order for XML Schema elements when class is
     * mapped to a XML Schema complex type.
     * <p/>
     * <p> Refer to the table for how the propOrder affects the
     * mapping of class </p>
     * <p/>
     * <p> The propOrder is a list of names of JavaBean properties in
     * the class. Each name in the list is the name of a Java
     * identifier of the JavaBean property. The order in which
     * JavaBean properties are listed is the order of XML Schema
     * elements to which the JavaBean properties are mapped. </p>
     * <p> All of the JavaBean properties being mapped to XML Schema
     * elements
     * must be listed.
     * <p> A JavaBean property or field listed in propOrder must not
     * be transient or annotated with <tt>@XmlTransient</tt>.
     * <p> The default ordering of JavaBean properties is determined
     * by @{@link XmlAccessorOrder}.
     */
    String[] propOrder() default {""};

    /**
     * Name of the target namespace of the XML Schema type. By
     * default, this is the target namespace to which the package
     * containing the class is mapped.
     */
    String namespace() default "##default";

    /**
     * Class containing a no-arg factory method for creating an
     * instance of this class. The default is this class.
     * <p/>
     * <p>If <tt>factoryClass</tt> is DEFAULT.class and
     * <tt>factoryMethod</tt> is "", then there is no static factory
     * method.
     * <p/>
     * <p>If <tt>factoryClass</tt> is DEFAULT.class and
     * <tt>factoryMethod</tt> is not "", then
     * <tt>factoryMethod</tt> is the name of a static factory method
     * in this class.
     * <p/>
     * <p>If <tt>factoryClass</tt> is not DEFAULT.class, then
     * <tt>factoryMethod</tt> must not be "" and must be the name of
     * a static factory method specified in <tt>factoryClass</tt>.
     */
    Class factoryClass() default DEFAULT.class;

    /**
     * Used in {@link XmlType#factoryClass()} to
     * signal that either factory mehod is not used or
     * that it's in the class with this {@link XmlType} itself.
     */
    static final class DEFAULT {
    }

    /**
     * Name of a no-arg factory method in the class specified in
     * <tt>factoryClass</tt> factoryClass().
     */
    String factoryMethod() default "";
}

@XmlRootElement(name = "addNumbers", namespace = "http://server.fromjava/")
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "addNumbers", namespace = "http://server.fromjava/", 
        propOrder = {"arg0", "arg1"})
public class AddNumbers {

    @XmlElement(name = "arg0", namespace = "")
    private int arg0;
    @XmlElement(name = "arg1", namespace = "")
    private int arg1;

    public int getArg0() {
        return this.arg0;
    }

    public void setArg0(int arg0) {
        this.arg0 = arg0;
    }

    public int getArg1() {
        return this.arg1;
    }

    public void setArg1(int arg1) {
        this.arg1 = arg1;
    }
}

This annotation is used to map a property contained in a class to a local element in the XML Schema complex type to which the containing class is mapped.

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
public @interface XmlElement {
    /**
     * Name of the XML Schema element.
     * <p> If the value is "##default", then element name is derived from
     * the
     * JavaBean property name.
     */
    String name() default "##default";

    /**
     * Customize the element declaration to be nillable.
     * <p>If nillable() is true, then the JavaBean property is
     * mapped to a XML Schema nillable element declaration.
     */
    boolean nillable() default false;

    /**
     * Customize the element declaration to be required.
     * <p>If required() is true, then Javabean property is mapped to
     * an XML schema element declaration with minOccurs="1".
     * maxOccurs is "1" for a single valued property and "unbounded"
     * for a multivalued property.
     * <p>If required() is false, then the Javabean property is mapped
     * to XML Schema element declaration with minOccurs="0".
     * maxOccurs is "1" for a single valued property and "unbounded"
     * for a multivalued property.
     */

    boolean required() default false;

    /**
     * XML target namespace of the XML Schema element.
     * <p/>
     * If the value is "##default", then the namespace is determined
     * as follows:
     * <ol>
     * <li>
     * If the enclosing package has {@link XmlSchema} annotation,
     * and its {@link XmlSchema#elementFormDefault() elementFormDefault}
     * is {@link XmlNsForm#QUALIFIED QUALIFIED}, then the namespace of
     * the enclosing class.
     * <p/>
     * <li>
     * Otherwise &#39;&#39; (which produces unqualified element in the 
     * default
     * namespace.
     * </ol>
     */
    String namespace() default "##default";

    /**
     * Default value of this element.
     * <p/>
     * <p/>
     * The <pre>'\u0000'</pre> value specified as a default of this 
     * annotation element
     * is used as a poor-man's substitute for null to allow implementations
     * to recognize the 'no default value' state.
     */
    String defaultValue() default "\u0000";

    /**
     * The Java class being referenced.
     */
    Class type() default DEFAULT.class;

    /**
     * Used in {@link XmlElement#type()} to
     * signal that the type be inferred from the signature
     * of the property.
     */
    static final class DEFAULT {
    }
}

@XmlRootElement(name = "addNumbers", namespace = "http://server.fromjava/")
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "addNumbers", namespace = "http://server.fromjava/", 
        propOrder = {"arg0", "arg1"})
public class AddNumbers {

    @XmlElement(name = "arg0", namespace = "")
    private int arg0;
    @XmlElement(name = "arg1", namespace = "")
    private int arg1;

    public int getArg0() {
        return this.arg0;
    }

    public void setArg0(int arg0) {
        this.arg0 = arg0;
    }

    public int getArg1() {
        return this.arg1;
    }

    public void setArg1(int arg1) {
        this.arg1 = arg1;
    }
}

Instructs Jakarta XML Binding to also bind other classes when binding this class.

/**
 * Instructs Jakarta XML Binding to also bind other classes when binding this class.
 * <p/>
 * Java makes it impractical/impossible to list all sub-classes of
 * a given class. This often gets in a way of Jakarta XML Binding users, as it Jakarta XML Binding
 * cannot automatically list up the classes that need to be known
 * to {@link JAXBContext}.
 * <p/>
 * For example, with the following class definitions:
 * <p/>
 * <pre>
 * class Animal {}
 * class Dog extends Animal {}
 * class Cat extends Animal {}
 * </pre>
 * <p/>
 * The user would be required to create {@link JAXBContext} as
 * <tt>JAXBContext.newInstance(Dog.class,Cat.class)</tt>
 * (<tt>Animal</tt> will be automatically picked up since <tt>Dog</tt>
 * and <tt>Cat</tt> refers to it.)
 * <p/>
 * {@link XmlSeeAlso} annotation would allow you to write:
 * <pre>
 * &#64;XmlSeeAlso({Dog.class,Cat.class})
 * class Animal {}
 * class Dog extends Animal {}
 * class Cat extends Animal {}
 * </pre>
 * <p/>
 * This would allow you to do <tt>JAXBContext.newInstance(Animal.class)
 * </tt>.
 * By the help of this annotation, Jakarta XML Binding implementations will be able to
 * correctly bind <tt>Dog</tt> and <tt>Cat</tt>.
 *
 * @author Kohsuke Kawaguchi
 * @since JAXB2.1
 */
@Target({ElementType.TYPE})
@Retention(RUNTIME)
public @interface XmlSeeAlso {
    Class[] value();
}

This annotation is used to mark a WebServiceContext resource that is needed by a web service. It is applied to a field or a method for Jakarta XML Web Services endpoints. The container will inject an instance of the WebServiceContext resource into the endpoint implementation when it is initialized.

@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Resource {

    // ...

    /**
     * The Java type of the resource.  For field annotations,
     * the default is the type of the field.  For method annotations,
     * the default is the type of the JavaBeans property.
     * For class annotations, there is no default and this must be
     * specified.
     */
    Class type() default java.lang.Object.class;
}

@WebService
public class HelloImpl {
    @Resource
    private WebServiceContext context;

    public String echoHello(String name) {
        // ...
    }
}

This annotation is used on a method that needs to be executed after dependency injection is done to perform any initialization. This method MUST be invoked before the class is put into service.

/**
 * The PostConstruct annotation is used on a method that needs to be 
 * executed
 * after dependency injection is done to perform any initialization. This
 * method MUST be invoked before the class is put into service. This
 * annotation MUST be supported on all classes that support dependency
 * injection. The method annotated with PostConstruct MUST be invoked even
 * if the class does not request any resources to be injected. Only one
 * method can be annotated with this annotation. The method on which the
 * PostConstruct annotation is applied MUST fulfill all of the following
 * criteria -
 * - The method MUST NOT have any parameters except in the case of EJB
 * interceptors   in which case it takes an InvocationC	ontext object as
 * defined by the EJB   specification.
 * - The return type of the method MUST be void.
 * - The method MUST NOT throw a checked exception.
 * - The method on which PostConstruct is applied MAY be public, protected,
 * package private or private.
 * - The method MUST NOT be static except for the application client.
 * - The method MAY be final.
 * - If the method throws an unchecked exception the class MUST NOT be 
 * put into
 * service except in the case of EJBs where the EJB can handle exceptions
 * and
 * even   recover from them.
 *
 * @see jakarta.annotation.PreDestroy
 * @see jakarta.annotation.Resource
 * @since Common Annotations 1.0
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface PostConstruct {
}

@WebService
public class HelloImpl {
    @PostConstruct
    private void init() {
        // ...
    }

    public String echoHello(String name) {
        // ...
    }
}

The PreDestroy annotation is used on methods as a callback notification to signal that the instance is in the process of being removed by the container. The method annotated with PreDestroy is typically used to release resources that it has been holding.

/**
 * The PreDestroy annotation is used on methods as a callback 
 * notification to
 * signal that the instance is in the process of being removed by the
 * container. The method annotated with PreDestroy is typically used to
 * release resources that it has been holding. This annotation MUST be
 * supported by all container managed objects that support PostConstruct
 * except the application client container in Jakarta EE. The method on 
 * which
 * the PreDestroy annotation is applied MUST fulfill all of the following
 * criteria -
 * - The method MUST NOT have any parameters except in the case of EJB
 * interceptors in which case it takes an InvocationContext object as 
 * defined
 * by the EJB specification.
 * - The return type of the method MUST be void.
 * - The method MUST NOT throw a checked exception.
 * - The method on which PreDestroy is applied MAY be public, protected,
 * package private or private.
 * - The method MUST NOT be static.
 * - The method MAY be final.
 * - If the method throws an unchecked exception it is ignored except in 
 * the
 * case of EJBs where the EJB can handle exceptions.
 *
 * @see jakarta.annotation.PostConstruct
 * @see jakarta.annotation.Resource
 * @since Common Annotations 1.0
 */

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface PreDestroy {
}

@WebService
public class HelloImpl {
    public String echoHello(String name) {
        // ...
    }

    @PreDestroy
    private void release() {
        // ...
    }
}

This section describes how a message can be sent to a Web service endpoint in transport neutral manner.

POST /fabrikam/Purchasing HTTP 1.1/POST                    
Host: example.com
SOAPAction: http://example.com/fabrikam/SubmitPO

<S:Envelope                                                
        xmlns:S="http://www.w3.org/2003/05/soap-envelope"
        xmlns:wombat="http://wombat.org/">
    <S:Header>
        <wombat:MessageID>
            uuid:e197db59-0982-4c9c-9702-4234d204f7f4
        </wombat:MessageID>
    </S:Header>
    <S:Body>
        ...
    </S:Body>
</S:Envelope>

Also in the above message, there is no standard header to establish the identity of a message. In this case, MessageID header defined in the namespace URI bound to wombat prefix is used but is application specific and is thus not re-usable.

WS-Addressing introduce Message Addressing Properties that collectively augment a message to normalize this information.

POST /fabrikam/Purchasing HTTP 1.1/POST                    
Host: example.com
SOAPAction: http://example.com/fabrikam/SubmitPO

<S:Envelope                                                
        xmlns:S="http://www.w3.org/2003/05/soap-envelope"
        xmlns:wsa="http://www.w3.org/2005/08/addressing/">
    <S:Header>
        <wsa:MessageID>                                    
            uuid:e197db59-0982-4c9c-9702-4234d204f7f4
        </wsa:MessageID>
        <wsa:To>
            http://example.com/fabrikam/Purchasing
        </wsa:To>
        <wsa:Action>
            http://example.com/fabrikam/SubmitPO
        </wsa:Action>
    </S:Header>
    <S:Body>
        ...
    </S:Body>
</S:Envelope>

<wsa:To>
    mailto:purchasing@example.com
</wsa:To>

Web services are usually stateless, i.e. the service endpoint receives a request and responds back without saving any processing state in between different requests. However making Web services stateful enables to share multiple instances of service endpoints. For example, consider a stateful Bank Web service. The client (say bank customer) can obtain a bank EPR, with relevant state information stored as reference parameters, and invoke a method on that EPR to do a series of banking operations. On the service endpoint, whenever a request is received, the reference parameters from the EPR are available as first-class SOAP headers allowing the endpoint to restore the state.

Eclipse Implementation of XML Web Services 4.0.0 enables stateful Web services to be annotated with com.sun.xml.ws.developer.Stateful annotation.

WS-Addressing defines standard Message Addressing Properties (MAPs) to support simple and complex message patterns. The SOAP Binding defines a mapping of these MAPs to SOAP headers and convey end-to-end message characteristics including addressing for source and destination endpoints as well as message identity. For example destination MAP represents an absolute IRI representing the address of the intended receiver of the message and is mapped to a SOAP header with wsa:To element name. reply endpoint represents an endpoint reference for the intended receiver for replies to this message and is mapped to a SOAP header with wsa:ReplyTo element name.  In addition, WSDL Binding, also defines requirement on the presence of these MAPs for standard Message Exchange Patterns (MEPs) such as request/response and one-way.

Using these MAPs, complex MEPs can be created. For example:

There are several Web services specification (commonly known as WS-* specs) that make use of the abstract properties defined by WS-Addressing. For example WS-Metadata Exchange define a bootstrap mechanism for retrieving metadata before the business message exchange can take place. This mechanism involve sending a WS-Transfer request for the retrieval of a resource's representation. A typical request message looks like:

<s11:Envelope                                              
        xmlns:s11="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:wsa="http://www.w3.org/2005/08/addressing">  
    <s11:Header>
        <wsa:Action>                                       
            http://schemas.xmlsoap.org/ws/2004/09/transfer/Get
        </wsa:Action>
        <wsa:To>http://example.org/metadata</wsa10:To>
        <wsa:ReplyTo>
            <wsa:Address>http://www.w3.org/2005/08/addressing/anonymous
            </wsa10:Address>
        </wsa:ReplyTo>
        <wsa:MessageID>
            uuid: 68da6b24-7fa1-4da2-8a06-e615bfa3d2d0
        </wsa:MessageID>
    </s11:Header>
    <s11:Body/>
</s11:Envelope>

This message has an empty SOAP Body and relies completely upon standard MAPs to convey all the information. Similarly, a WS-Metadata Exchange response message with metadata looks like:

<s11:Envelope
        xmlns:s11="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:wsa="http://www.w3.org/2005/08/addressing">
    <s11:Header>
        <wsa:Action>                                       
            http://schemas.xmlsoap.org/ws/2004/09/transfer/GetResponse
        </wsa:Action>
        <wsa:RelatesTo>
            uuid: 68da6b24-7fa1-4da2-8a06-e615bfa3d2d0
        </wsa:RelatesTo>
    </s11:Header>
    <s11:Body/>                                            
    ...
    <s11:Body/>
</s11:Envelope>

WS-Reliable Messaging describes a protocol that allows messages to be delivered reliably between distributed applications in the presence of software component, system or network failures. This specification defines protocol messages that must be exchanged between client and service endpoint, before the business message exchange, in order to deliver the messages reliably. For example, RM Source sends <CreateSequence> request message to RM Destination to create an outbound sequence. The message looks like:

<s11:Envelope
        xmlns:s11="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:wsa=" http://www.w3.org/2005/08/addressing"
        xmlns:wsrm=" http://schemas.xmlsoap.org/ws/2005/02/rm">
    <s11:Body>                                             
        <wsrm:CreateSequence>
            <wsrm:AcksTo>
                <wsa:Address>
                    http://www.w3.org/2005/08/addressing/anonymous
                </wsa:Address>
            </wsrm:AcksTo>
        </wsrm:CreateSequence>
    </s11:Body>
</s11:Envelope>

The Body contains an element, wsrm:AcksTo (of the type Endpoint Reference), that specifies the endpoint reference to which <SequenceAcknowledgement> messages and faults related to sequence creation are sent.

WS-Secure Conversation, WS-Trust, WS-Policy and other similar specifications use the constructs defined by WS-Addressing as building blocks.

Addressing 1.0 - Metadata specification uses Web Services Policy Framework (WS Policy 1.5) and Web Services Policy - Attachment [ WS Policy 1.5 - Attachment] specifications to express the support of Web Services Addressing 1.0. A new policy assertion <wsam:Addressing> is defined to express the support of Addressing. The wsam:Addressing policy assertion applies to the endpoint policy subject and may be attached to wsdl11:port or wsdl11:binding.

Indicating the requirement of WS-Addressing: When

<wsam:Addressing>

is present in a Policy alternative, one is required to use WS-Addressing to communicate with the subject.

Indicating the support of WS-Addressing:

<wsam:Addressing wsp:Optional="true">

can be used to indicate support for WS-Addressing but does not require the use of it. In these cases, there are no restrictions about the use of WS-Adressing.

In certain cases, the endpoint can lay some restrictions to indicate the messages it can accept with WS-Addressing. Nested asertions can be used to restrict the use of response endpoint inside the <wsam:Addressing> assertion.

Requiring the use of Non-Anonymous response endpoints:

<wsam:Addressing>
    <wsp:Policy>
        <wsam:NonAnonymousResponses/>
    </wsp:Policy>
</wsam:Addressing>

can be used to indicate that the subject requires WS-Addressing and requires the use of non-anonymous response EPRs. In this case, the response endpoint in the request messages will have to use something other than the anonymous URI as the value of address. This is typically used when the response needs to be sent to a third entity other than the client and service and the response is sent to the non-anonyous URI through a new connection Requiring the use of Anonymous response endpoints:

<wsam:Addressing>
    <wsp:Policy>
        <wsam:AnonymousResponses/>
    </wsp:Policy>
</wsam:Addressing>

can be used to indicate that the subject requires WS-Addressing and requires the use of anonymous responses. In this case, the endpoint requires request messages to use response endpoint EPRs that contain the anonymous URI ("http://www.w3.org/2005/08/addressing/anonymous") or None URI ("http://www.w3.org/2005/08/addressing/none") as the value of address.

W3C WS-Addressing WSDL Binding defines an extensibility element, wsaw:UsingAddressing, that can be used to indicate that an endpoint conforms to the WS-Addressing specification. Eclipse Implementation of XML Web Services generates this extension element in the WSDL if W3C WS-Addressing is enabled on the server-side. On the client side, the RI recognizes this extension element and enforce the rules defined by the W3C specification. This extensibility element may be augmented with wsdl:required attribute to indicate whether WS-Addressing is required (true) or not (false).

W3C WS-Addressing WSDL Binding defines wsaw:Anonymous element which when used in conjunction with wsaw:UsingAddressing define assertions regarding a requirement or a constraint in the use of anonymous URI in EPRs sent to the endpoint. The WSDL Binding defines three distinct values: optional, required and prohibited to express the assertion. The default value of wsaw:Anonymous (equivalent to not present) is optional. An operation with required wsaw:Anonymous value is shown below:

<wsaw:UsingAddressing wsdl:required="true"/>
<soap:binding transport="http://schemas.xmlsoap.org/soap/http"
        style="document"/>
<operation name="addNumbers">
    <soap:operation soapAction=""/>
    
    ...
    
    <wsaw:Anonymous>required</wsaw:Anonymous>
</operation>
<soap:binding>

In this case, a message received at the endpoint, for this operation, with a non-anonymous ReplyTo or FaultTo EPR will result in a fault message returned back to the client with wsa:OnlyAnonymousAddressSupported fault code. There is no such equivalent feature in Member Submission WS-Addressing.

Starting from WSDL, If the wsdl contains the above described metadata to indicate use addressing at endpoint scope, Addressing is enabled on the server-side.  See  Describing WS-Addressing in WSDL section for more details.

This section describes how WS-Addressing can be enabled/disabled if you develop an endpoint starting from a Java SEI.

By default, WS-Addressing is disabled on an endpoint starting from Java. If that is the expected behavior, then nothing else needs to be done. In that case any WS-Addressing headers received at the endpoint are treated like SOAP headers targeted for the appliaction and are ignored.

@jakarta.xml.ws.soap.Addressing
@jakarta.jws.WebService
public class AddNumbersImpl {

    // ...

}

@com.sun.xml.ws.developer.MemberSubmissionAddressing
@jakarta.jws.WebService
public class AddNumbersImpl {

    // ...

}

@com.sun.xml.ws.developer.MemberSubmissionAddressing(enabled = true,
        required = true)
@jakarta.jws.WebServicepublic
class AddNumbersImpl {

    // ...

}

As defined in Describing WS-Addressing in WSDL, If the WSDL contains metadata about the support or requirement of WS-Addressing, Eclipse Implementation of XML Web Services runtime enables Addressing feature on the client-side.

There is no standard extensibility element for Member Submission WS-Addressing and so there is no implicit behavior defined. It can only be explicitly enabled as described in the next section. 

If a WSDL does not contain WS-Addressing standard extensibility element, then either W3C WS-Addressing or Member Submission WS-Addressing can be explicitly enabled using createDispatch and getPort methods on jakarta.xml.ws.Service. The following new APIs are added in Jakarta XML Web Services 2.1:

Each method is a variation of an already existing method in Jakarta XML Web Services. The only addition is an extra var-arg jakarta.xml.ws.WebServiceFeature parameter. A WebServiceFeature is a new class introduced in Jakarta XML Web Services 2.1 specification used to represent a feature that can be enabled or disabled for a Web service.

The Jakarta XML Web Services 2.1 specification defines jakarta.xml.ws.soap.AddressingFeature to enable W3C WS-Addressing on the client side. In addition, the Eclipse Implementation of XML Web Services also defines com.sun.xml.ws.developer.MemberSubmissionAddressingFeature to enable Member Submission WS-Addressing on the client side.

For example in fromjava-wsaddressing example, in order to enable W3C WS-Addressing on a proxy, wsimport is used to generate the AddNumbersImplService class. Then a port can be obtained using the getAddNumbersImplPort method and passing an instance of jakarta.xml.ws.AddressingFeature. The code looks like:

new AddNumbersImplService().getAddNumbersImplPort(new jakarta.xml.ws.AddressingFeature());

Similarly, a Dispatch instance with Member Submission WS-Addressing can be created as:

new AddNumbersImplService().createDispatch(
        new QName("http://server.fromjava_wsaddressing/", 
                "AddNumbersImplPort"),
        SOAPMessage.class, 
        Service.Mode.MESSAGE,
        new com.sun.xml.ws.developer.MemberSubmissionAddressingFeature());

Feature Parameters

Both jakarta.xml.ws.soap.AddressingFeature and com.sun.xml.ws.developer.MemberSubmissionAddressingFeature take two optional Boolean parameters, enabled (default true) and required (default false). If enabled, all WS-Addressing headers are generated for an outbound message. If required is specified true, then WS-Addressing rules are enforced for inbound message. Otherwise the inbound message is inspected to find out if WS-A is engaged and then the rules are enforced.

For example, to enforce Member Submission WS-Addressing rules on the client side, the above code sample will change to:

new AddNumbersImplService().getAddNumbersImplPort(new com.sun.xml
        .ws.developer.MemberSubmissionAddressingFeature(true, true));

A client may like to instruct Eclipse Implementation of XML Web Services to disable WS-Addressing processing. The assumption is that in this case the client has it's own WS-Addressing processing module. For example, a Dispatch-based client in MESSAGE mode may be used to perform non-anonymous ReplyTo/FaultTo processing.

WS-Addressing processing can be explicitly disabled using one of new methods added to Jakarta XML Web Services 2.1 specification as defined in Section 3.2. For example, W3C WS-Addressing processing can be disabled using the following code:

new AddNumbersImplService().getAddNumbersImplPort(new jakarta.xml.ws.AddressingFeature(false));

In most common cases, an implicit Action association, as defined by W3C WS-Addressing 1.0 - Metadata and Member Submission, will be sufficient. For such cases, only using the correct annotation to enable Addressing is required. The client looking at such a WSDL will send the implicit wsa:Action header. If only Addressing is enabled by using the appropriate annotation at the SEI, 

This section describes how an explicit Action Message Addressing Property can be associated with an operation in the SEI.

W3C WS-Addressing W3C WS-Addressing 1.0 - Metadata and Member Submission WS-Addressing define mechanisms to associate Action Message Addressing Property with an operation. Jakarta XML Web Services defines jakarta.xml.ws.Action and jakarta.xml.ws.FaultAction annotations to explicitly associate an Action with input, output, and fault messages of the mapped WSDL operation. For example, one of the methods in the fromjava-wsaddressing sample looks like:

@Action(input = "http://example.com/input3", output = "http://example.com/output3",
        fault = {@FaultAction(className = AddNumbersException.class,
        value = "http://example.com/fault3")})
public int addNumbers3(int number1, int number2) throws AddNumbersException {

    // ...

}

The generated WSDL fragment looks like:

<operation name="addNumbers3">
    <input wsam:Action="http://example.com/input3"
            message="tns:addNumbers3"/>
    <output wsam:Action="http://example.com/output3"
            message="tns:addNumbers3Response"/>
    <fault message="tns:AddNumbersException" name="AddNumbersException"
            wsam:Action="http://example.com/fault3"/>
</operation>

where wsam is bound to W3C WS-Addressing 1.0 - Metadata namespace or Member Submission namespace depending upon the annotation used to enable Addressing.