JAX-WS annotations

Java™ API for XML-Based Web Services (JAX-WS) relies on the use of annotations to specify metadata associated with web services implementations and to simplify the development of web services. Annotations describe how a server-side service implementation is accessed as a web service or how a client-side Java class accesses web services.

The JAX-WS programming standard introduces support for annotating Java classes with metadata that is used to define a service endpoint application as a web service and how a client can access the web service. JAX-WS supports the use of annotations based on the Metadata Facility for the Java Programming Language (Java Specification Request (JSR) 175) specification, the Web Services Metadata for the Java Platform (JSR 181) specification and annotations defined by the JAX-WS 2.0 and later (JSR 224) specification which includes JAXB annotations. Using annotations from the JSR 181 standard, you can simply annotate the service implementation class or the service interface and now the application is enabled as a web service. Using annotations within the Java source simplifies development and deployment of web services by defining some of the additional information that is typically obtained from deployment descriptor files, WSDL files, or mapping metadata from XML and WSDL into the source artifacts.

Use annotations to configure bindings, handler chains, set names of portType, service and other WSDL parameters. Annotations are used in mapping Java to WSDL and schema, and at runtime to control how the JAX-WS runtime processes and responds to web service invocations.

For JAX-WS web services, the use of the webservices.xml deployment descriptor is optional because you can use annotations to specify all of the information that is contained within the deployment descriptor file. You can use the deployment descriptor file to augment or override existing JAX-WS annotations. Any information that you define in the webservices.xml deployment descriptor overrides any corresponding information that is specified by annotations.

Starting with WebSphere® Application Server Version 7.0 and later, Java EE 5 application modules (Web application modules version 2.5 or later, or EJB modules version 3.0 or later) are scanned for annotations to identify JAX-WS services and clients. However, pre-Java EE 5 application modules (web application modules version 2.4 or before, or EJB modules version 2.1 or before) are not scanned for JAX-WS annotations, by default, for performance considerations.

In the Version 6.1 Feature Pack for Web Services, the default behavior is to scan pre- Java Platform, Enterprise Edition (Java EE) 5 web application modules to identify JAX-WS services and to scan pre-Java EE 5 web application modules and EJB modules for service clients during application installation. Because the default behavior for WebSphere Application Server Version 7.0 and later is to not scan pre-Java EE 5 modules for annotations during application installation or server startup, to preserve backward compatability with the feature pack from previous releases, you must configure one of the following properties:
  • You can set the UseWSFEP61ScanPolicy property in the META-INF/MANIFEST.MF of a WAR file or EJB module to true. For example:
    Manifest-Version: 1.0
UseWSFEP61ScanPolicy: true
    When this property is set to true in the META-INF/MANIFEST.MF file of the module, the module is scanned for JAX-WS annotations regardless of the Java EE version of the module. The default value is false and when the default value is in effect, JAX-WS annotations are only supported in modules whose version is Java EE 5 or later.
  • You can set the com.ibm.websphere.webservices.UseWSFEP61ScanPolicy custom Java virtual machine (JVM) property using the administrative console. See the JVM custom properties documentation for the correct navigation path to use. To request annotation scanning in all modules regardless of their Java EE version, set the custom property com.ibm.websphere.webservices.UseWSFEP61ScanPolicy to true. You must change the setting on each server that requires a change in the default behavior.
If the property is set within the META-INF/MANIFEST.MF file of the module, this setting takes precedence over the server's custom JVM property. When using either property, you must establish the desired annotation scanning behavior before the application is installed. You cannot dynamically change the scanning behavior once an application is installed. If changes to the behavior are required after your application is installed, you must first uninstall the application, specify the desired scanning behavior using the appropriate property and then install the application again. When federating nodes that have the com.ibm.websphere.webservices.UseWSFEP61ScanPolicy set to true in the configuration of the servers contained within the node, this property does not affect the deployment manager. You must set the property to true on the deployment manager before the node is federated to preserve the behavior as it was on the node before federation.
[z/OS]
Avoid trouble: If this JVM property is being used on the z/OS® platform, it must be set in both the servant and control regions of the server.
Avoid trouble: When federating nodes that have the com.ibm.websphere.webservices.UseWSFEP61ScanPolicy set to true in the configuration of the servers contained within the node, this does not affect the deployment manager. You must set the property to true on the deployment manager before the node is federated if you wish to preserve the behavior as it was on the node before federation.
Annotations supported by JAX-WS are listed in the following table. The target for annotations is applicable for these Java objects:
  • types such as a Java class, enum or interface
  • methods
  • fields representing local instance variables within a Java class
  • parameters within a Java method
Table 1. Web services Metadata Annotations (JSR 181) . Describes the supported web services metadata annotations and their associated properties.
Annotation class Annotation Properties
javax.jws. WebService The @WebService annotation marks a Java class as implementing a Web service or marks a service endpoint interface (SEI) as implementing a web service interface.
Important:
  • A Java class that implements a web service must specify either the @WebService or @WebServiceProvider annotation. Both annotations cannot be present. This annotation is applicable on a client or server SEI or a server endpoint implementation class.
  • If the annotation references an SEI through the endpointInterface attribute, the SEI must also be annotated with the @WebService annotation.
  • See the exposing methods in SEI-based JAX-WS web services information to learn about best practices for using the @WebService and @WebMethod annotations on a service endpoint implementation to specify Java methods that you want to expose as JAX-WS web services.
  • Annotation target: Type
  • Properties:
    - name
    The name of the wsdl:portType. The default value is the unqualified name of the Java class or interface. (String)
    - targetNamespace
    Specifies the XML namespace of the WSDL and XML elements generated from the web service. The default value is the namespace mapped from the package name containing the web service. (String)
    - serviceName
    Specifies the service name of the web service: wsdl:service. The default value is the simple name of the Java class + Service. (String)
    - endpointInterface
    Specifies the qualified name of the service endpoint interface that defines the services' abstract web service contract. If specified, the service endpoint interface is used to determine the abstract WSDL contract. (String)
    - portName
    The wsdl:portName. The default value is WebService.name +Port . (String)
    - wsdlLocation
    Specifies the web address of the WSDL document that defines the web service. The web address is either relative or absolute. (String)
javax.jws. WebMethod The @WebMethod annotation denotes a method that is a web service operation.

Apply this annotation to methods on a client or server Service Endpoint Interface (SEI) or a server endpoint implementation class.
  • Annotation target: Method
  • Properties:
    - operationName
    Specifies the name of the wsdl:operation matching this method. The default value is the name of Java method. (String)
    - action
    Defines the action for this operation. For SOAP bindings, this value determines the value of the SOAPAction header and must be explicitly set.
    - exclude
    Specifies whether to exclude a method from the web service. The default value is false. (Boolean)
javax.jws. Oneway The @Oneway annotation denotes a method as a web service one-way operation that only has an input message and no output message.

Apply this annotation to methods on a client or server Service Endpoint Interface (SEI) or a server endpoint implementation class.

  • Annotation target: Method
  • There are no properties on the Oneway annotation.
javax.jws. WebParam The @WebParam annotation customizes the mapping of an individual parameter to a web service message part and XML element.

Apply this annotation to methods on a client or server Service Endpoint Interface (SEI) or a server endpoint implementation class.
  • Annotation target: Parameter
  • Properties:
    - name
    The name of the parameter. If the operation is remote procedure call (RPC) style and the partName attribute is not specified, then this is the name of the wsdl:part attribute representing the parameter. If the operation is document style or the parameter maps to a header, then -name is the local name of the XML element representing the parameter. This attribute is required if the operation is document style, the parameter style is BARE, and the mode is OUT or INOUT. (String)
    - partName
    Defines the name of wsdl:part attribute representing this parameter. This is only used if the operation is RPC style, or the operation is document style and the parameter style is BARE. (String)
    - targetNamespace
    Specifies the XML namespace of the XML element for the parameter. Applies only for document bindings when the attribute maps to an XML element. The default value is the targetNamespace for the web service. (String)
    - mode
    The value represents the direction the parameter flows for this method. Valid values are IN, INOUT, and OUT. (String)
    - header
    Specifies whether the parameter is in a message header rather than a message body. The default value is false. (Boolean)
javax.jws. WebResult The @WebResult annotation customizes the mapping of a return value to a WSDL part or XML element.

Apply this annotation to methods on a client or server Service Endpoint Interface (SEI) or a server endpoint implementation class.
  • Annotation target: Method
  • Properties:
    - name
    Specifies the name of the return value as it is listed in the WSDL file and found in messages on the wire. For RPC bindings, this is the name of the wsdl:part attribute representing the return value. For document bindings, the -name parameter is the local name of the XML element representing the return value. The default value is return for RPC and DOCUMENT/WRAPPED bindings. The default value is the method name + Response for DOCUMENT/BARE bindings. (String)
    - targetNamespace
    Specifies the XML namespace for the return value. This parameter is only used if the operation is RPC style or if the operation is DOCUMENT style and the parameter style is BARE. (String)
    - header
    Specifies whether the result is carried in a header. The default value is false. (Boolean)
    - partName
    Specifies the part name for the result with RPC or DOCUMENT/BARE operations. The default value is @WebResult.name. (String)
javax.jws. HandlerChain The @HandlerChain annotation associates the web service with an externally defined handler chain.

You can only configure the server side handler by using the @HandlerChain annotation on the Service Endpoint Interface (SEI) or the server endpoint implementation class.

Use one of several ways to configure a client side handler. You can configure a client side handler by using the @HandlerChain annotation on the generated service class or SEI. Additionally, you can programmatically register your own implementation of the HandlerResolver interface on the Service, or programmatically set the handler chain on the Binding object.
  • Annotation target: Type
  • Properties:
    - file
    Specifies the location of the handler chain file. The file location is either an absolute java.net.URL in external form or a relative path from the class file. (String)
    - name
    Specifies the name of the handler chain in the configuration file. (String)
javax.jws. SOAPBinding The @SOAPBinding annotation specifies the mapping of the web service onto the SOAP message protocol.

Apply this annotation to a type or methods on a client or server Service Endpoint Interface (SEI) or a server endpoint implementation class.

The method level annotation is limited in what it can specify and is only used if the style property is DOCUMENT. If the method level annotation is not specified, the @SOAPBinding behavior from the type is used.
  • Annotation target: Type or Method
  • Properties:
    - style
    Defines encoding style for messages sent to and from the web service. The valid values are DOCUMENT and RPC. The default value is DOCUMENT. (String)
    - use
    Defines the formatting used for messages sent to and from the web service. The default value is LITERAL. ENCODED is not supported. (String)
    - parameterStyle
    Determines whether the method's parameters represent the entire message body or whether parameters are elements wrapped inside a top-level element named after the operation. Valid values are WRAPPED or BARE. You can only use the BARE value with DOCUMENT style bindings. The default value is WRAPPED. (String)

Table 2. JAX-WS Annotations (JSR 224) . Describes the supported JAX-WS annotations and their associated properties.
Annotation class Annotation Properties
javax.xml.ws. Action The @Action annotation specifies the WS-Addressing action that is associated with a web service operation.

When you use this annotation with a particular method, and generate the corresponding WSDL document, the WS-Addressing Action extension attribute is added to the input and output elements of the WSDL operation that corresponds to that method.

To add this attribute to the WSDL operation, you must also specify the @Addressing annotation on the server endpoint implementation class. If you do not want to use the @Addressing annotation you can supply your own WSDL document with the Action attribute already defined.
  • Annotation target: Method
  • Properties:
    - fault
    Specifies the array of FaultAction for the wsdl:fault of the operation. (String)
    - input
    Specifies the action for thewsdl:input of the operation. (String)
    - output
    Specifies the action for thewsdl:output of the operation. (String)
javax.xml.ws. BindingType The @BindingType annotation specifies the binding to use when publishing an endpoint of this type.

Apply this annotation to a server endpoint implementation class.

Important: You can use the @BindingType annotation on the JavaBeans endpoint implementation class to enable MTOM by specifying either javax.xml.ws.soap.SOAPBinding.SOAP11HTTP_MTOM_BINDING or javax.xml.ws.soap.SOAPBinding.SOAP12HTTP_MTOM_BINDING as the value for the annotation.
  • Annotation target: Type
  • Properties:
    - value
    Indicates the binding identifier web address. Valid values are javax.xml.ws.soap.SOAPBinding.SOAP11HTTP_BINDING, javax.xml.ws.soap.SOAPBinding.SOAP12HTTP_BINDING, and javax.xml.ws.http.HTTPBinding.HTTP2HTTP_BINDING. The default value is javax.xml.ws.soap.SOAPBinding.SOAP11HTTP_BINDING. (String)
javax.xml.ws. FaultAction The @FaultAction annotation specifies the WS-Addressing action that is added to a fault response.

This annotation must be contained within an @Action annotation.

When you use this annotation with a particular method, the WS-Addressing FaultAction extension attribute is added to the fault element of the WSDL operation that corresponds to that method.

To add this attribute to the WSDL operation, you must also specify the @Addressing annotation on the server endpoint implementation class. If you do not want to use the @Addressing annotation you can supply your own WSDL document with the Action attribute already defined.
  • Annotation target: Method
  • Properties:
    - value
    Specifies the action of the wsdl:fault of the operation. (String)
    - output
    Specifies the name of the exception class. (String)
    - className
    Specifies the name of the class representing the request wrapper. (String)
javax.xml.ws. RequestWrapper The @RequestWrapper annotation supplies the JAXB generated request wrapper bean, the element name, and the namespace for serialization and deserialization with the request wrapper bean that is used at runtime.

When starting with a Java object, this element is used to resolve overloading conflicts in document literal mode. Only the className attribute is required in this case.

Apply this annotation to methods on a client or server Service Endpoint Interface (SEI) or a server endpoint implementation class.
  • Annotation target: Method
  • Properties:
    - localName
    Specifies the local name of the XML schema element representing the request wrapper. The default value is the operationName as defined in javax.jws.WebMethod annotation. (String)
    - targetNamespace
    Specifies the XML namespace of the request wrapper method. The default value is the target namespace of the SEI. (String)
    - className
    Specifies the name of the class representing the request wrapper. (String)
    - partName
    Specifies the name of the wsdl:part attribute that represents the XML schema element for the RequestWrapper class. This property is applicable for JAX-WS 2.2 and later. (String)
javax.xml.ws. ResponseWrapper The @ResponseWrapper annotation supplies the JAXB generated response wrapper bean, the element name, and the namespace for serialization and deserialization with the response wrapper bean that is used at runtime.

When starting with a Java object, this element is used to resolve overloading conflicts in document literal mode. Only the className attribute is required in this case.

Apply this annotation to methods on a client or server Service Endpoint Interface (SEI) or a server endpoint implementation class.
  • Annotation target: Method
  • Properties:
    - localName
    Specifies the local name of the XML schema element representing the request wrapper. The default value is the operationName + Response. operationName is defined in javax.jws.WebMethod annotation. (String)
    - targetNamespace
    Specifies the XML namespace of the request wrapper method. The default value is the target namespace of the SEI. (String)
    - className
    Specifies the name of the class representing the response wrapper. (String)
    - partName
    Specifies the name of the wsdl:part attribute that represents the XML schema element for the ResponseWrapper class. This property is applicable for JAX-WS 2.2 and later. (String)
javax.xml.ws. RespectBinding The @RespectBinding annotation specifies whether the JAX-WS implementation must use the contents of the wsdl:binding for an endpoint.

When this annotation is specified, a check is performed to ensure all required WSDL extensibility elements with the enabled attribute set to true are supported.

Apply this annotation to methods on a server endpoint implementation class.
  • Annotation target: Method
  • Properties:
    - enabled
    Specifies whether the wsdl:binding must be used or not. The default value is true. (Boolean)
javax.xml.ws. ServiceMode The @ServiceMode annotation specifies whether a service provider needs to have access to an entire protocol message or just the message payload.
Important: The @ServiceMode annotation is only supported on classes that are annotated with the @WebServiceProvider annotation.
  • Annotation target: Type
  • Properties:
    - value
    Indicates whether the provider class accepts the payload of the message, PAYLOAD or the entire message MESSAGE. The default value is PAYLOAD. (String)
javax.xml.ws. soap.Addressing The @Addressing annotation specifies that this service wants to enable WS-Addressing support.

Apply this annotation to methods on a server endpoint implementation class.
  • Annotation target: Type
  • Properties:
    - enabled
    Specifies if WS-Addressing is enabled or not. The default value is true. (Boolean)
    - required
    Specifies that WS-Addressing headers must be present on incoming messages. The default value is false. (Boolean)
    - responses
    Specifies the message exchange pattern to use. The default value is Responses.ALL. This property is applicable for JAX-WS 2.2 and later. (String)
javax.xml.ws. soap.MTOM The @MTOM annotation specifies whether binary content in the body of a SOAP message is sent using MTOM.

Apply this annotation to a service endpoint implementation class.
  • Annotation target: Class
  • Properties:
    - enabled
    Specifies if MTOM is enabled for the JAX-WS endpoint. The default value is true. (Boolean)
    - threshold
    Specifies the minimum size for messages that are sent using MTOM. When the message size is less than this specified integer, the message is inlined in the XML document as base64 or hexBinary data. (integer)
javax.xml.ws. WebFault The @WebFault annotation maps WSDL faults to Java exceptions. It is used to capture the name of the fault during the serialization of the JAXB type that is generated from a global element referenced by a WSDL fault message. It can also be used to customize the mapping of service specific exceptions to WSDL faults.

This annotation can only be applied to a fault implementation class on the client or server.
  • Annotation target: Type
  • Properties:
    - name
    Specifies the local name of the XML element that represents the corresponding fault in the WSDL file. The actual value must be specified. (String)
    - targetNamespace
    Specifies the namespace of the XML element that represents the corresponding fault in the WSDL file. (String)
    - faultBean
    Specifies the name of the fault bean class. (String)
    - messageName
    Specifies the name of the wsdl:message attribute that represents the corresponding fault in the WSDL file. This property is applicable for JAX-WS 2.2 and later. (String)
javax.xml.ws. WebServiceProvider The @WebServiceProvider annotation denotes that a class satisfies requirements for a JAX-WS Provider implementation class.
Important:
  • A Java class that implements a web service must specify either the @WebService or @WebServiceProvider annotation. Both annotations cannot be present.
  • The @WebServiceProvider annotation is only supported on the service implementation class.
Any class with the @WebServiceProvider annotation must implement the javax.xml.ws.Provider interface.
  • Annotation target: Type
  • Properties:
    - targetNamespace
    Specifies the XML namespace of the WSDL and XML elements generated from the web service. The default value is the namespace mapped from the package name containing the web service. (String)
    - serviceName
    Specifies the service name of the web service: wsdl:service. The default value is the simple name of the Java class + Service. (String)
    - portName
    The wsdl:portName. The default value is the name of the class + Port. (String)
    - wsdlLocation
    The web address of the WSDL document defining the web service. This attribute is required. (String)
javax.xml.ws. WebServiceRef The @WebServiceRef annotation defines a reference to a web service invoked by the client.
Note:
  • The @WebServiceRef annotation can be used to inject instances of JAX-WS services and ports.
  • The @WebServiceRef annotation is only supported in certain class types. Examples are JAX-WS endpoint implementation classes, JAX-WS handler classes, Enterprise JavaBeans classes, and servlet classes. This annotation is supported in the same class types as the @Resource annotation. See the Java Platform, Enterprise Edition (Java EE) 5 specification for a complete list of supported class types.
  • Annotation target: Type, Field or Method
  • Properties:
    - name
    Specifies the JNDI name of the resource. The field name is the default for field annotations. The JavaBeans property name that corresponds to the method is the default for method annotations. You must specify a value for class annotations as there is no default. (String)
    - type
    Indicates the Java type of the resource. The field type is the default for field annotations. The type of the JavaBeans property is the default for method annotations. You must specify a value for class annotations as there is no default. (Class)
    - mappedName
    Specifies the name to map this resource to. (String)
    - value
    Indicates the value of the service class and it is a type that extends javax.xml.ws.Service. This attribute is required when the type of the reference is a service endpoint interface. (Class)
    - wsdlLocation
    The web address of the WSDL document defining the web service. This attribute is required. (String)
    - lookup
    Specifies the JNDI lookup name for the target web service. This property is applicable for JAX-WS 2.2 and later. (String)
javax.xml.ws. WebServiceRefs The @WebServiceRefs annotation associates multiple @WebServiceRef annotations with a specific class.
Note: The @WebServiceRef annotation is only supported in certain class types. Examples are JAX-WS endpoint implementation classes, JAX-WS handler classes, Enterprise JavaBeans classes, and servlet classes. This annotation is supported in the same class types as the @Resource annotation. See the Java Platform, Enterprise Edition (Java EE) 5 specification for a complete list of supported class types.
  • Annotation target: Type
  • Properties:
    - value
    Specifies an array for multiple web service reference declarations. This attribute is required.
Table 3. JAX-WS Common Annotations (JSR 250) . Describes the supported JAX-WS common annotations and their associated properties.
Annotation class Annotation Properties
javax.annotation. Resource The @Resource annotation marks a WebServiceContext resource needed by the application.
Note:

Applying this annotation to a WebServiceContext type field on the server endpoint implementation class for a JavaBeans endpoint or a Provider endpoint results in the container injecting an instance of the WebServiceContext into the specified field.

When this annotation is used in place of the @WebServiceRef annotation, the rules described for the @WebServiceRef annotation apply.
  • Annotation target: Field or Method
  • Properties:
    - type
    Indicates the Java type of the resource. You are required to use the default, java.lang.Object or javax.xml.ws.Web ServiceContext value. If the type is the default, the resource must be injected into a field or a method. In this case, the type of the field or the type of the JavaBeans property defined by the method must be javax.xml.ws.WebServiceContext. (Class)
    If you are using this annotation to inject a web service, see the description of the @WebServiceRef type attribute.
javax.annotation. Resources The @Resources annotation associates multiple @Resource annotations with a specific class and serves as a container for multiple resource declarations.
  • Annotation target: Field or Method
  • Properties:
    - value
    Specifies an array for multiple @Resource annotations. This attribute is required.
javax.annotation. PostConstruct The @PostConstruct annotation marks a method that needs to run after dependency injection is performed on the class.

Apply this annotation to a JAX-WS application handler, a server endpoint implementation class.
  • Annotation target: Method
javax.annotation. PreDestroy The @PreDestroy annotation marks a method that must be run when the instance is in the process of being removed by the container.

Apply this annotation to a JAX-WS application handler or a server endpoint implementation class.
  • Annotation target: Method
Table 4. IBM proprietary annotations . Describes the supported IBM® proprietary annotations and their associated properties.
Annotation class Annotation Properties
com.ibm.websphere. wsaddressing. jaxws21. SubmissionAddressing The @SubmissionAddressing annotation specifies that this service wants to enable WS-Addressing support for the 2004/08 WS-Addressing specification.

This annotation is part of the IBM implementation of the JAX-WS 2.1 specification.

Apply this annotation to methods on a server endpoint implementation class.
  • Annotation target: Type
  • Properties:
    - enabled
    Specifies if WS-Addressing is enabled or not. The default value is true. (Boolean)
    - required
    Specifies that WS-Addressing headers must be present on incoming messages. The default value is false. (Boolean)