+

Search Tips   |   Advanced Search

JAX-WS annotations

JAX-WS relies on the use of annotations to specify metadata associated with web services implementations. 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 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 (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, we 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. We can use annotations to specify all of the information contained within the deployment descriptor file. We can use the deployment descriptor file to augment or override existing JAX-WS annotations. Information defined in the webservices.xml deployment descriptor overrides any corresponding information specified by annotations.

Starting with WAS v7.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 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 WAS v7 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, configure one of the following properties:

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. We cannot dynamically change the scanning behavior once an application is installed. If changes to the behavior are required after the application is installed, 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. 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.

(zos)

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

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

Annotations supported by JAX-WS are listed in the following table. The target for annotations is applicable for these Java objects:

Metadata Annotations (JSR 181). Describes the supported
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 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

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

Avoid trouble: Beginning with Sun and HP JDK Version 1.6 containing JAX-WS tooling Version 2.1.6, the behavior of the JAX-WS runtime environments and tooling has changed in how it determines which methods are exposed as web services operations in an effort to better adhere to the JAX-WS specifications. Applications that might be affected by this change include web services applications that do not specify a WSDL file or an explicit service endpoint interface (SEI). To learn more, see the exposing methods in SEI-based JAX-WS web services information. gotcha

  • Annotation target: Method

  • Properties:

    - operationName

    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

    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

    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

    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

    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

    Whether the result is carried in a header. The default value is false. (Boolean)

    - partName

    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.

We can only configure the server side handler 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. We can configure a client side handler using the @HandlerChain annotation on the generated service class or SEI. Additionally, we can programmatically register our own implementation of the HandlerResolver interface on the Service, or programmatically set the handler chain on the Binding object.

  • Annotation target: Type

  • Properties:

    - file

    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

    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. We can only use the BARE value with DOCUMENT style bindings. The default value is WRAPPED. (String)

Annotations (JSR 224). Describes the supported JAX-WS
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 we do not want to use the @Addressing annotation we can supply our own WSDL document with the Action attribute already defined.

  • Annotation target: Method

  • Properties:

    - fault

    Array of FaultAction for the wsdl:fault of the operation. (String)

    - input

    Action for thewsdl:input of the operation. (String)

    - output

    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: We 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 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 we do not want to use the @Addressing annotation we can supply our own WSDL document with the Action attribute already defined.

  • Annotation target: Method

  • Properties:

    - value

    Action of the wsdl:fault of the operation. (String)

    - output

    Name of the exception class. (String)

    - className

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

    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

    Name of the class representing the request wrapper. (String)

    - partName

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

    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

    Name of the class representing the response wrapper. (String)

    - partName

    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

    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

    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

    Minimum size for messages 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

    Local name of the XML element that represents the corresponding fault in the WSDL file. The actual value must be specified. (String)

    - targetNamespace

    Namespace of the XML element that represents the corresponding fault in the WSDL file. (String)

    - faultBean

    Name of the fault bean class. (String)

    - messageName

    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

    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.

  • 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 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. 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. Specify a value for class annotations as there is no default. (Class)

    - mappedName

    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.

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

Common Annotations (JSR 250). Describes the supported
Annotation class Annotation Properties
javax.annotation. Resource The @Resource annotation marks a WebServiceContext resource needed by the application.

Apply 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. We 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 we 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

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)


Related concepts

  • JAX-WS
  • JAXB
  • Ways to install enterprise applications or modules


    Related tasks

  • Exposing methods in SEI-based JAX-WS web services
  • Develop JAX-WS web services with annotations

  • EJB metadata annotations
  • JVM custom properties
  • Web services specifications and APIs


    Related information:

    JAX-WS API documentation