JAX-WS relies on the annotation feature of Java 5. The JAX-WS annotations are used to specify the metadata used to map the SEI to a fully specified service definition. Among the information provided in the annotations are the following:
The target namespace for the service.
The name of the class used to hold the request message.
The name of the class used to hold the response message.
If an operation is a one way operation.
The binding style the service uses.
The name of the class used for any custom exceptions.
The namespaces under which the types used by the service are defined.
Tip | |
---|---|
Most of the annotations have sensible defaults and do not need to be specified. However, the more information you provide in the annotations, the better defined your service definition. A solid service definition increases the likely hood that all parts of a distributed application will work together. |
In order to create a service from Java code you are only required to add one annotation to your code. You must add the @WebService()
annotation on both the SEI and the implementation class.
The @WebService
annotation is defined by the javax.jws.WebService
interface and it is placed on an interface or a class that is intended to be used as a service. @WebService
has the following properties:
Table 1.1. @WebService
Properties
Property | Description |
---|---|
name | Specifies the name of the service interface. This property is mapped to the name attribute of the wsdl:portType element that defines the service's interface in a WSDL contract. The default is to append PortType to the name of the implementation class.
[a]
|
targetNamespace | Specifies the target namespace under which the service is defined. If this property is not specified, the target namespace is derived from the package name. |
serviceName | Specifies the name of the published service. This property is mapped to the name attribute of the wsdl:service element that defines the published service. The default is to use the name of the service's implementation class.
[a]
|
wsdlLocation | Specifies the URI at which the service's WSDL contract is stored. The default is the URI at which the service is deployed. |
endpointInterface | Specifies the full name of the SEI that the implementation class implements. This property is only used when the attribute is used on a service implementation class. |
portName | Specifies the name of the endpoint at which the service is published. This property is mapped to the name attribute of the wsdl:port element that specifies the endpoint details for a published service. The default is the append Port to the name of the service's implementation class.
[a]
|
[a] When you generate WSDL from an SEI the interface's name is used in place of the implementation class' name. |
Tip | |
---|---|
You do not need to provide values for any of the |
The SEI requires that you add the @WebService
annotation. Since the SEI is the contract that defines the service, you should specify as much detail as you can about the service in the @WebService
annotation's properties.
Example 1.3, “Interface with the @WebService
Annotation” shows the interface defined in Example 1.1, “Simple SEI” with the @WebService
annotation.
Example 1.3. Interface with the @WebService
Annotation
package com.iona.demo; import javax.jws.*; @WebService(name="quoteUpdater", targetNamespace="http:\\demos.iona.com", serviceName="updateQuoteService", wsdlLocation="http:\\demos.iona.com\quoteExampleService?wsdl", portName="updateQuotePort") public interface quoteReporter { public Quote getQuote(String ticker); }
The @WebService
annotation in Example 1.3, “Interface with the @WebService
Annotation” does the following:
In addition to annotating the SEI with the @WebService
annotation, you also have to annotate the service implementation class with the @WebService
annotation. When adding the annotation to the service implementation class you only need to specify the endpointInterface property. As shown in Example 1.4, “Annotated Service Implementation Class” the property needs to be set to the full name of the SEI.
Example 1.4. Annotated Service Implementation Class
package org.eric.demo; import javax.jws.*; @WebService(endpointInterface="com.iona.demo.quoteReporter") public class stockQuoteReporter implements quoteReporter { public Quote getQuote(String ticker) { ... } }
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.
Tip | |
---|---|
The more details you provide in the SEI the 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. |
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 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.
Table 1.2, “@SOAPBinding
Properties” shows the properties for the @SOAPBinding
annotation.
Table 1.2. @SOAPBinding
Properties
Property | Values | Description |
---|---|---|
style |
|
Specifies the style of the SOAP message. If RPC style is specified, each message part within the SOAP body is a parameter or return value and will appear inside a wrapper element within the soap:body element. The message parts within the wrapper element correspond to operation parameters and must appear in the same order as the parameters in the operation. If DOCUMENT style is specified, the contents of the SOAP body must be a valid XML document, but its form is not as tightly constrained. |
use |
|
Specifies how the data of the SOAP message is streamed. |
parameterStyle [a] |
|
Specifies how the method parameters, which correspond to message parts in a WSDL contract, are placed into the SOAP message body. A parameter style of BARE means that each parameter is placed into the message body as a child element of the message root. A parameter style of WRAPPED means that all of the input parameters are wrapped into a single element on a request message and that all of the output parameters are wrapped into a single element in the response message. |
[a] If you set the style to |
Example 1.5, “Specifying an RPC/LITERAL SOAP Binding with the @SOAPBinding
Annotation” shows an SEI that uses rpc/literal SOAP messages.
Example 1.5. Specifying an RPC/LITERAL SOAP Binding with the @SOAPBinding
Annotation
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.
Table 1.3, “@WebMethod
Properties” describes the properties of the @WebMethod
annotation.
Table 1.3. @WebMethod
Properties
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.
Table 1.4, “@RequestWrapper
Properties” 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 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. |
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.
Table 1.5, “@ResponseWrapper
Properties” 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 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 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. |
The @WebFault
annotation is defined by the javax.xml.ws.WebFault
interface. It is placed on methods in the SEI that throw exceptions. 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, “@WebFault
Properties” describes the properties of the @WebFault
annotation.
Important | |
---|---|
The name property is required. |
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 1.6, “SEI with Annotated Methods” shows an SEI whose methods are annotated.
Example 1.6. SEI with Annotated Methods
package com.iona.demo; import javax.jws.*; import javax.xml.ws.*; @WebService(name="quoteReporter") public interface quoteReporter { @WebMethod(operationName="getStockQuote") @RequestWrapper(targetNamespace="http://demo.iona.com/types", className="java.lang.String") @ResponseWrapper(targetNamespace="http://demo.iona.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
.
Table 1.7, “@WebParam
Properties” describes the properties of the @WebParam
annotation.
Table 1.7. @WebParam
Properties
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.
Table 1.8, “@WebResult
Properties” describes the properties of the @WebResult
annotation.
Table 1.8. @WebResult
Properties
Example 1.7, “Fully Annotated SEI” shows an SEI that is fully annotated.
Example 1.7. Fully Annotated SEI
package com.iona.demo; import javax.jws.*; import javax.xml.ws.*; import javax.jws.soap.*; import javax.jws.soap.SOAPBinding.*; import javax.jws.WebParam.*; @WebService(targetNamespace="http://demo.iona.com", name="quoteReporter") @SOAPBinding(style=Style.RPC, use=Use.LITERAL) public interface quoteReporter { @WebMethod(operationName="getStockQuote") @RequestWrapper(targetNamespace="http://demo.iona.com/types", className="java.lang.String") @ResponseWrapper(targetNamespace="http://demo.iona.com/types", className="org.eric.demo.Quote") @WebResult(targetNamespace="http://demo.iona.com/types", name="updatedQuote") public Quote getQuote( @WebParam(targetNamespace="http://demo.iona.com/types", name="stockTicker", mode=Mode.IN) String ticker ); }