# Annotations

## Overview

Annotations play a critical role in JAX-WS &jax-ws.release.spec.version;. First, annotations are used in mapping Java to WSDL and schema. Second, annotations are used a runtime to control how the JAX-WS runtime processes and responds to web service invocations. Currently the annotations utilized by JAXR-WS 2.0 are defined in separate JSRs:

- JSR 181: Web Services Metadata for the Java TM Platform

- JSR 222: Java TM Architecture for XML Binding (JAXB) 2.1

- JSR 224: Java TM API for XML Web Services (JAX-WS) 2.0 and 2.1

- JSR 250: Common Annotations for the Java TM Platform.

## JSR 181 (Web Services Metadata) Annotations

Because JSR 181 has been written to work with JAX-RPC 1.1, we have made slight changes in the use and interpretation of these annotations to work better with JAX-WS 2.0. We are working with the JSR 181 expert group to align the next release with JAX-WS 2.0 and we hope that all of the changes we have made will be folded in.

### `@javax.jws.WebService`

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 JAX-WS 2.0 specification.

`@javax.jws.WebService` - Description of Properties

Property | Description | Default
--- | --- | ---
`name` | The name of the `wsdl:portType` | The unqualified name of the Java class or interface
`targetNamespace` | The XML namespace of the the WSDL and some of the XML elements generated from this web service. Most of the XML elements will be in the namespace according to the JAXB mapping rules. | The namespace mapped from the package name containing the web service according to section 3.2 of the JAX-WS 2.0 specification.
`serviceName` | The Service name of the web service: `wsdl:service` | The unqualified name of the Java class or interface + "Service"
`endpointInterface` | The qualified name of the service endpoint interface. If the implementation bean references a service endpoint interface, that service endpoint interface is used to determine the abstract WSDL contract (portType and bindings). In this case, the service implementation bean MUST NOT include any JSR 181 annotations other than `@WebService` and `@HandlerChain` In addition, the `@WebService` annotation MUST NOT include the name annotation element. The endpoint implementation class is not required to implement the endpointInterface. | None – If not specified, the endpoint implementation class is used to generate the web service contract. In this case, a service endpoint interface is not required.
`portName` | The `wsdl:portName` | The `WebService.name` + "Port"
`wsdlLocation` | Not currently used by &jax-ws.product.name; |

#### Annotation Type Definition

    @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 "";
    }

#### Examples

`@javax.jws.WebService` - Example 1

    @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;
        }
    }

If you are familiar with JAX-RPC 1.1, you will notice that the `AddNumbersImpl` implementation class does not implement a service endpoint interface. In JAX-WS &jax-ws.release.spec.version; a service endpoint interface is no longer required. If a service endpoint interfaces is desired, then the `@WebService` annotation on the endpoint implementation is modified to specify the endpoint interface and the actual service endpoint interface must also have a `@WebService` annotation. The following is the above `AddNumbersImpl` modified to use a service endpoint interface.

`@javax.jws.WebService` - Example 2 - Implementation class using Service Endpoint Interface

    @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;

    }

### `@javax.jws.WebMethod`

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 JAX-WS 2.0 specification.

`@javax.jws.WebMethod` - Description of Properties

Property | Description | Default
--- | --- | ---
`operationName` | The name of the `wsdl:operation` matching this method. For operations using the mode defined by `SOAPBinding.Style.DOCUMENT`, `SOAPBinding.Use.LITERAL`, and `SOAPBinding.ParameterStyle.BARE`, this name is also used for the global XML element representing the operations body element. The namespace of this name is taken from the value `@WebService.targetNamespace` or its default value. | The name of the Java method
`action` | The XML namespace of the the WSDL and some of the XML elements generated from this web service. Most of the XML elements will be in the namespace according to the JAXB mapping rules. | ""
`exclude` | Used to exclude a method from the WebService. | false

#### Annotation Type Definition

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

        String action() default "";

        boolean exclude() default false;
    }

#### Examples

`@javax.jws.WebMethod` - Example

    @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;

    }

### `@javax.jws.OneWay`

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 JSR 224 spec.

There are no properties on the `OneWay` annotation.

#### Annotation Type Definition

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

#### Examples

`@javax.jws.OneWay` - Example

    @WebService(name = "CheckIn")
    public class CheckInIF {

        @WebMethod
        @OneWay
        public void checkIn(String name);

    }

### `@javax.jws.WebParam`

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

`@javax.jws.WebParam` - Description of Properties

Property | Description | Default
--- | --- | ---
`name` | Name of the parameter. If the operation is RPC style and `@WebParam.partName` has not been specified, this is name of the `wsdl:part` representing the parameter. `@WebMethod.operation` Name, if the operation is document style and the parameter style is `BARE`. Otherwise, the default is `argN` if the operation is document style or the parameter maps to a header, this is the local name of the XML element representing the parameter. A name MUST be specified if the operation is document style, the parameter style is `BARE`, and the mode is `OUT` or `INOUT`. | `@WebMethod.operation` Name, if the operation is document style and the parameter style is `BARE`. Otherwise, the default is `argN`, where `N` represents the index of the parameter in the method signature (starting at `arg0`).
`targetNamespace` | The XML namespace for the parameter. Only used if the operation is document style or the paramater maps to a header. If the target namespace is set to "", this represents the empty namespace. | The empty namespace, if the operation is document style, the parameter style is `WRAPPED`, and the parameter does not map to a header. Otherwise, the default is the `targetNamespace` for the Web Service.
`mode` | Represents the direction the parameter flows for this method. Possible values are `IN`, `INOUT` and `OUT`. `INOUT` and `OUT` modes can only be used with parameters that meet the requirements for a holder as classified by section 3.5 of the JAX-WS 2.0 specification. `OUT` and `INOUT` parameters can be used by all `RPC` and `DOCUMENT` bindings. | `IN` for non-holder parameters `INOUT` for holder parameters.
`header` | Specifies whether the parameter should be carried in a header. | `FALSE`
`partName` | Used to specify the `partName` for the parameter with `RPC` or `DOCUMENT`/`BARE` operations. | `@WebParam.name`

#### Annotation Type Definition

    @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 "";
    }

#### Examples

`@javax.jws.WebParam` - Example 1

    @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;

    }

`@javax.jws.WebParam` - Example 2

    @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;

    }

### `@javax.jws.WebResult`

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

`@javax.jws.WebResult` - Description of Properties

Property | Description | Default
--- | --- | ---
`name` | The name of the return value in the WSDL and on the wire. For `RPC` bindings this is the part name of the return value in the response message. For `DOCUMENT` bindings this is the local name of the XML element representing the return value. | "return" for `RPC` and `DOCUMENT`/`WRAPPED` bindings. Method name + "Response" for `DOCUMENT`/`BARE` bindings.
`targetNamespace` | The XML namespace for the return value. Only used if the operation is document style or the return value maps to a header. If the target namespace is set to "", this represents the empty namespace. | The empty namespace, if the operation is document style, the parameter style is `WRAPPED`, and the return value does not map to a header, Otherwise, the default is the `targetNamespace` for the Web Service.
`header` | Specifies whether the result should be carried in a header. | `FALSE`
`partName` | Used to specify the `partName` for the result with `RPC` or `DOCUMENT`/`BARE` operations. | `@WebResult.name`

#### Annotation Type Definition

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

        String name() default "return";

        String targetNamespace() default "";

        boolean header() default false;

        String partName() default "";
    }

#### Examples

`@javax.jws.WebResult` - Example

    @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;

    }

### `@javax.jws.HandlerChain`

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

`@javax.jws.HandlerChain` - Description of Properties

Property | Description | Default
--- | --- | ---
`file` | Location of the file containing the handler chain definition. The location can be relative or absolute with in a classpath system. If the location is relative, it is relative to the package of the web service. If it is absolute, it is absolute from some path on the classpath. | None
`name` | DEPRECATED The handler chain name from within the handler chain file. | ""

#### Annotation Type Definition

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

        String file();

        @Deprecated String name() default "";

    }

#### Examples

`@javax.jws.HandlerChain` - Example

    @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;
        }

    }

`@javax.jws.HandlerChain` - Example - handlers.xml

    <jws:handler-config xmlns:jws="http://java.sun.com/xml/ns/javaee">
        <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>

When using a handler chain file, it is important that the file is store in the appropriate place in the classpath so that the file can be found. This means that when a raw WAR file is created that the file must be place in the proper directory. Please refer to the fromjavahandlers sample application and the for more information.

### `@javax.jws.soap.SOAPBinding`

JSR 181 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`. JAX-WS &jax-ws.release.spec.version; 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.

`@javax.jws.soap.SOAPBinding` - Description of Properties

Property | Description | Default
--- | --- | ---
`style` | Defines the style for messages used in a web service. The value can be either `DOCUMENT` or `RPC`. | `DOCUMENT`
`use` | Defines the encoding used for messages used in web service. Can only be `LITERAL` for JAX-WS &jax-ws.release.spec.version;. | `LITERAL`
`parameterStyle` | Determines if the method's parameters represent the entire message body or whether the parameters are wrapped in a body element named after the operation. Choice of `WRAPPED` or `BARE`. `BARE` can only be used with `DOCUMENT` style bindings. | `WRAPPED`

#### Annotation Type Definition

    @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;

    }

#### Examples

`@javax.jws.soap.SOAPBinding` - Example

    @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;

    }

## JSR 224 (JAX-WS) Annotations

The following are standard annotations needed by JAX-WS that are not defined in JSR 181. The developer may not ever use these annotations directly as some of them are generated by JAX-WS tools but they will be presented here to avoid confusion.

### `@javax.xml.ws.BindingType`

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.

`@javax.xml.ws.BindingType` - Description of Properties

Property | Description | Default
--- | --- | ---
`value` | A binding identifier (a URI). See the `SOAPBinding` and `HTTPBinding` for the definition of the standard binding identifiers. `@see javax.xml.ws.Binding` `@see javax.xml.ws.soap.SOAPBinding#SOAP11HTTP_BINDING` `@see javax.xml.ws.soap.SOAPBinding#SOAP12HTTP_BINDING` `@see javax.xml.ws.http.HTTPBinding#HTTP_BINDING` | "`SOAP 1.1 Protocol`"/`HTTP`

#### Annotation Type Definition

    @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 javax.xml.ws.Binding
         * @see javax.xml.ws.soap.SOAPBinding#SOAP11HTTP_BINDING
         * @see javax.xml.ws.soap.SOAPBinding#SOAP12HTTP_BINDING
         * @see javax.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 javax.xml.ws.RespectBindingFeature
         * @see javax.xml.ws.soap.AddressingFeature
         * @see javax.xml.ws.soap.MTOMFeature
         * @since JAX-WS 2.1
         */
        Feature[] features() default {};
    }

#### Examples

`@javax.xml.ws.BindingType` - Example

Given the web service defined by

    @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;
        }
    }

The deployed endpoint would use the SOAP 1.2 over HTTP binding.

### `@javax.xml.ws.RequestWrapper`

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.

`@javax.xml.ws.RequestWrapper` - Description of Properties

Property | Description | Default
--- | --- | ---
`localName` | Specifies the `localName` of the XML Schema element representing this request wrapper. | `operationName` as defined by `@javax.jws.WebMethod`
`targetNamespace` | namespace of the request wrapper element. | the `targetNamespace` of the SEI
`className` | The name of the Class representing the request wrapper. |

#### Annotation Type Definition

    @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 "";
    }

#### Examples

`@javax.xml.ws.RequestWrapper` - Example

    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;
    }

### `@javax.xml.ws.ResponseWrapper`

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.

`@javax.xml.ws.ResponseWrapper` - Description of Properties

Property | Description | Default
--- | --- | ---
`localName` | Specifies the `localName` of the XML Schema element representing this request wrapper. | `operationName` as defined by `@javax.jws.WebMethod`
`targetNamespace` | namespace of the request wrapper element. | the `targetNamespace` of the SEI
`className` | The name of the Class representing the request wrapper. |

#### Annotation Type Definition

    @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 "";
    }

#### Examples

`@javax.xml.ws.ResponseWrapper` - Example

    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;
    }

### `@javax.xml.ws.ServiceMode`

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

`@javax.xml.ws.ServiceMode` - Description of Properties

Property | Description | Default
--- | --- | ---
`value` | Convey whether the `Provider` endpoint wants to access then entire message (`MESSAGE`) or just the payload (`PAYLOAD`). | `PAYLOAD`

#### Annotation Type Definition

    @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;
    }

#### Examples

`@javax.xml.ws.ServiceMode` - Example

    @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;
        }
    }

### `@javax.xml.ws.WebEndpoint`

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.

`@javax.xml.ws.WebEndpoint` - Description of Properties

Property | Description | Default
--- | --- | ---
`name` | Defines the local name of the XML element representing the corresponding port in the WSDL. | ""

#### Annotation Type Definition

    /**
     * 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 javax.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 "";
    }

#### Examples

`@javax.xml.ws.WebEndpoint` - Example

    @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);
        }
    }

### `@javax.xml.ws.WebFault`

This annotation is generated by the JAX-WS 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 JAX-WS 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 JAX-WS 2.0 specification.

`@javax.xml.ws.WebFault` - Description of Properties

Property | Description | Default
--- | --- | ---
`name` | Defines the local name of the XML element representing the corresponding fault in the WSDL. | ""
`targetNamespace` | Defines the namespace of the XML element representing the corresponding fault in the WSDL. | ""
`faultBean` | The qualified name of the Java class that represents the detail of the fault message. | ""

#### Annotation Type Definition

    /**
     * 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 "";
    }

#### Examples

`@javax.xml.ws.WebFault` - Example

    @javax.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;
        }

    }

### `@javax.xml.ws.WebServiceClient`

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.

`@javax.xml.ws.WebServiceClient` - Description of Properties

Property | Description | Default
--- | --- | ---
`name` | Defines the local name of the `wsdl:serviceName` in the WSDL. | ""
`targetNamespace` | Defines the namespace for the `wsdl:serviceName` in the WSDL. | ""
`wsdlLocation` | Specifies the location of the WSDL that defines this service. | ""

#### Annotation Type Definition

    /**
     * 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 "";
    }

#### Examples

`@javax.xml.ws.WebServiceClient` - Example

    @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);
        }
    }

### `@javax.xml.ws.WebServiceProvider`

Annotation used to annotate a `Provider` implementation class.

`@javax.xml.ws.WebServiceProvider` - Description of Properties

Property | Description | Default
--- | --- | ---
`targetNamespace` | The XML namespace of the the WSDL and some of the XML elements generated from this web service. Most of the XML elements will be in the namespace according to the JAXB mapping rules. | The namespace mapped from the package name containing the web service according to section 3.2 of the JAX-WS 2.0 specification.
`serviceName` | The Service name of the web service: `wsdl:service` | The unqualified name of the Java class or interface + "Service"
`portName` | The `wsdl:portName` |
`wsdlLocation` | Location of the WSDL description for the service |

#### Annotation Type Definition

    /**
     * Used to annotate a Provider implementation class.
     *
     * @since JAX-WS 2.0
     * @see javax.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 "";
    }

#### Examples

`@javax.xml.ws.WebServiceProvider` - Example

    @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;
        }
    }

### `@javax.xml.ws.WebServiceRef`

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 Java EE 5 sense.

`@javax.xml.ws.WebServiceRef` - Description of Properties

Property | Description | Default
--- | --- | ---
`name` | 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. |
`type` | 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. |
`mappedName` | A product specific name that this resource should be mapped to. |
`value` | The service class, always a type extending `javax.xml.ws.Service`. This element must be specified whenever the type of the reference is a service endpoint interface. |
`wsdlLocation` | Location of the WSDL description for the service |

#### Annotation Type Definition

    /**
     * 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 Java EE 5 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 JAX-WS 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 javax.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>javax.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 "";

    }

### `@javax.xml.ws.Action`

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.

`@javax.xml.ws.Action` - Description of Properties

Property | Description | Default
--- | --- | ---
`input` | Explicit value of `Action` message addressing property for the `input` message of the operation. If the value is "", then no `wsaw:Action` is generated. | ""
`ouput` | Explicit value of `Action` message addressing property for the `output` message of the operation. If the value is "", then no `wsaw:Action` is generated. | ""
`fault` | Explicit value of `Action` message addressing property for the `fault` message(s) of the operation. Each exception that is mapped to a fault and requires explicit `Action` message addressing property, need to be specified as a value in this property using FaultAction annotation. | {}

#### Annotation Type Definition

    /**
     * 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 JAX-WS 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 {};
    }

#### Examples

`@javax.xml.ws.Action` - Example 1 - Specify explicit values for `Action` message addressing property for `input` and `output` messages.

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

The generated WSDL looks like:

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

`@javax.xml.ws.Action` - Example 2 - Specify explicit value for `Action` message addressing property for only the `input` message.

The default values are used for the `output` message.

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

The generated WSDL looks like:

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

It is legitimate to specify an explicit value for `Action` message addressing property for `output` message only. In this case, a default value of `wsaw:Action` is used for the `input` message.

`@javax.xml.ws.Action` - Example 3 - `@FaultAction`

See `` for an example of how to specify an explicit value for `Action` message addressing property for the `fault` message.

### `@javax.xml.ws.FaultAction`

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.

`@javax.xml.ws.FaultAction` - Description of Properties

Property | Description | Default
--- | --- | ---
`className` | Name of the exception class | there is no default and is required.
`value` | Value of `Action` message addressing property for the exception | ""

#### Annotation Type Definition

    @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 "";
    }

#### Examples

`@javax.xml.ws.FaultAction` - Example 1 - Specify explicit values for `Action` message addressing property for the `input`, `output` and `fault` message if the Java method throws only one service specific exception.

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

The generated WSDL looks like:

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

`@javax.xml.ws.FaultAction` - Example 1 - Specify explicit values for `Action` message addressing property if the Java method throws only one service specific exception, without specifying the values for `input` and `output` messages.

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

The generated WSDL looks like:

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

`@javax.xml.ws.FaultAction` - Example 1 - Specify explicit values for `Action` message addressing property if the Java method throws more than one service specific exception.

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

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

The generated WSDL looks like:

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

## JSR 222 (JAXB) Annotations

The following JAXB annotations are being documented because JAX-WS generates them when generating wrapper beans and exception beans according to the JAX-WS 2.0 spec. Please refer to sections 3.5.2.1 and 3.6 of the JAX-WS 2.0 specification for more information on these beans. For more information on these and other JAXB annotations please refer to the JAXB 2.0 specification.

### `@javax.xml.bind.annotation.XmlRootElement`

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.

`@javax.xml.bind.annotation.XmlRootElement` - Description of Properties

Property | Description | Default
--- | --- | ---
`name` | Defines the local name of the XML element representing the annotated class | `##default` – the name is derived from the class
`namespace` | Defines the namespace of the XML element representing the annotated class | `##default` – the namespace is derived from the package of the class

#### Annotation Type Definition

    @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";

    }

#### Examples

`@javax.xml.bind.annotation.XmlRootElement` - Example

    @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;
        }
    }

### `@javax.xml.bind.annotation.XmlAccessorType`

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

`@javax.xml.bind.annotation.XmlAccessorType` - Description of Properties

Property | Description | Default
--- | --- | ---
`value` | Specifies whether fields or properties are serialized by default. The value can be `XmlAccessType.FIELD` or `XmlAccessType.PROPERTY` or `XmlAccessType.PUBLIC_MEMBER` or `XmlAccessType.NONE` | `XmlAccessType.PROPERTY`

#### Annotation Type Definition

    @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 JAXB-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 JAXB annotations.
         */
        PROPERTY,
        /**
         * Every non static, non transient field in a JAXB-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 JAXB 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 JAXB annotations.
         */
        PUBLIC_MEMBER,
        /**
         * None of the fields or properties is bound to XML unless they
         * are specifically  annotated with some of the JAXB
         * annotations.
         */
        NONE
    }

#### Examples

`@javax.xml.bind.annotation.XmlAccessorType` - Example

    @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;
        }
    }

### `@javax.xml.bind.annotation.XmlType`

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).

`@javax.xml.bind.annotation.XmlType` - Description of Properties

Property | Description | Default
--- | --- | ---
`name` | Defines the local name of the XML type representing this class in the XML schema used by the WSDL of the web service | "`##default`"
`namespace` | Defines the namespace of the XML type representing this class in the XML schema used by the WSDL of the web service | "`##default`"
`propOrder` | Defines 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. All of the JavaBean properties being mapped must be listed (i.e. if a JavaBean property mapping is prevented by `@XmlTransient` then it does not have to be listed). Otherwise, it is an error. By default, the JavaBean properties are ordered using a default order specified in the JAXB 2.0 specification. | {""}

#### Annotation Type Definition

    @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 "";
    }

#### Examples

`@javax.xml.bind.annotation.XmlType` - Example

    @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;
        }
    }

### `@javax.xml.bind.annotation.XmlElement`

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.

`@javax.xml.bind.annotation.XmlElement` - Description of Properties

Property | Description | Default
--- | --- | ---
`name` | Defines the local name of the XML element representing the property of a JavaBean | "`##default`" - the element name is derived from the JavaBean property name.
`namespace` | Defines the namespace of the XML element representing the property of a JavaBean | "`##default`" - the namespace of the containing class
`nillable` | Not generated by JAX-WS |
`type` | Not generated by JAX-WS |

#### Annotation Type Definition

    @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 {
        }
    }

#### Examples

`@javax.xml.bind.annotation.XmlElement` - Example

    @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;
        }
    }

### `@javax.xml.bind.annotation.XmlSeeAlso`

Instructs JAXB to also bind other classes when binding this class.

`@javax.xml.bind.annotation.XmlSeeAlso` - Description of Properties

Property | Description | Default
--- | --- | ---
`value` | Other classes that JAXB can use when binding this class | {}

#### Annotation Type Definition

    /**
     * Instructs JAXB 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 JAXB users, as it JAXB
     * 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, JAXB 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();
    }

## JSR 250 (Common Annotations) Annotations

The following annotations are being documented because JAX-WS endpoints use them for resource injection, and as lifecycle methods. Please refer to sections 5.2.1 and 5.3 of the JAX-WS 2.0 specification for resource injection, and lifecycle management. For more information on these and other common annotations please refer to the JSR 250: Common Annotations for the Java TM Platform .

### `@javax.annotation.Resource`

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 JAX-WS endpoints. The container will inject an instance of the WebServiceContext resource into the endpoint implementation when it is initialized.

`@javax.annotation.Resource` - Description of Properties

Property | Description | Default
--- | --- | ---
`type` | 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.

#### Annotation Type Definition

    @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;
    }

#### Examples

`@javax.annotation.Resource` - Example

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

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

### `@javax.annotation.PostConstruct`

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.

#### Annotation Type Definition

    /**
     * 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 javax.annotation.PreDestroy
     * @see javax.annotation.Resource
     * @since Common Annotations 1.0
     */
    @Documented
    @Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.METHOD)
    public @interface PostConstruct {
    }

#### Examples

`@javax.annotation.PostConstruct` - Example

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

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

### `@javax.annotation.PreDestroy`

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.

#### Annotation Type Definition

    /**
     * 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 Java EE 5. 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 javax.annotation.PostConstruct
     * @see javax.annotation.Resource
     * @since Common Annotations 1.0
     */

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

#### Examples

`@javax.annotation.PreDestroy` - Example

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

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