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, Java EE 5 application modules (Web application modules version 2.5 or above, or EJB modules version 3.0 or above) 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.
Manifest-Version: 1.0 UseWSFEP61ScanPolicy: trueWhen 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.
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. |
|
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. ![]() ![]() ![]() ![]() |
|
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. |
|
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. |
|
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. |
|
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. |
|
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 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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
javax.xml.ws. WebServiceRef | The @WebServiceRef annotation defines
a reference to a Web service invoked by the client. Important: • 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. |
|
javax.xml.ws. WebServiceRefs | The @WebServiceRefs annotation associates
multiple @WebServiceRef annotations with a specific class. Important: • 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 class | Annotation | Properties |
---|---|---|
javax.annotation. Resource | The @Resource annotation marks a WebServiceContext
resource needed by the application. Important: 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. |
|
javax.annotation. Resources | The @Resources annotation associates multiple @Resource annotations with a specific class and serves as a container for multiple resource declarations. |
|
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. |
|
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 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. |
|