Annotations for creating web services overview

You can use annotations in your Java™ code to create web services. Annotations specify metadata that is associated with web service implementations.

The Java API for XML-Based Web Services (JAX-WS) programming standard relies on annotations to simplify the development of web services. Annotations describe two aspects of web services: how a server-side service implementation is accessed as a web service, and how a client-side Java class accesses web services.

The JAX-WS programming standard supports annotating Java classes with metadata that is used to define a service endpoint application as a web service and to specify how a client can access the service. The JAX-WS standard supports the use of annotations that are based on several Java Specification Requests (JSRs):

A Metadata Facility for the Java Programming Language (JSR 175),
Web Services Metadata for the Java Platform (JSR 181)
Java API for XML-Based web services (JAX-WS) 2.0 (JSR 224).
Common Annotations for the Java Platform (JSR 250)

Using annotations from the JSR 181 standard, you can annotate a service implementation class or a service interface. Then, you can generate a web service with a wizard or by publishing the application to a server. Using annotations within both Java source code and Java classes simplifies web service development. If you use annotations in this way it defines more information that is typically obtained from deployment descriptor files, Web Services Description Language (WSDL) files, or mapping metadata from XML and WSDL into source artifacts.

You can use annotations to configure bindings and handler chains; and to set names of portType, service, and other WSDL parameters. You can also use annotations at build-time to map Java to WSDL and schema, and at run time to control how the JAX-WS runtime processes and responds to web service invocations.

The product uses annotations in clients that you create through the web service client wizard. The wizard generates a client proxy and a static service class with annotations. These annotations specify how the client accesses the web service.

For detailed information about annotations that you can use, see the related reference.

Supported annotation-based web service scenarios

The following web service scenarios are supported by the tools and WebSphere® runtime environments:

Table 1. Supported runtime environments. Run times supported by annotation-based web service scenarios.
Scenario	Runtime environment	Comments
Bottom-up Java bean	WebSphere Application Server v7.0 and later	Can be done by using annotations alone or in combination with the web service wizards. If the bean already has a @javax.jws.WebService annotation, many of the fields in the wizard is disabled because the wizard does not need to generate a delegate bean for you. You are only able to select to generate a WSDL file. If you added only the @javax.jws.WebService to your Java bean and want to enable other options such as SOAP 1.2 binding or MTOM, exit the wizard and either remove the annotation or proceed to create the web service by using the annotations documentation. The wizard does not enable you to append new annotations to a pre-existing partially annotated bean.
Bottom-up EJB 2.x	None	Not supported by using annotations
Bottom-up EJB 3.0	WebSphere Application Server v7.0 and later	Cannot use a mixture of annotations and the web services wizard. You must use annotations and deploy the EJB bean to the application server.
Meet-in-the-middle Java bean	WebSphere Application Server v7.0 and later	This scenario enables you to map a web service annotated Java bean to a WSDL document using the wsdlLocation attribute. Note: If you want to use SOAP 1.2: `@javax.xml.ws.BindingType (value=javax.xml.ws.soap.SOAPBinding.SOAP12HTTP_BINDING)` you must you specify the wsdlLocation attribute of the @WebService annotation, such as in the following example: `@javax.jws.WebService (targetNamespace="http://p/", ..., wsdlLocation="WEB-INF/wsdl/EchoService.wsdl")` You cannot use the WSDL file dynamically generated by WebSphere Application Server but must have a WSDL file created beforehand. Alternatively, you can use the web services wizards, which generates a WSDL file for you if you select to use SOAP 1.2 when you generate a web service from a Java bean. For more information, see: Creating a web service from a Java bean and a WSDL file.
Meet-in-the-middle EJB 3.0	WebSphere Application Server v7.0 and later	This scenario enables you to map a web service annotated EJB bean to a WSDL document by using the wsdlLocation attribute. For more information, see: Creating a Web service from an EJB bean and a WSDL file.

Example

For example, you can embed a @WebService tag in the Java source to expose a bean as a web service.

@WebService 

public class QuoteBean implements StockQuote {

       public float getQuote(String sym) { ... }

}

The annotation @WebService tells the server runtime environment to expose all public methods on that bean as a web service. You can control more levels of granularity by adding other annotations on individual methods or parameters. Using annotations makes it much easier to expose Java artifacts as web services. In addition, as you create artifacts by using some of the top-down mapping tools that start from a WSDL file, annotations are included within the source and Java classes as a way of capturing the metadata along with the source files.

Feedback