# Optional Annotations

While the @WebService annotation is sufficient for service enabling a Java interface or a Java class, it does not provide a lot of information about how the service will be exposed as an endpoint. The JAX-WS programming model uses a number of optional annotations for adding details about your service, such as the binding it uses, to the Java code. You add these annotations to the service's SEI.

Information noteNote: The more details you provide in the SEIthe easier it will be for developers to implement applications that can use the functionality it defines. It will also provide for better generated WSDL contracts.

## Defining the Binding Properties with Annotations

If you are using a SOAP binding for your service, you can use JAX-WS annotations to specify a number of the bindings properties. These properties correspond directly to the properties you can specify in a service's WSDL contract.

## The @SOAPBinding annotation

The @SOAPBinding annotation is defined by the javax.jws.soap.SOAPBinding interface. It provides details about the SOAP binding used by the service when it is deployed. If the @SOAPBinding annotation is not specified, a service is published using a wrapped doc/literal SOAP binding.

You can put the @SOAPBinding annotation on the SEI and any of the SEI's methods. When it is used on a method, setting of the method's @SOAPBinding annotation take precedent.

The following table shows the properties for the @SOAPBinding annotation.

| Property | Values | Description |
| --- | --- | --- |
| style | Style.DOCUMENT (default)<br>Style.RPC | Specifies the style of the SOAP message. If RPC style is<br>specified, each message part within the SOAP body is a parameter or return<br>value and will appear inside a wrapper element within the<br>soap:body element. The message parts within the wrapper<br>element correspond to operation parameters and must appear in the same order<br>as the parameters in the operation. If DOCUMENT style is<br>specified, the contents of the SOAP body must be a valid XML document, but<br>its form is not as tightly constrained. |
| use | Use.LITERAL (default)<br>Use.ENCODED | Specifies how the data of the SOAP message is streamed. |
| parameterStyle | ParameterStyle.BARE<br><br>ParameterStyle.WRAPPED (default) | Specifies how the method parameters, which correspond to message parts<br>in a WSDL contract, are placed into the SOAP message body. A parameter style<br>of BARE means that each parameter is placed into the message<br>body as a child element of the message root. A parameter style of<br>WRAPPED means that all of the input parameters are wrapped<br>into a single element on a request message and that all of the output<br>parameters are wrapped into a single element in the response message. If you<br>set the style to RPC you must use the WRAPPED parameter style. |

The below shows an SEI that uses rpc/literal SOAP messages.

Specifying an RPC/LITERAL SOAP Binding

```
package org.eric.demo;
            
            import javax.jws.*;
            import javax.jws.soap.*;
            import javax.jws.soap.SOAPBinding.*;
            
            @WebService(name="quoteReporter")
            @SOAPBinding(style=Style.RPC, use=Use.LITERAL)
            public interface QuoteReporter {
            ...
            }
```

## Defining Operation Properties with Annotations

When the runtime maps your Java method definitions into XML operation definitions it fills in details such as:

* what the exchanged messages look like in XML.

* if the message can be optimized as a one way message.

* the namespaces where the messages are defined.

## The @WebMethod annotation

The @WebMethod annotation is defined by the javax.jws.WebMethod interface. It is placed on the methods in the SEI. The @WebMethod annotation provides the information that is normally represented in the wsdl:operation element describing the operation to which the method is associated.

The following table describes the properties of the @WebMethod annotation.

| Property | Description |
| --- | --- |
| operationName | Specifies the value of the associated wsdl:operation<br>element's name. The default value is the name of the method. |
| action | Specifies the value of the soapAction attribute of the<br>soap:operation element generated for the method. The default<br>value is an empty string. |
| exclude | Specifies if the method should be excluded from the service interface.<br>The default is false . |

## The @RequestWrapper annotation

The @RequestWrapper annotation is defined by the javax.xml.ws.RequestWrapper interface. It is placed on the methods in the SEI. As the name implies, @RequestWrapper specifies the Java class that implements the wrapper bean for the method parameters that are included in the request message sent in a remote invocation. It is also used to specify the element names, and namespaces, used by the runtime when marshalling and unmarshalling the request messages.

The following table describes the properties of the @RequestWrapper annotation.

| Property | Description |
| --- | --- |
| localName | Specifies the local name of the wrapper element in the XML<br>representation of the request message. The default value is the name of the<br>method or the value of the @WebMethod annotation's<br>operationName property. |
| targetNamespace | Specifies the namespace under which the XML wrapper element is defined.<br>The default value is the target namespace of the SEI. |
| className | Specifies the full name of the Java class that implements the wrapper<br>element. |

Information noteNote: Only the className property is required.

## The @ResponseWrapper annotation

The @ResponseWrapper annotation is defined by the javax.xml.ws.ResponseWrapper interface. It is placed on the methods in the SEI. As the name implies, @ResponseWrapper specifies the Java class that implements the wrapper bean for the method parameters that are included in the response message sent in a remote invocation. It is also used to specify the element names, and namespaces, used by the runtime when marshalling and unmarshalling the response messages.

The following table describes the properties of the @ResponseWrapper annotation.

| Property | Description |
| --- | --- |
| localName | Specifies the local name of the wrapper element in the XML<br>representation of the response message. The default value is the name of the<br>method with Response appended or the value of the<br>@WebMethod annotation's operationName property<br>with Response appended. |
| targetNamespace | Specifies the namespace under which the XML wrapper element is defined.<br>The default value is the target namespace of the SEI. |
| className | Specifies the full name of the Java class that implements the wrapper<br>element. |

Information noteNote: Only the className property is required.

## The @WebFault annotation

The @WebFault annotation is defined by the javax.xml.ws.WebFault interface. It is placed on exceptions that are thrown by your SEI. The @WebFault annotation is used to map the Java exception to a wsdl:fault element. This information is used to marshall the exceptions into a representation that can be processed by both the service and its consumers.

The following table describes the properties of the @WebFault annotation.

| Property | Description |
| --- | --- |
| name | Specifies the local name of the fault element. |
| targetNamespace | Specifies the namespace under which the fault element is defined. The<br>default value is the target namespace of the SEI. |
| faultName | Specifies the full name of the Java class that implements the<br>exception. |

Information noteNote: The name property is required.

## The @Oneway annotation

The @Oneway annotation is defined by the javax.jws.Oneway interface. It is placed on the methods in the SEI that will not require a response from the service. The @Oneway annotation tells the run time that it can optimize the execution of the method by not waiting for a response and not reserving any resources to process a response.

## Example of SEI with Annotated Methods

The next example shows an SEI whose methods are annotated.

SEI with Annotated Methods

```
package org.apache.cxf;
            
            import javax.jws.*;
            import javax.xml.ws.*;
            
            @WebService(name="quoteReporter")
            public interface QuoteReporter {
            @WebMethod(operationName="getStockQuote")
            @RequestWrapper(targetNamespace="http://demo.mycompany.com/types",
            className="java.lang.String")
            @ResponseWrapper(targetNamespace="http://demo.mycompany.com/types",
            className="org.eric.demo.Quote")
            public Quote getQuote(String ticker);
            }
```

## Defining Parameter Properties with Annotations

The method parameters in the SEI coresspond to the wsdl:message elements and their wsdl:part elements. JAX-WS provides annotations that allow you to describe the wsdl:part elements that are generated for the method parameters.

## The @WebParam annotation

The @WebParam annotation is defined by the javax.jws.WebParam interface. It is placed on the parameters on the methods defined in the SEI. The @WebParam annotation allows you to specify the direction of the parameter, if the parameter will be placed in the SOAP header, and other properties of the generated wsdl:part .

The following table describes the properties of the @WebParam annotation.

| Property | Description |
| --- | --- |
| name | Specifies the name of the parameter as it appears in the WSDL. For RPC<br>bindings, this is name of the wsdl:part representing the<br>parameter. For document bindings, this is the local name of the XML element<br>representing the parameter. Per the JAX-WS specification, the default is<br>argN , where N is replaced with the zero-based argument index (i.e.,<br>arg0 , arg1 , etc.) |
| targetNamespace | Specifies the namespace for the parameter. It is only used with document<br>bindings where the parameter maps to an XML element. The defaults is to use<br>the service's namespace. |
| mode | Specifies the direction of the parameter: Mode.IN (default), Mode.OUT,<br>Mode.INOUT |
| header | Specifies if the parameter is passed as part of the SOAP header. Values<br>of true or false (default). |
| partName | Specifies the value of the name attribute of the wsdl:part<br>element for the parameter when the binding is document. |

## The @WebResult annotation

The @WebResult annotation is defined by the javax.jws.WebResult interface. It is placed on the methods defined in the SEI. The @WebResult annotation allows you to specify the properties of the generated wsdl:part that is generated for the method's return value.

The following table describes the properties of the @WebResult annotation.

| Property | Description |
| --- | --- |
| name | Specifies the name of the return value as it appears in the WSDL. For<br>RPC bindings, this is name of the wsdl:part representing the<br>return value. For document bindings, this is the local name of the XML<br>element representing the return value. The default value is return. |
| targetNamespace | Specifies the namespace for the return value. It is only used with<br>document bindings where the return value maps to an XML element. The<br>defaults is to use the service's namespace. |
| header | Specifies if the return value is passed as part of the SOAP<br>header. |
| partName | Specifies the value of the name attribute of the wsdl:part<br>element for the return value when the binding is document. |

## Example of fully annotated SEI

This example shows an SEI that is fully annotated.

Fully Annotated SEI

```
package org.apache.cxf;
            
            import javax.jws.*;
            import javax.xml.ws.*;
            import javax.jws.soap.*;
            import javax.jws.soap.SOAPBinding.*;
            import javax.jws.WebParam.*;
            
            @WebService(name="quoteReporter")
            @SOAPBinding(style=Style.RPC, use=Use.LITERAL)
            public interface QuoteReporter {
            @WebMethod(operationName="getStockQuote")
            @RequestWrapper(targetNamespace="http://demo.mycompany.com/types",
            className="java.lang.String")
            @ResponseWrapper(targetNamespace="http://demo.mycompany.com/types",
            className="org.eric.demo.Quote")
            @WebResult(targetNamespace="http://demo.mycompany.com/types",
            name="updatedQuote")
            public Quote getQuote(
            @WebParam(targetNamespace="http://demo.mycompany.com/types",
            name="stockTicker", mode=Mode.IN)
            String ticker
            );
            }
```