Optional Annotations

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.

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

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

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.

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.

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.

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.

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

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

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.

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