Using annotations to create Web services

With the Java™ API for XML-Based Web Services, you can use annotations in your Java code to simplify creating Web services.

The Java API for XML-Based Web Services (JAX-WS) programming standard relies on the use of annotations to specify metadata that is associated with Web service implementations. The standard also 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. Using annotations in this way defines additional 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, as well as 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.

Scenario	Runtime environment	Comments
Bottom-up Java bean	WAS v6.1 with the Feature Pack for Web Services WAS v7.0	Can be done 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 will be disabled because the wizard does not need to generate a delegate bean for you. You will only be able to select to generate a WSDL file. If you have added only the @javax.jws.WebService to your Java bean and want to enable other options such as SOAP 1.2 binding or MTOM, you should exit the wizard and either remove the annotation or proceed to create the Web service using the annotations documentation. The wizard will not allow you to append new annotations to a pre-existing partially annotated bean.
Bottom-up EJB 2.x	None	Not supported using annotations
Bottom-up EJB 3.0	WAS v7.0	Cannot use a mixture of annotations and the Web services wizard. Must use annotations and deploy the EJB bean to the application server.
Meet-in-the-middle Java bean	WAS v6.1 with the Feature Pack for Web Services WAS v7.0	This scenario allows you to map a Web service annotated Java bean to a WSDL document using the wsdlLocation attribute. For more information see: Creating a Web service from a Java bean and a WSDL file
Meet-in-the-middle EJB 3.0	WAS v7.0	This scenario allows you to map a Web service annotated EJB bean to a WSDL document 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 additional 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 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.

For more information about using annotations, see the related tasks:

• Annotating a Java bean to create a Web service
  You can annotate types, methods, fields, and parameters in your Java bean to specify a Web service.

• Annotating an EJB bean to create a Web service
  You can annotate types, methods, fields, and parameters in your EJB bean to specify a Web service.

• Creating a Web service from a Java bean and a WSDL file
  You can use annotations to associate an implementation Java bean with an existing WSDL service contract.

• Creating a Web service from an EJB bean and a WSDL file
  You can use annotations to associate an implementation EJB bean with an existing WSDL service contract.

• Validation of Web services annotations
  When you are using annotations with Java code, the product validates the usage and values of the annotations. Through this validation, you can detect problems before deploying your Web service.

 

Related concepts

JAX-WS

JAXB

 

Related reference

JAX-WS annotations reference

Related information

Developing Web services applications from JavaBeans using IBM WAS

Java API for XML Web Services (JAX-WS) API documentation

List of All Java Specification Requests (JSRs)

---