Developing 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.
Before you begin
About this task
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 Java API for XML-based RPC (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. You 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, you must 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.
- Develop SEI-based JAX-WS web services
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.
- Develop JAX-WS web services using the Provider interface
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.
從 WebSphere® Application Server 7.0 版和更新的版本開始,系統會掃描 Java EE 5 應用程式模組(Web 應用程式模組 2.5 版或更新版本,或是 EJB 模組 3.0 版或更新版本)中是否有註釋可識別 JAX-WS 服務和用戶端。 不過,為了效能考量,依預設,系統不會掃描 Java EE 5 之前的應用程式模組(Web 應用程式模組 2.4 版或更早版本,或 EJB 模組 2.1 版或更早版本)中是否有 JAX-WS 註釋。在 6.1 版 Feature Pack for Web Services 中,預設行為是在應用程式安裝期間,掃描 Java EE 5 之前的 Web 應用程式模組來識別 JAX-WS 服務,以及掃描 Java EE 5 之前的 Web 應用程式模組和 EJB 模組,來尋找服務用戶端。由於 WebSphere Application Server 7.0 版及更新版本的預設行為是不在安裝應用程式或啟動伺服器期間掃描 Java EE 5 之前的模組是否含有註釋,因此為了保留與舊版特性套件的舊版相容性,您必須在伺服器上配置 Web 應用程式保存檔 (WAR) 的 META-INF/MANIFEST.MF 中的 UseWSFEP61ScanPolicy 內容或 EJB 模組,或定義 Java 虛擬機器自訂內容 com.ibm.websphere.webservices.UseWSFEP61ScanPolicy,來要求在安裝應用程式及啟動伺服器期間進行掃描。如果要進一步瞭解註釋掃描,請參閱 JAX-WS 註釋資訊。
Procedure
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.
Sample JavaBeans service endpoint implementation and 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
}
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.