SupportConsoleDevelopersStart a trialContact

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
PropertyDescription
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
PropertyValuesDescription
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
PropertyDescription
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
PropertyDescription
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
PropertyDescription
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
PropertyDescription
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
PropertyValuesDescription
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
PropertyDescription
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
PropertyDescription
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
TypeDescription
INApply schema validation to incoming messages on client and server.
OUTApply schema validation to outgoing messages on client and server.
BOTHApply schema validation to both incoming and outgoing messages on client and server.
NONEAll schema validation is disabled.
REQUESTApply schema validation to Request messages—that is, causing validation to be applied to outgoing client messages and to incoming server messages.
RESPONSEApply 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
PropertyDescription
thresholdMessages 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
PropertyDescription
forceA 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
PropertyDescription
limitSpecifies the size limit, beyond which the message is truncated in the logs. Default is 64K.
inLocationSpecifies the location to log incoming messages. Can be either <stderr>, <stdout>, <logger>, or a filename. Default is <logger>.
outLocationSpecifies 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
PropertyDescription
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);
}
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.