このコンテンツは選択した言語では利用できません。

22.3. Annotating the Code

22.3.1. Overview of JAX-WS Annotations

The JAX-WS annotations 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

Note

Most of the annotations have sensible defaults and it is not necessary to provide values for them. However, the more information you provide in the annotations, the better your service definition is specified. A well-specified service definition increases the likelihood that all parts of a distributed application will work together.

22.3.2. Required Annotations

Overview

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

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 properties described in Table 22.1, “@WebService Properties”

Table 22.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 where 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 URL where the service's WSDL contract is stored. This must be specified using a relative URL. The default is the URL where the service is deployed.
endpointInterface	Specifies the full name of the SEI that the implementation class implements. This property is only specified 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.

Note

It is not necessary to provide values for any of the @WebService annotation's properties. However, it is recommended that you provide as much information as you can.

Annotating the SEI

The SEI requires that you add the @WebService annotation. Because the SEI is the contract that defines the service, you should specify as much detail as possible about the service in the @WebService annotation's properties.

Example 22.3, “Interface with the @WebService Annotation” shows the interface defined in Example 22.1, “Simple SEI” with the @WebService annotation.

Example 22.3. Interface with the @WebService Annotation

package com.fusesource.demo;

import javax.jws.*;

@WebService(name="quoteUpdater", 1
            targetNamespace="http:\\demos.redhat.com", 2
	        serviceName="updateQuoteService", 3
            wsdlLocation="http:\\demos.redhat.com\quoteExampleService?wsdl", 4
            portName="updateQuotePort") 5
public interface quoteReporter
{
  public Quote getQuote(String ticker);
}

The @WebService annotation in Example 22.3, “Interface with the @WebService Annotation” does the following:

1: Specifies that the value of the name attribute of the wsdl:portType element defining the service interface is quoteUpdater.
2: Specifies that the target namespace of the service is http:\\demos.redhat.com.
3: Specifies that the value of the name of the wsdl:service element defining the published service is updateQuoteService.
4: Specifies that the service will publish its WSDL contract at http:\\demos.redhat.com\quoteExampleService?wsdl.
5: Specifies that the value of the name attribute of the wsdl:port element defining the endpoint exposing the service is updateQuotePort.

Annotating the service implementation

In addition to annotating the SEI with the @WebService annotation, you also must 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 22.4, “Annotated Service Implementation Class” the property must be set to the full name of the SEI.

Example 22.4. Annotated Service Implementation Class

package org.eric.demo;

import javax.jws.*;

@WebService(endpointInterface="com.fusesource.demo.quoteReporter")
public class stockQuoteReporter implements quoteReporter
{
public Quote getQuote(String ticker)
  {
  ...
  }
}

22.3.3. Optional Annotations

Abstract

While the @WebService annotation is sufficient for service enabling a Java interface or a Java class, it does not fully describe how the service will be exposed as a service provider. 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.

The more details you provide in the SEI the easier it is for developers to implement applications that can use the functionality it defines. It also makes the WSDL documents generated by the tools more specific.

22.3.3.1. Defining the Binding Properties with Annotations

Overview

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. Some of the settings, such as the parameter style, can restrict how you implement a method. These settings can also effect which annotations can be used when annotating method parameters.

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

Table 22.2, “@SOAPBinding Properties” shows the properties for the @SOAPBinding annotation.

Table 22.2. @SOAPBinding Properties
Property	Values	Description
style	`Style.DOCUMENT` (default) `Style.RPC`	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 appears 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	`Use.LITERAL` (default) `Use.ENCODED`^[a]	Specifies how the data of the SOAP message is streamed.
parameterStyle ^[b]	`ParameterStyle.BARE` `ParameterStyle.WRAPPED` (default)	Specifies how the method parameters, which correspond to message parts in a WSDL contract, are placed into the SOAP message body. If `BARE` is specified, each parameter is placed into the message body as a child element of the message root. If `WRAPPED` is specified, all of the input parameters are wrapped into a single element on a request message and all of the output parameters are wrapped into a single element in the response message.
^[a] `Use.ENCODED` is not currently supported. ^[b] If you set the style to `RPC` you must use the `WRAPPED` parameter style.

Document bare style parameters

Document bare style is the most direct mapping between Java code and the resulting XML representation of the service. When using this style, the schema types are generated directly from the input and output parameters defined in the operation's parameter list.

You specify you want to use bare document\literal style by using the @SOAPBinding annotation with its style property set to Style.DOCUMENT, and its parameterStyle property set to ParameterStyle.BARE.

To ensure that an operation does not violate the restrictions of using document style when using bare parameters, your operations must adhere to the following conditions:

The operation must have no more than one input or input/output parameter.
If the operation has a return type other than void, it must not have any output or input/output parameters.
If the operation has a return type of void, it must have no more than one output or input/output parameter.

Note

Any parameters that are placed in the SOAP header using the @WebParam annotation or the @WebResult annotation are not counted against the number of allowed parameters.

Document wrapped parameters

Document wrapped style allows a more RPC like mapping between the Java code and the resulting XML representation of the service. When using this style, the parameters in the method's parameter list are wrapped into a single element by the binding. The disadvantage of this is that it introduces an extra-layer of indirection between the Java implementation and how the messages are placed on the wire.

To specify that you want to use wrapped document\literal style use the @SOAPBinding annotation with its style property set to Style.DOCUMENT, and its parameterStyle property set to ParameterStyle.WRAPPED.

You have some control over how the wrappers are generated by using the the section called “The @RequestWrapper annotation” annotation and the the section called “The @ResponseWrapper annotation” annotation.

Example

Example 22.5, “Specifying a Document Bare SOAP Binding with the SOAP Binding Annotation” shows an SEI that uses document bare SOAP messages.

Example 22.5. Specifying a Document Bare SOAP Binding with the SOAP Binding Annotation

package org.eric.demo;

import javax.jws.*;
import javax.jws.soap.*;
import javax.jws.soap.SOAPBinding.*;

@WebService(name="quoteReporter")
@SOAPBinding(parameterStyle=ParameterStyle.BARE)
public interface quoteReporter
{
  ...
}

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

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 22.3, “@WebMethod Properties” describes the properties of the @WebMethod annotation.

Table 22.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 22.4, “@RequestWrapper Properties” describes the properties of the @RequestWrapper annotation.

Table 22.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 the section called “The @WebMethod annotation” 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.

Note

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 22.5, “@ResponseWrapper Properties” describes the properties of the @ResponseWrapper annotation.

Table 22.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 the section called “The @WebMethod annotation” 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.

Note

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 22.6, “@WebFault Properties” describes the properties of the @WebFault annotation.

Table 22.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 22.6, “SEI with Annotated Methods” shows an SEI with its methods annotated.

Example 22.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.redhat.com/types", 
                  className="java.lang.String")
  @ResponseWrapper(targetNamespace="http://demo.redhat.com/types", 
                   className="org.eric.demo.Quote")
  public Quote getQuote(String ticker);
}

22.3.3.3. Defining Parameter Properties with Annotations

Overview

The method parameters in the SEI correspond 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 of 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 22.7, “@WebParam Properties” describes the properties of the @WebParam annotation.

Table 22.7. @WebParam Properties
Property	Values	Description
name		Specifies the name of the parameter as it appears in the generated WSDL document. For RPC bindings, this is the name of the `wsdl:part` representing the parameter. For document bindings, this is the local name of the XML element representing the parameter. Per the JAX-WS specification, the default is `argN`, where N is replaced with the zero-based argument index (i.e., arg0, arg1, etc.).
targetNamespace		Specifies the namespace for the parameter. It is only used with document bindings where the parameter maps to an XML element. The default is to use the service's namespace.
mode	`Mode.IN` (default)^[a] `Mode.OUT` `Mode.INOUT`	Specifies the direction of the parameter.
header	`false` (default) `true`	Specifies if the parameter is passed as part of the SOAP header.
partName		Specifies the value of the `name` attribute of the `wsdl:part` element for the parameter. This property is used for document style SOAP bindings.
^[a] Any parameter that implements the `Holder` interface is mapped to `Mode.INOUT` by default.

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 wsdl:part that is generated for the method's return value.

Table 22.8, “@WebResult Properties” describes the properties of the @WebResult annotation.

Table 22.8. @WebResult Properties
Property	Description
name	Specifies the name of the return value as it appears in the generated WSDL document. For RPC bindings, this is the name of the `wsdl:part` representing the return value. For document bindings, this is the local name of the XML element representing the return value. The default value is `return`.
targetNamespace	Specifies the namespace for the return value. It is only used with document bindings where the return value maps to an XML element. The default is to use the service's namespace.
header	Specifies if the return value is passed as part of the SOAP header.
partName	Specifies the value of the `name` attribute of the `wsdl:part` element for the return value. This property is used for document style SOAP bindings.

Example

Example 22.7, “Fully Annotated SEI” shows an SEI that is fully annotated.

Example 22.7. Fully Annotated SEI

package com.fusesource.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.redhat.com", 
            name="quoteReporter")
@SOAPBinding(style=Style.RPC, use=Use.LITERAL)
public interface quoteReporter
{
  @WebMethod(operationName="getStockQuote")
  @RequestWrapper(targetNamespace="http://demo.redhat.com/types", 
                  className="java.lang.String")
  @ResponseWrapper(targetNamespace="http://demo.redhat.com/types", 
                   className="org.eric.demo.Quote")
  @WebResult(targetNamespace="http://demo.redhat.com/types", 
             name="updatedQuote")
  public Quote getQuote(
                        @WebParam(targetNamespace="http://demo.redhat.com/types", 
                                  name="stockTicker",
                                  mode=Mode.IN)
                        String ticker
  );
}

22.3.4. Apache CXF Annotations

22.3.4.1. WSDL Documentation

@WSDLDocumentation annotation

The @WSDLDocumentation annotation is defined by the org.apache.cxf.annotations.WSDLDocumentation interface. It can be placed on the SEI or the SEI methods.

This annotation enables you to add documentation, which will then appear within wsdl:documentation elements after the SEI is converted to WSDL. By default, the documentation elements appear inside the port type, but you can specify the placement property to make the documentation appear at other locations in the WSDL file. Table 22.9, “@WSDLDocumentation properties” shows the properties supported by the @WSDLDocumentation annotation.

Table 22.9. @WSDLDocumentation properties
Property	Description
`value`	(Required) A string containing the documentation text.
`placement`	(Optional) Specifies where in the WSDL file this documentation is to appear. For the list of possible placement values, see the section called “Placement in the WSDL contract”.
`faultClass`	(Optional) If the placement is set to be `FAULT_MESSAGE`, `PORT_TYPE_OPERATION_FAULT`, or `BINDING_OPERATION_FAULT`, you must also set this property to the Java class that represents the fault.

@WSDLDocumentationCollection annotation

The @WSDLDocumentationCollection annotation is defined by the org.apache.cxf.annotations.WSDLDocumentationCollection interface. It can be placed on the SEI or the SEI methods.

This annotation is used to insert multiple documentation elements at a single placement location or at various placement locations.

Placement in the WSDL contract

To specify where the documentation should appear in the WSDL contract, you can specify the placement property, which is of type WSDLDocumentation.Placement. The placement can have one of the following values:

WSDLDocumentation.Placement.BINDING
WSDLDocumentation.Placement.BINDING_OPERATION
WSDLDocumentation.Placement.BINDING_OPERATION_FAULT
WSDLDocumentation.Placement.BINDING_OPERATION_INPUT
WSDLDocumentation.Placement.BINDING_OPERATION_OUTPUT
WSDLDocumentation.Placement.DEFAULT
WSDLDocumentation.Placement.FAULT_MESSAGE
WSDLDocumentation.Placement.INPUT_MESSAGE
WSDLDocumentation.Placement.OUTPUT_MESSAGE
WSDLDocumentation.Placement.PORT_TYPE
WSDLDocumentation.Placement.PORT_TYPE_OPERATION
WSDLDocumentation.Placement.PORT_TYPE_OPERATION_FAULT
WSDLDocumentation.Placement.PORT_TYPE_OPERATION_INPUT
WSDLDocumentation.Placement.PORT_TYPE_OPERATION_OUTPUT
WSDLDocumentation.Placement.SERVICE
WSDLDocumentation.Placement.SERVICE_PORT
WSDLDocumentation.Placement.TOP

Example of @WSDLDocumentation

Example 22.8, “Using @WSDLDocumentation” shows how to add a @WSDLDocumentation annotation to the SEI and to one of its methods.

Example 22.8. Using @WSDLDocumentation

@WebService
@WSDLDocumentation("A very simple example of an SEI")
public interface HelloWorld {
    @WSDLDocumentation("A traditional form of greeting")
    String sayHi(@WebParam(name = "text") String text);
}

When WSDL, shown in Example 22.9, “WSDL generated with documentation”, is generated from the SEI in Example 22.8, “Using @WSDLDocumentation”, the default placements of the documentation elements are, respectively, PORT_TYPE and PORT_TYPE_OPERATION.

Example 22.9. WSDL generated with documentation

<wsdl:definitions ... >
  ...
  <wsdl:portType name="HelloWorld">
 <wsdl:documentation>A very simple example of an SEI</wsdl:documentation>
    <wsdl:operation name="sayHi">
 <wsdl:documentation>A traditional form of greeting</wsdl:documentation>
      <wsdl:input name="sayHi" message="tns:sayHi">
    </wsdl:input>
      <wsdl:output name="sayHiResponse" message="tns:sayHiResponse">
    </wsdl:output>
    </wsdl:operation>
  </wsdl:portType>
  ...
</wsdl:definitions>

Example of @WSDLDocumentationCollection

Example 22.10, “Using @WSDLDocumentationCollection” shows how to add a @WSDLDocumentationCollection annotation to an SEI.

Example 22.10. Using @WSDLDocumentationCollection

@WebService
@WSDLDocumentationCollection(
    {
        @WSDLDocumentation("A very simple example of an SEI"),
        @WSDLDocumentation(value = "My top level documentation",
                           placement = WSDLDocumentation.Placement.TOP),
        @WSDLDocumentation(value = "Binding documentation",
                           placement = WSDLDocumentation.Placement.BINDING)
    }
)
public interface HelloWorld {
    @WSDLDocumentation("A traditional form of Geeky greeting")
    String sayHi(@WebParam(name = "text") String text);
}

22.3.4.2. Schema Validation of Messages

@SchemaValidation annotation

The @SchemaValidation annotation is defined by the org.apache.cxf.annotations.SchemaValidation interface. It can be placed on the SEI and on individual SEI methods.

This annotation turns on schema validation of the XML messages sent to this endpoint. This can be useful for testing purposes, when you suspect there is a problem with the format of incoming XML messages. By default, validation is disabled, because it has a significant impact on performance.

Schema validation type

The schema validation behaviour is controlled by the type parameter, whose value is an enumeration of org.apache.cxf.annotations.SchemaValidation.SchemaValidationType type. Table 22.10, “Schema Validation Type Values” shows the list of available validation types.

Table 22.10. Schema Validation Type Values
Type	Description
`IN`	Apply schema validation to incoming messages on client and server.
`OUT`	Apply schema validation to outgoing messages on client and server.
`BOTH`	Apply schema validation to both incoming and outgoing messages on client and server.
`NONE`	All schema validation is disabled.
`REQUEST`	Apply schema validation to Request messages—that is, causing validation to be applied to outgoing client messages and to incoming server messages.
`RESPONSE`	Apply schema validation to Response messages—that is, causing validation to be applied to incoming client messages, and outgoing server messages.

Example

The following example shows how to enable schema validation of messages for endpoints based on the MyService SEI. Note how the annotation can be applied to the SEI as a whole, as well as to individual methods in the SEI.

@WebService
@SchemaValidation(type = SchemaValidationType.BOTH)
public interface MyService {
    Foo validateBoth(Bar data);
 
    @SchemaValidation(type = SchemaValidationType.NONE)
    Foo validateNone(Bar data);
 
    @SchemaValidation(type = SchemaValidationType.IN)
    Foo validateIn(Bar data);
 
    @SchemaValidation(type = SchemaValidationType.OUT)
    Foo validateOut(Bar data);
 
    @SchemaValidation(type = SchemaValidationType.REQUEST)
    Foo validateRequest(Bar data);
 
    @SchemaValidation(type = SchemaValidationType.RESPONSE)
    Foo validateResponse(Bar data);
}

22.3.4.3. Specifying the Data Binding

@DataBinding annotation

The @DataBinding annotation is defined by the org.apache.cxf.annotations.DataBinding interface. It is placed on the SEI.

This annotation is used to associate a data binding with the SEI, replacing the default JAXB data binding. The value of the @DataBinding annotation must be the class that provides the data binding, ClassName.class.

Supported data bindings

The following data bindings are currently supported by Apache CXF:

org.apache.cxf.jaxb.JAXBDataBinding
(Default) The standard JAXB data binding.
org.apache.cxf.sdo.SDODataBinding
The Service Data Objects (SDO) data binding is based on the Apache Tuscany SDO implementation. If you want to use this data binding in the context of a Maven build, you need to add a dependency on the cxf-rt-databinding-sdo artifact.
org.apache.cxf.aegis.databinding.AegisDatabinding
If you want to use this data binding in the context of a Maven build, you need to add a dependency on the cxf-rt-databinding-aegis artifact.
org.apache.cxf.xmlbeans.XmlBeansDataBinding
If you want to use this data binding in the context of a Maven build, you need to add a dependency on the cxf-rt-databinding-xmlbeans artifact.
org.apache.cxf.databinding.source.SourceDataBinding
This data binding belongs to the Apache CXF core.
org.apache.cxf.databinding.stax.StaxDataBinding
This data binding belongs to the Apache CXF core.

Example

Example 22.11, “Setting the data binding” shows how to associate the SDO binding with the HelloWorld SEI

Example 22.11. Setting the data binding

@WebService
@DataBinding(org.apache.cxf.sdo.SDODataBinding.class)
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}

22.3.4.4. Compressing Messages

@GZIP annotation

The @GZIP annotation is defined by the org.apache.cxf.annotations.GZIP interface. It is placed on the SEI.

Enables GZIP compression of messages. GZIP is a negotiated enhancement. That is, an initial request from a client will not be gzipped, but an Accept header will be added and, if the server supports GZIP compression, the response will be gzipped and any subsequent requests will be also.

Table 22.11, “@GZIP Properties” shows the optional properties supported by the @GZIP annotation.

Table 22.11. @GZIP Properties
Property	Description
`threshold`	Messages smaller than the size specified by this property are not gzipped. Default is -1 (no limit).

@FastInfoset

The @FastInfoset annotation is defined by the org.apache.cxf.annotations.FastInfoset interface. It is placed on the SEI.

Enables the use of FastInfoset format for messages. FastInfoset is a binary encoding format for XML, which aims to optimize both the message size and the processing performance of XML messages. For more details, see the following Sun article on Fast Infoset.

FastInfoset is a negotiated enhancement. That is, an initial request from a client will not be in FastInfoset format, but an Accept header will be added and, if the server supports FastInfoset, the response will be in FastInfoset and any subsequent requests will be also.

Table 22.12, “@FastInfoset Properties” shows the optional properties supported by the @FastInfoset annotation.

Table 22.12. @FastInfoset Properties
Property	Description
`force`	A boolean property that forces the use of FastInfoset format, instead of negotiating. When `true`, force the use of FastInfoset format; otherwise, negotiate. Default is `false`.

Example of @GZIP

Example 22.12, “Enabling GZIP” shows how to enable GZIP compression for the HelloWorld SEI.

Example 22.12. Enabling GZIP

@WebService
@GZIP
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}

Exampe of @FastInfoset

Example 22.13, “Enabling FastInfoset” shows how to enable the FastInfoset format for the HelloWorld SEI.

Example 22.13. Enabling FastInfoset

@WebService
@FastInfoset
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}

22.3.4.5. Enable Logging on an Endpoint

@Logging annotation

The @Logging annotation is defined by the org.apache.cxf.annotations.Logging interface. It is placed on the SEI.

This annotation enables logging for all endpoints associated with the SEI. Table 22.13, “@Logging Properties” shows the optional properties you can set in this annotation.

Table 22.13. @Logging Properties
Property	Description
`limit`	Specifies the size limit, beyond which the message is truncated in the logs. Default is 64K.
`inLocation`	Specifies the location to log incoming messages. Can be either `<stderr>`, `<stdout>`, `<logger>`, or a filename. Default is `<logger>`.
`outLocation`	Specifies the location to log outgoing messages. Can be either `<stderr>`, `<stdout>`, `<logger>`, or a filename. Default is `<logger>`.

Example

Example 22.14, “Logging configuration using annotations” shows how to enable logging for the HelloWorld SEI, where incoming messages are sent to <stdout> and outgoing messages are sent to <logger>.

Example 22.14. Logging configuration using annotations

@WebService
@Logging(limit=16000, inLocation="<stdout>")
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}

22.3.4.6. Adding Properties and Policies to an Endpoint

Abstract

Both properties and policies can be used to associate configuration data with an endpoint. The essential difference between them is that properties are a Apache CXF specific configuration mechanism whereas policies are a standard WSDL configuration mechanism. Policies typically originate from WS specifications and standards and they are normally set by defining wsdl:policy elements that appear in the WSDL contract. By contrast, properties are Apache CXF-specific and they are normally set by defining jaxws:properties elements in the Apache CXF Spring configuration file.

It is also possible, however, to define property settings and WSDL policy settings in Java using annotations, as described here.

22.3.4.6.1. Adding properties

@EndpointProperty annotation

The @EndpointProperty annotation is defined by the org.apache.cxf.annotations.EndpointProperty interface. It is placed on the SEI.

This annotation adds Apache CXF-specific configuration settings to an endpoint. Endpoint properties can also be specified in a Spring configuration file. For example, to configure WS-Security on an endpoint, you could add endpoint properties using the jaxws:properties element in a Spring configuration file as follows:

<beans xmlns="http://www.springframework.org/schema/beans"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:jaxws="http://cxf.apache.org/jaxws"
   ... >

   <jaxws:endpoint 
      id="MyService"
      address="https://localhost:9001/MyService" 
      serviceName="interop:MyService"
      endpointName="interop:MyServiceEndpoint"
      implementor="com.foo.MyService">
        
      <jaxws:properties>
         <entry key="ws-security.callback-handler" value="interop.client.UTPasswordCallback"/>
         <entry key="ws-security.signature.properties" value="etc/keystore.properties"/>
         <entry key="ws-security.encryption.properties" value="etc/truststore.properties"/>
         <entry key="ws-security.encryption.username" value="useReqSigCert"/>
      </jaxws:properties> 
     
   </jaxws:endpoint> 
</beans>

Alternatively, you could specify the preceding configuration settings in Java by adding @EndpointProperty annotations to the SEI, as shown in Example 22.15, “Configuring WS-Security Using @EndpointProperty Annotations”.

Example 22.15. Configuring WS-Security Using @EndpointProperty Annotations

@WebService
@EndpointProperty(name="ws-security.callback-handler" value="interop.client.UTPasswordCallback")
@EndpointProperty(name="ws-security.signature.properties" value="etc/keystore.properties")
@EndpointProperty(name="ws-security.encryption.properties" value="etc/truststore.properties")
@EndpointProperty(name="ws-security.encryption.username" value="useReqSigCert")
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}

@EndpointProperties annotation

The @EndpointProperties annotation is defined by the org.apache.cxf.annotations.EndpointProperties interface. It is placed on the SEI.

This annotation provides a way of grouping multiple @EndpointProperty annotations into a list. Using @EndpointProperties, it is possible to re-write Example 22.15, “Configuring WS-Security Using @EndpointProperty Annotations” as shown in Example 22.16, “Configuring WS-Security Using an @EndpointProperties Annotation”.

Example 22.16. Configuring WS-Security Using an @EndpointProperties Annotation

@WebService
@EndpointProperties(
  {
  @EndpointProperty(name="ws-security.callback-handler" value="interop.client.UTPasswordCallback"),
  @EndpointProperty(name="ws-security.signature.properties" value="etc/keystore.properties"),
  @EndpointProperty(name="ws-security.encryption.properties" value="etc/truststore.properties"),
  @EndpointProperty(name="ws-security.encryption.username" value="useReqSigCert")
})
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}

22.3.4.6.2. Adding policies

@Policy annotation

The @Policy annotation is defined by the org.apache.cxf.annotations.Policy interface. It can be placed on the SEI or the SEI methods.

This annotation is used to associate a WSDL policy with an SEI or an SEI method. The policy is specified by providing a URI that references an XML file containing a standard wsdl:policy element. If a WSDL contract is to be generated from the SEI (for example, using the java2ws command-line tool), you can specify whether or not you want to include this policy in the WSDL.

Table 22.14, “@Policy Properties” shows the properties supported by the @Policy annotation.

Table 22.14. @Policy Properties
Property	Description
`uri`	(Required) The location of the file containing the policy definition.
`includeInWSDL`	(Optional) Whether to include the policy in the generated contract, when generating WSDL. Default is `true`.
`placement`	(Optional) Specifies where in the WSDL file this documentation is to appear. For the list of possible placement values, see the section called “Placement in the WSDL contract”.
`faultClass`	(Optional) If the placement is set to be `BINDING_OPERATION_FAULT` or `PORT_TYPE_OPERATION_FAULT`, you must also set this property to specify which fault this policy applies to. The value is the Java class that represents the fault.

@Policies annotation

The @Policies annotation is defined by the org.apache.cxf.annotations.Policies interface. It can be placed on the SEI or thse SEI methods.

This annotation provides a way of grouping multiple @Policy annotations into a list.

Placement in the WSDL contract

To specify where the policy should appear in the WSDL contract, you can specify the placement property, which is of type Policy.Placement. The placement can have one of the following values:

Policy.Placement.BINDING
Policy.Placement.BINDING_OPERATION
Policy.Placement.BINDING_OPERATION_FAULT
Policy.Placement.BINDING_OPERATION_INPUT
Policy.Placement.BINDING_OPERATION_OUTPUT
Policy.Placement.DEFAULT
Policy.Placement.PORT_TYPE
Policy.Placement.PORT_TYPE_OPERATION
Policy.Placement.PORT_TYPE_OPERATION_FAULT
Policy.Placement.PORT_TYPE_OPERATION_INPUT
Policy.Placement.PORT_TYPE_OPERATION_OUTPUT
Policy.Placement.SERVICE
Policy.Placement.SERVICE_PORT

Example of @Policy

The following example shows how to associate WSDL policies with the HelloWorld SEI and how to associate a policy with the sayHi method. The policies themselves are stored in XML files in the file system, under the annotationpolicies directory.

@WebService
@Policy(uri = "annotationpolicies/TestImplPolicy.xml",
        placement = Policy.Placement.SERVICE_PORT),
@Policy(uri = "annotationpolicies/TestPortTypePolicy.xml", 
        placement = Policy.Placement.PORT_TYPE)
public interface HelloWorld {
    @Policy(uri = "annotationpolicies/TestOperationPTPolicy.xml", 
            placement = Policy.Placement.PORT_TYPE_OPERATION),
    String sayHi(@WebParam(name = "text") String text);
}

Example of @Policies

You can use the @Policies annotation to group multiple @Policy annotations into a list, as shown in the following example:

@WebService
@Policies({
    @Policy(uri = "annotationpolicies/TestImplPolicy.xml",
            placement = Policy.Placement.SERVICE_PORT),
    @Policy(uri = "annotationpolicies/TestPortTypePolicy.xml", 
            placement = Policy.Placement.PORT_TYPE)
})
public interface HelloWorld {
    @Policy(uri = "annotationpolicies/TestOperationPTPolicy.xml", 
            placement = Policy.Placement.PORT_TYPE_OPERATION),
    String sayHi(@WebParam(name = "text") String text);
}

このコンテンツは選択した言語では利用できません。

22.3. Annotating the Code

22.3.1. Overview of JAX-WS Annotations

22.3.2. Required Annotations

Overview

The @WebService annotation

Annotating the SEI

Annotating the service implementation

22.3.3. Optional Annotations

22.3.3.1. Defining the Binding Properties with Annotations

Overview

The @SOAPBinding annotation

Document bare style parameters

Document wrapped parameters

Example

22.3.3.2. Defining Operation Properties with Annotations

Overview

The @WebMethod annotation

The @RequestWrapper annotation

The @ResponseWrapper annotation

The @WebFault annotation

The @Oneway annotation

Example

22.3.3.3. Defining Parameter Properties with Annotations

Overview

The @WebParam annotation

The @WebResult annotation

Example

22.3.4. Apache CXF Annotations

22.3.4.1. WSDL Documentation

@WSDLDocumentation annotation

@WSDLDocumentationCollection annotation

Placement in the WSDL contract

Example of @WSDLDocumentation

Example of @WSDLDocumentationCollection

22.3.4.2. Schema Validation of Messages

@SchemaValidation annotation

Schema validation type

Example

22.3.4.3. Specifying the Data Binding

@DataBinding annotation

Supported data bindings

Example

22.3.4.4. Compressing Messages

@GZIP annotation

@FastInfoset

Example of @GZIP

Exampe of @FastInfoset

22.3.4.5. Enable Logging on an Endpoint

@Logging annotation

Example

22.3.4.6. Adding Properties and Policies to an Endpoint

22.3.4.6.1. Adding properties

@EndpointProperty annotation

@EndpointProperties annotation

22.3.4.6.2. Adding policies

@Policy annotation

@Policies annotation

Placement in the WSDL contract

Example of @Policy

Example of @Policies

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

多様性を受け入れるオープンソースの強化

会社概要

Red Hat legal and privacy links

Red Hat legal and privacy links