+

Search Tips   |   Advanced Search

Develop a JAX-WS service endpoint implementation with annotations


JAX-WS supports two different service endpoint implementations types, the standard Web service endpoint interface and a new Provider interface to enable services to work at the XML message level. By using annotations on the service endpoint implementation or client, we can define the service endpoint as a Web service.

Set up a development environment for Web services.

This task is a required step to develop a JAX-WS Web service.

When developing a JAX-WS Web service starting from existing Java Beansor enterprise beans, we can expose the bean as a JAX-WS Web service by using annotations. Adding the @WebService or @WebServiceProvider annotation to the bean defines the bean as a JAX-WS Web service.

JAX-WS technology enables the implementation of Web services based on both the standard service endpoint interface and a new Provider interface. JAX-WS service endpoints are similar to the endpoint implementations in the JAX-RPC specification. Unlike JAX-RPC, the requirement for a service endpoint interface (SEI) is optional for JAX-WS Web services. JAX-WS services that do not have an associated SEI are regarded as having an implicit SEI, whereas services that have an associated SEI are regarded as having an explicit SEI. The service endpoint interfaces required by JAX-WS are also more generic than the service endpoint interfaces required by JAX-RPC. With JAX-WS, the SEI is not required to extend the java.rmi.Remote interface as required by the JAX-RPC specification.

The JAX-WS model also leverages support for annotating Java classes with metadata to define a service endpoint implementation as a Web service and define how a client can access the Web service. JAX-WS supports annotations based on the Metadata Facility for the Java Programming Language (JSR 175) specification, the Web Services Metadata for the Java Platform (JSR 181) spec and annotations defined by the JAX-WS 2.0 (JSR 224) specification, which includes JAXB annotations. Using annotations, the service endpoint implementation can independently describe the Web service without requiring a WSDL file. Annotations can provide all of the WSDL information necessary to configure the service endpoint implementation or Web services client. We can specify annotations on the service endpoint interface used by the client and the server, or on the server-side service implementation class.

To develop a JAX-WS Web service, annotate your Java class with the javax.jws.WebService annotation for Java Beans or enterprise beans endpoints or the javax.jws.WebServiceProvider annotation for a Provider endpoint. These annotations define the Java class as a Web service endpoint. For a JAX-WS service endpoint, the service endpoint interface or service endpoint implementation is a Java interface or class, respectively, that declares the business methods provided by a particular Web service. The only methods on a JAX-WS service endpoint that can be invoked by a Web services client are the business methods defined in the explicit or implicit service endpoint interface.

All JAX-WS service endpoints are required to have the @WebService (javax.jws.WebService) annotation included on the bean class. If the service implementation bean also uses an SEI, then that endpoint interface must be referenced by the endpointInterface attribute on that annotation. If the service implementation bean does not use an SEI, then the service is described by the implicit SEI defined in the bean.

The JAX-WS model introduces the new Provider API, javax.xml.ws.Provider, as an alternative to service endpoint interfaces. The Provider interface supports a more messaging oriented approach to Web services. With the Provider interface, we can create a Java class that implements a simple interface to produce a generic service implementation class. The Provider interface has one method, the invoke method, which uses generics to control both the input and output types when working with various messages or message payloads. All Provider endpoints must be annotated with the @WebServiceProvider (javax.xml.ws.WebServiceProvider) annotation. A service implementation cannot specify the @WebService annotation if it implements the javax.xml.ws.Provider interface.

For transitioning users: In WAS V7.0, the default annotation support behavior has changed. In the V6.1 Feature Pack for Web services, the default behavior is to scan pre-Java EE 5 Web app modules to identify JAX-WS services and to scan pre-Java EE 5 Web app modules and EJB modules for service clients during application installation. For V 7.0, the default behavior is to not scan pre-Java EE 5 modules for annotations during application installation or server startup. You can preserve compatibility with feature packs from previous releases by either setting the UseWSFEP61ScanPolicy property in the META-INF/MANIFEST.MF of a WAR file or EJB module or by defining the Java virtual machine custom property, com.ibm.websphere.webservices.UseWSFEP61ScanPolicy, on servers to request scanning during application installation and server startup. To learn more about annotations scanning, see the JAX-WS annotations documentation.trns

 

  1. Identify the service endpoint requirements for the Web services application.

    First determine if the service implementation is a standard JAX-WS service endpoint or a Provider endpoint. If we choose to use a JAX-WS service endpoint, then determine to use an explicit SEI or if the bean has an implicit SEI.

  2. Annotate the service endpoints. A Java class that implements a Web service must specify either the javax.jws.WebService or javax.xml.ws.WebServiceProvider annotation. Both annotations must not be present on a Java class. The javax.xml.ws.WebServiceProvider annotation is only supported on classes that implement the javax.xml.ws.Provider interface.

    • If we have an explicit service endpoint interface with the Java class, then use the endpointInterface parameter to specify the service endpoint interface class name in the javax.jws.WebService annotation.

      We can add the @WebMethod annotation to methods of a service endpoint interface to customize the Java -to-WSDL mappings. All public methods are considered exposed methods regardless of whether the @WebMethod annotation is specified. It is incorrect to have an @WebMethod annotation on an service endpoint interface that contains the exclude attribute.

    • If we have an implicit service endpoint interface and the @WebMethod annotation is not specified, all public methods are exposed including the inherited methods of parent classes that are also annotated with @WebService annotations. Use the exclude parameter of the @WebMethod annotation to control which methods are exposed.

    • If the Web service implementation class implements the Provider interface, use the javax.xml.ws.WebServiceProvider annotation on the Provider endpoint.

 

Results

we have defined the service endpoint implementation that represents the Web services application. See the JAX-WS annotations documentation to learn more about the supported JAX-WS annotations.

 

Example

Sample Java Beans service endpoint implementation and interface

The following example illustrates a simple explicit Java Beans service endpoint implementation and the associated service endpoint interface. 

/** This is an excerpt from the service implementation file, EchoServicePortTypeImpl.java  package com.ibm.was.wssample.echo;
 import java.io.ByteArrayInputStream;
 import java.io.ByteArrayOutputStream;
 import javax.xml.bind.JAXBContext;
 import javax.xml.bind.Marshaller;
 import javax.xml.bind.Unmarshaller;
 import javax.xml.transform.stream.StreamSource;

@javax.jws.WebService(serviceName = "EchoService", 
                      endpointInterface = "com.ibm.was.wssample.echo.EchoServicePortType",
                      targetNamespace="http://com/ibm/was/wssample/echo/",
                      portName="EchoServicePort") 
public class EchoServicePortTypeImpl implements EchoServicePortType {

                public EchoServicePortTypeImpl() {
                }

                public String invoke(String obj) {
                        String str;
                        ....
                        str = obj;
                        ....
                        
                        return str;

                }

}


/**  This is a sample EchoServicePortType.java service interface */
 import javax.jws.WebMethod;
 import javax.jws.WebParam;
 import javax.jws.WebResult;
 import javax.jws.WebService;
 import javax.xml.ws.*;


@WebService(name = "EchoServicePortType", 
                   targetNamespace = "http://com/ibm/was/wssample/echo/",  
                   wsdlLocation="WEB-INF/wsdl/Echo.wsdl") 
public interface EchoServicePortType {


    /** ...the method process ...*/
        @WebMethod
    @WebResult(name = "response", targetNamespace = "http://com/ibm/was/wssample/echo/")
    @RequestWrapper(localName = "invoke", targetNamespace = "http://com/ibm/was/wssample/echo/",  className = "com.ibm.was.wssample.echo.Invoke")
    @ResponseWrapper(localName = "echoStringResponse", targetNamespace = "http://com/ibm/was/wssample/echo/", className = "com.ibm.was.wssample.echo.EchoStringResponse")
    public String invoke(
        @WebParam(name = "arg0", targetNamespace = "http://com/ibm/was/wssample/echo/")
        String arg0);

}

Sample Provider endpoint implementation

The following example illustrates a simple Provider service endpoint interface for a Java class. 

package jaxws.provider.source;
 import javax.xml.ws.Provider;
 import javax.xml.ws.WebServiceProvider;
 import javax.xml.transform.Source;

@WebServiceProvider() public class SourceProvider implements Provider<Source> {

    public Source invoke(Source data) {
        return data;
    }
}

In the Provider implementation example, the javax.xml.transform.Source type is specified in the generic <Source> method. The generic <Source> method specifies that both the input and output types are Source objects. An endpoint interface that implements the Provider interface must include a @WebServiceProvider annotation.

 

Next steps

Develop Java artifacts for JAX-WS applications from Java Beans.

 

Related tasks


Implement Web services applications with JAX-WS
Generating Java artifacts for JAX-WS applications

 

Related


JAX-WS annotations

 

Related information


Web services specifications and APIs
Java API for XML Web Services (JAX-WS) API documentation