Defining Operation Properties with Annotations

Overview

When the runtime maps your Java method definitions into XML operation definitions it provides 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 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.

Table 1.3 describes the properties of the @WebMethod annotation.

Table 1.3. @WebMethod Properties

Property	Description
operationName	Specifies the value of the associated `wsdl:operation` element's `name`. The default value is the name of the method.
action	Specifies the value of the `soapAction` attribute of the `soap:operation` element generated for the method. The default value is an empty string.
exclude	Specifies if the method should be excluded from the service interface. 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. The @RequestWrapper annotation specifies the Java class implementing the wrapper bean for the method parameters of the request message starting a message exchange. It also specifies the element names, and namespaces, used by the runtime when marshalling and unmarshalling the request messages.

Table 1.4 describes the properties of the @RequestWrapper annotation.

Table 1.4. @RequestWrapper Properties

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

	Tip
	Only the className property is required.

	Important
	If the method is also annotated with the `@SOAPBinding` annotation, and its parameterStyle property is set to `ParameterStyle.BARE`, this annotation is ignored.

The `@ResponseWrapper` annotation

The @ResponseWrapper annotation is defined by the javax.xml.ws.ResponseWrapper interface. It is placed on the methods in the SEI. The @ResponseWrapper specifies the Java class implementing the wrapper bean for the method parameters in the response message in the message exchange. It also specifies the element names, and namespaces, used by the runtime when marshaling and unmarshalling the response messages.

Table 1.5 describes the properties of the @ResponseWrapper annotation.

Table 1.5. @ResponseWrapper Properties

Property	Description
localName	Specifies the local name of the wrapper element in the XML representation of the response message. The default value is either the name of the method with `Response` appended, or the value of the `@WebMethod` annotation's operationName property with `Response` appended.
targetNamespace	Specifies the namespace where the XML wrapper element is defined. The default value is the target namespace of the SEI.
className	Specifies the full name of the Java class that implements the wrapper element.

	Tip
	Only the className property is required.

	Important
	If the method is also annotated with the `@SOAPBinding` annotation and its parameterStyle property is set to `ParameterStyle.BARE`, this annotation is ignored.

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.

Table 1.6 describes the properties of the @WebFault annotation.

Table 1.6. @WebFault Properties

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

	Important
	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 by not reserving any resources to process a response.

This annotation can only be used on methods that meet the following criteria:

They return void
They have no parameters that implement the Holder interface
They do not throw any exceptions that can be passed back to a consumer

Example

Example 1.6 shows an SEI with its methods annotated.

Example 1.6. SEI with Annotated Methods

package com.fusesource.demo;

import javax.jws.*;
import javax.xml.ws.*;

@WebService(name="quoteReporter")
public interface quoteReporter
{
  @WebMethod(operationName="getStockQuote")
  @RequestWrapper(targetNamespace="http://demo.fusesource.com/types", 
                  className="java.lang.String")
  @ResponseWrapper(targetNamespace="http://demo.fusesource.com/types", 
                   className="org.eric.demo.Quote")
  public Quote getQuote(String ticker);
}