JAX-WS annotations

JAX-WS annotations

+
Search Tips | Advanced Search

Overview

JAX-WS uses annotations to specify metadata describing how...

A server-side service implementation is accessed as a Web service
A client-side Java class accesses Web services

Annotations replace...

deployment descriptor files
WSDL files
mapping metadata from XML and WSDL into the source artifacts

Use annotations to replace WSDL parameters such as...

bindings
handler chains
set names of portType
service

Annotations are used in...

mapping Java to WSDL and schema
at runtime to control how the JAX-WS runtime processes and responds to Web service invocations

For JAX-WS Web services, the use of webservices.xml is optional. You can still use webservices.xml to augment or override existing JAX-WS annotations.
JAX-WS supports the use of annotations based on...

JSR 175
JSR 181
JSR 224

V6.1 Feature Pack for Web services

In the V6.1 Feature Pack for Web services, the default behavior during application installation is to scan...

pre-Java EE 5 Web application modules to identify JAX-WS services
pre-Java EE 5 Web application modules and EJB modules for service clients

For V7.0, the default behavior is to not scan pre-Java EE 5 modules for annotations during application installation or server startup.
To preserve backward compatibility with the feature pack in either of two ways:

Set the property UseWSFEP61ScanPolicy to true in META-INF/MANIFEST.MF.
Manifest-Version: 1.0
UseWSFEP61ScanPolicy: true

The module is scanned for JAX-WS annotations regardless of the Java EE version of the module.
Default is false. With a value of false JAX-WS annotations are only supported in modules whose version is Java EE 5 or later.
Set the following custom JVM property to true...
com.ibm.websphere.webservices.UseWSFEP61ScanPolicy

Change the setting on each server that requires a change in the default behavior.

Settings in META-INF/MANIFEST.MF take precedence over custom JVM properties. When using either property, establish the desired annotation scanning behavior before the application is installed. You cannot dynamically change the scanning behavior after the application is installed.
If changes to the behavior are required after the application is installed...

Uninstall the application
Specify the desired scanning behavior using the appropriate property
Install the application again

Federating nodes that have...
com.ibm.websphere.webservices.UseWSFEP61ScanPolicy = true

...does not affect the deployment manager. You need to set the property to true on the deployment manager before the node is federated.

Annotations

The targets for annotations listed below are 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

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.
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.
Annotation target: Type
Properties:

-name Name of the wsdl:portType.
Default is the unqualified name of the Java class or interface. (String)
-targetNamespace XML namespace of the WSDL and XML elements generated from the Web service.
Default is the namespace mapped from the package name containing the Web service. (String)
-serviceName Service name of the Web service: wsdl:service.
Default is the simple name of the Java class + Service. (String)
-endpointInterface 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 wsdl:portName.
Default is WebService.name +Port . (String)
-wsdlLocation 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.
The @WebMethod annotation is only supported on classes that are annotated with the @WebService annotation.
Annotation target: Method
Properties:

-operationName Name of the wsdl:operation matching this method.
Default 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.
Default is the name of Java method. (String)
-exclude Whether to exclude a method from the Web service.
Default 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 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 XML namespace of the XML element for the parameter. Applies only for document bindings when the attribute maps to an XML element.
Default is the targetNamespace for the Web service. (String)
-mode 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.
Default 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.
Default is return for RPC and DOCUMENT/WRAPPED bindings.
Default is the method name + Response for DOCUMENT/BARE bindings. (String)
-targetNamespace 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.
Default 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 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. Configure a client side handler by using the @HandlerChain annotation on the generated service class or SEI. Additionally, we can programmatically register the 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.
Default is DOCUMENT. (String)
-use Defines the formatting used for messages sent to and from the Web service.
Default 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.
Default is WRAPPED. (String)

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, also specify the @Addressing annotation on the server endpoint implementation class. If we do not want to use the @Addressing annotation we can supply the 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.
Use the @BindingType annotation on the Java Beansendpoint 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 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.
Default 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, also specify the @Addressing annotation on the server endpoint implementation class. If we do not want to use the @Addressing annotation we can supply the 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.
Default is the operationName as defined in javax.jws.WebMethod annotation. (String)
-targetNamespace XML namespace of the request wrapper method.
Default is the target namespace of the SEI. (String)
-className Name of the class representing the request wrapper. (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.
Default is the operationName + Response. operationName is defined in javax.jws.WebMethod annotation. (String)
-targetNamespace XML namespace of the request wrapper method.
Default is the target namespace of the SEI. (String)
-className Name of the class representing the response wrapper. (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.
Default 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.
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.
Default 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 If WS-Addressing is enabled or not.
Default is true. (Boolean)
-required WS-Addressing headers must be present on incoming messages.
Default is false. (Boolean)

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 MTOM is enabled for the JAX-WS endpoint.
Default is true. (Boolean)
-threshold 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 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)

javax.xml.ws.WebServiceProvider

The @WebServiceProvider annotation denotes that a class satisfies requirements for a JAX-WS Provider implementation class.
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 XML namespace of the WSDL and XML elements generated from the Web service.
Default is the namespace mapped from the package name containing the Web service. (String)
-serviceName Service name of the Web service: wsdl:service.
Default is the simple name of the Java class + Service. (String)
-portName wsdl:portName.
Default is the name of the class + Port. (String)
-wsdlLocation 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 Java Beans 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 spec for a complete list of supported class types.
Annotation target: Type, Field or Method
Properties:

-name JNDI name of the resource. The field name is the default for field annotations. The Java Beans 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 Java type of the resource. The field type is the default for field annotations. The type of the Java Beans property is the default for method annotations. Specify a value for class annotations as there is no default. (Class)
-mappedName Specified the name to map this resource to. (String)
-value 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 Web address of the WSDL document defining the Web service. This attribute is required. (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 Java Beans 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 spec for a complete list of supported class types.
Annotation target: Type
Properties:

-value Array for multiple Web service reference declarations. Required.

javax.annotation.Resource

The @Resource annotation marks a WebServiceContext resource needed by the application.
Applying this annotation to a WebServiceContext type field on the server endpoint implementation class for a Java Beans 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 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 Java Beans property defined by the method must be javax.xml.ws.WebServiceContext. (Class)
If using this annotation to inject a Web service, see the description of the @WebServiceRef type attribute.

javax.annotation.Resources

Associates multiple @Resource annotations with a specific class and serves as a container for multiple resource declarations.
Annotation target: Field or Method
Properties:

-value Array for multiple @Resource annotations.

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

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:

-required WS-Addressing headers must be present on incoming messages.
Default is false. (Boolean)

Rules for methods on classes annotated with @WebService

The following rules apply for methods on classes annotated with the @WebService annotation.

If the @WebService annotation of an implementation class references an SEI, the implementation class must not have any @WebMethod annotations.
All public methods for an SEI are considered exposed methods regardless of whether the @WebMethod annotation is specified or not. It is incorrect to have an @WebMethod annotation on an SEI that contains the exclude attribute.
For an implementation class that does not reference an SEI, if the @WebMethod annotation is specified with a value of exclude=true, that method is not exposed. If the @WebMethod annotation is not specified, all public methods are exposed including the inherited methods with the exception of methods inherited from java.lang.Object.

Related concepts
JAXB
Ways to install enterprise apps or modules

Related
EJB 3.0 metadata annotations
Java virtual machine custom properties
Web services specifications and APIs

Related information
JAX-WS API documentation

-name	Name of the wsdl:portType. Default is the unqualified name of the Java class or interface. (String)
-targetNamespace	XML namespace of the WSDL and XML elements generated from the Web service. Default is the namespace mapped from the package name containing the Web service. (String)
-serviceName	Service name of the Web service: wsdl:service. Default is the simple name of the Java class + Service. (String)
-endpointInterface	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	wsdl:portName. Default is WebService.name +Port . (String)
-wsdlLocation	Web address of the WSDL document defining the Web service. The Web address is either relative or absolute. (String)

-operationName	Name of the wsdl:operation matching this method. Default 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. Default is the name of Java method. (String)
-exclude	Whether to exclude a method from the Web service. Default is false. (Boolean)

-name	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	XML namespace of the XML element for the parameter. Applies only for document bindings when the attribute maps to an XML element. Default is the targetNamespace for the Web service. (String)
-mode	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. Default is false. (Boolean)

-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. Default is return for RPC and DOCUMENT/WRAPPED bindings. Default is the method name + Response for DOCUMENT/BARE bindings. (String)
-targetNamespace	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. Default is @WebResult.name. (String)

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

-style	Defines encoding style for messages sent to and from the Web service. The valid values are DOCUMENT and RPC. Default is DOCUMENT. (String)
-use	Defines the formatting used for messages sent to and from the Web service. Default 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. Default is WRAPPED. (String)

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

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

-localName	Local name of the XML schema element representing the request wrapper. Default is the operationName as defined in javax.jws.WebMethod annotation. (String)
-targetNamespace	XML namespace of the request wrapper method. Default is the target namespace of the SEI. (String)
-className	Name of the class representing the request wrapper. (String)

-enabled	If WS-Addressing is enabled or not. Default is true. (Boolean)
-required	WS-Addressing headers must be present on incoming messages. Default is false. (Boolean)

-enabled	MTOM is enabled for the JAX-WS endpoint. Default is true. (Boolean)
-threshold	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)

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

-name	JNDI name of the resource. The field name is the default for field annotations. The Java Beans 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	Java type of the resource. The field type is the default for field annotations. The type of the Java Beans property is the default for method annotations. Specify a value for class annotations as there is no default. (Class)
-mappedName	Specified the name to map this resource to. (String)
-value	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	Web address of the WSDL document defining the Web service. This attribute is required. (String)