Network Deployment (Distributed operating systems), v8.0 > Develop and deploying applications > Develop web services > Develop JAX-WS web services (bottom up)
Develop JAX-WS web services with annotations
Java API for XML-Based
Web Services (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, you 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 JAX-WS web services.
JAX-WS technology supports the implementation of web services based on both the standard service endpoint interface and a new Provider interface. JAX-WS endpoints are like 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 programming model also uses 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) specification and annotations defined by the JAX-WS 2.0 (JSR 224) specification, which includes Java Architecture for XML Binding (JAXB) annotations. Using annotations, the service endpoint implementation can independently describe the web service without requiring a WSDL file. Annotations can provide all the WSDL information necessary to configure your 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.
For details regarding the supported standards and specifications, see the web services specifications and API documentation.
When developing a JAX-WS web service starting from existing Java classes, known as the bottom-up approach, annotate the class with either the @WebService (javax.jws.WebService) annotation or @WebServiceProvider (javax.xml.ws.Provider) annotation to initially define the class as a web service. The @WebService annotation defines the service as an SEI-based endpoint, while the @WebServiceProvider annotation defines the service as a Provider-based endpoint.
For an SEI-based endpoint, the service endpoint interface (SEI), whether it is a Java class or a Java interface, declares the business methods provided by a particular web service. The only methods that a web services client can invoke on a JAX-WS endpoint are the business methods that are defined in the explicit or implicit SEI.
All SEI-based endpoints are required to have the @WebService annotation included on the implementation class. If the service implementation uses an explicit SEI, then that interface must be referenced by the endpointInterface attribute on the @WebService annotation. If the service implementation does not use an explicit SEI, then the service is described implicitly by the implementation class and is an implicit SEI.
The JAX-WS programming model introduces the Provider interface for Provider endpoints, javax.xml.ws.Provider, as the dynamic alternative to SEI-based endpoints. The Provider interface supports a more messaging-oriented approach to web services. With the Provider interface, you can create a Java class that implements a simple interface to produce a generic service implementation class. The Provider interface defines 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: Starting with WAS v7.0 and later, 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.
In the v6.1 Feature Pack for Web Services, the default behavior
is to scan pre-Java EE 5 web application modules to identify JAX-WS
services and to scan pre-Java EE 5 web application modules and EJB modules for service clients during application installation. Because the default behavior for WAS Version 7.0 and later is to not scan pre-Java EE 5 modules for annotations
during application installation or server startup, to preserve backward
compatability with the feature pack from previous releases,
configure either the UseWSFEP61ScanPolicy property in the META-INF/MANIFEST.MF
of a WAR file or EJB module or define 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 information.trns
Procedure
- Determine to define your web services using SEI endpoints or the Provider interface. If you prefer a high-level Java-centric abstraction that hide the details of converting between Java objects and their XML representation, consider using SEI-based endpoints to develop your web services. However, if you prefer that your web service operate more at the XML message level, consider using Provider-based endpoints.
- Annotate the service endpoints.
- Annotate the SEI-based endpoint with the javax.jws.WebService annotation.
- For an SEI-based endpoint, annotate the implementation class with the javax.jws.WebService annotation. We can choose
to explicitly reference a service endpoint interface by defining
the @WebService.endpointInterface attribute, which specifies this endpoint is an explicit SEI. In this case, the Java interface that is referenced
must also contain the javax.jws.WebService annotation.
If the endpointInterface attribute is not defined
or is empty, the implementation bean is considered an implicit SEI.
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 a service endpoint
interface that contains the exclude attribute.
- If you use an implicit SEI, you can apply more granular control
on how the methods are exposed through selective use of the @WebMethod annotation.
For a more detailed explanation, see the exposing methods in SEI-based
JAX-WS web services information.
- For an SEI-based endpoint, annotate the implementation class with the javax.jws.WebService annotation. We can choose
to explicitly reference a service endpoint interface by defining
the @WebService.endpointInterface attribute, which specifies this endpoint is an explicit SEI. In this case, the Java interface that is referenced
must also contain the javax.jws.WebService annotation.
If the endpointInterface attribute is not defined
or is empty, the implementation bean is considered an implicit SEI.
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 a service endpoint
interface that contains the exclude attribute.
- Annotate the Provider-based endpoint with the javax.xml.ws.WebServiceProvider annotation.
- For a Provider-based endpoint, annotate the implementation class
with the javax.xml.ws.WebServiceProvider annotation.
This annotation must be specified only on a class that implements
a strongly typed javax.xml.ws.Provider.interface class
such as Provider
<Source> or Provider
<SOAPMessage>, in contrast to a class that is unbounded, such as Provider
<T>.
A strongly typed class is one that is associated with a specific input
and output Java type, such as Source or SOAPMessage, for example.
@WebServiceProvider( serviceName="StringProviderService", wsdlLocation="META-INF/echostring.wsdl", targetNamespace="http://stringprovider.sample.test.org") - (optional) According the JAX-WS 2.2 specification, if you are defining a Provider-based endpoint so that the Provider implementation returns a null value, no response is needed. If the javax.xml.ws.WebServiceProvider annotation
does not specify a WSDL, and the Provider invoke() method returns a null value, the default behavior of the JAX-WS runtime environment is to return a response that consists of a SOAPEnvelope that contains an empty SOAPBody. We can set the JVM property, jaxws.provider.interpretNullAsOneway, to true if you want the JAX-WS runtime environment to interpret this scenario as a request-only operation and not return
a response.
- For a Provider-based endpoint, annotate the implementation class
with the javax.xml.ws.WebServiceProvider annotation.
This annotation must be specified only on a class that implements
a strongly typed javax.xml.ws.Provider.interface class
such as Provider
<Source> or Provider
<SOAPMessage>, in contrast to a class that is unbounded, such as Provider
<T>.
A strongly typed class is one that is associated with a specific input
and output Java type, such as Source or SOAPMessage, for example.
- Annotate the SEI-based endpoint with the javax.jws.WebService annotation.
- Understand and apply best practices for
exposing methods
as operations in SEI-based JAX-WS web services.
Because of ambiguity across multiple web services specifications regarding which methods are exposed as web services operations for SEI-based endpoints, you can ensure consistent behavior by following best practices, regardless of the JAX-WS implementation that you use.
Results
You 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 JavaBeans service endpoint implementation and interface
The following example illustrates a simple explicit JavaBeans 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 echo(String obj) {
String str;
....
str = obj;
....
return str;
}
}
/** This is a sample EchoServicePortType.java service interface. */
import javax.jws.WebMethod;
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
}
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 echo(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.
What to do next
Develop Java artifacts for JAX-WS applications from JavaBeans.
To learn more, see the generating Java artifacts for JAX-WS applications information.
JAX-WS
Set up a development environment for web services
Exposing methods in SEI-based JAX-WS web services
Implement web services applications with JAX-WS
Generate Java artifacts for JAX-WS applications
Related
JAX-WS annotations
Web services specifications and APIs
Java API for XML Web Services (JAX-WS) API documentation