JAX-WS-Web-Services mit Annotationen entwickeln

Java API for XML-Based Web Services (JAX-WS) unterstützt zwei verschiedene Typen von Serviceendpunktimplementierungen, die Standardserviceendpunktschnittstelle für Web-Services und eine neue Providerschnittstelle, die die Ausführung von Services auf XML-Nachrichtenebene ermöglicht. Mit Hilfe von Annotationen in der Serviceendpunktimplementierung oder im Client können Sie den Serviceendpunkt als Web-Service definieren.

Informationen zu diesem Vorgang

Diese Task ist ein erforderlicher Schritt für die Entwicklung von JAX-WS-Web-Services.

Die JAX-WS-Technologie unterstützt die Implementierung von Web-Services auf der Basis der Standardserviceendpunktschnittstelle und einer neuen Providerschnittstelle. JAX-WS-Serviceendpunkte sind wie Endpunktimplementierungen in der Spezifikation Java™ API for XML-based RPC (JAX-RPC). Anders als bei JAX-RPC wird für JAX-WS-Services keine Serviceendpunktschnittstelle vorausgesetzt. JAX-WS-Services, denen keine Serviceendpunktschnittstelle zugeordnet ist, haben eine sogenannte implizite Serviceendpunktschnittstelle, während Services, denen eine Serviceendpunktschnittstelle zugeordnet ist, eine sogenannte explizite Serviceendpunktschnittstelle haben. Die für JAX-WS erforderlichen Serviceendpunktschnittstellen sind außerdem generischer als die für JAX-RPC erforderlichen Serviceendpunktschnittstellen. Bei JAX-WS muss die Serviceendpunktschnittstelle die Schnittstelle java.rmi.Remote nicht erweitern, wie es bei der Spezifikation JAX-RPC erforderlich ist.

Das JAX-WS-Programmiermodell nutzt außerdem die Unterstützung für die Annotation von Java-Klassen mit Metadaten, um eine Serviceendpunktimplementierung als Web-Service und den Zugriff auf den Web-Service über einen Client zu definieren. JAX-WS unterstützt Annotationen auf der Basis der Spezifikation "Metadata Facility for the Java Programming Language (JSR 175)", der Spezifikation "Web Services Metadata for the Java Platform (JSR 181)" und der Annotationen, die in der Spezifikation "JAX-WS 2.0 (JSR 224)" definiert sind, zu denen auch die JAXB-Annotationen (Java Architecture for XML Binding) gehören. Mit Annotationen kann die Serviceendpunktimplementierung den Web-Service unabhängig beschreiben, ohne eine WSDL-Datei verwenden zu müssen. Über Annotationen können alle WSDL-Informationen bereitgestellt werden, die zum Konfigurieren der Serviceendpunktimplementierung oder des Web-Service-Clients erforderlich sind. Sie können Annotationen in der vom Client und vom Server verwendeten Serviceendpunktschnittstelle oder in der serverseitigen Serviceimplementierungsklasse angeben.

Detaillierte Informationen zu den unterstützten Standards und Spezifikationen finden Sie in der Dokumentation zu den Web-Service-Spezifikationen und APIs.

Wenn Sie einen JAX-WS-Web-Service aus vorhandenen Java-Klassen entwickeln (Bottom-up-Ansatz), müssen Sie die Klasse mit einer der Annotationen @WebService (javax.jws.WebService) oder @WebServiceProvider (javax.xml.ws.Provider) versehen, damit die Klasse anfänglich als Web-Service definiert wird. Die Annotation @WebService definiert den Service als SEI-basierten Endpunkt, während die Annotation @WebServiceProvider den Service als providerbasierten Endpunkt definiert.

SEI-basierte JAX-WS-Web-Services entwickeln

Für einen SEI-basierten Endpunkt deklariert die Serviceendpunktschnittstelle (SEI), bei der es sich um eine Java-Klasse oder um eine Java-Schnittstelle handeln kann, die von einem bestimmten Web-Service bereitgestellten Geschäftsmethoden. Die einzigen Methoden, die ein Web-Service-Client in einem JAX-WS-Endpunkt aufrufen kann, sind die Geschäftsmethoden, die in der expliziten oder impliziten SEI definiert sind.

Bei allen SEI-basierten Endpunkten muss die Annotation @WebService in der Implementierungsklasse enthalten sein. Wenn die Serviceimplementierung eine explizite SEI verwenden, muss diese Schnittstelle vom Attribut endpointInterface in der Annotation @WebService referenziert werden. Wenn die Serviceimplementierung keine explizite SEI verwendet, wird der Service implizit von der Implementierungsklasse beschrieben und ist eine implizite SEI.

JAX-WS-Web-Services mit der Providerschnittstelle entwickeln

Das JAX-WS-Programmiermodell führt die Providerschnittstelle für Providerendpunkte javax.xml.ws.Provider als dynamische Alternative zu SEI-basierten Endpunkten ein. Die Providerschnittstelle unterstützt einen eher Messaging-orientierten Web-Service-Ansatz. Über die Providerschnittstelle können Sie eine Java-Klasse erstellen, die eine einfache Schnittstelle für das Erzeugen einer generischen Serviceimplementierungsklasse implementiert. Die Providerschnittstelle definiert eine Methode, die Methode invoke, die generische Elemente verwendet, um die Eingabe- und Ausgabetypen bei der Arbeit mit verschiedenen Nachrichten und Nachrichtennutzlasten zu steuern. Alle Providerendpunkte müssen mit der Annotation @WebServiceProvider (javax.xml.ws.WebServiceProvider) annotiert werden. Eine Serviceimplementierung darf die Annotation @WebService nicht verwenden, wenn sie die Schnittstelle javax.xml.ws.Provider implementiert.

Ab WebSphere Application Server Version 7.0 werden Java EE 5-Anwendungsmodule (Webanwendungsmodule der Version 2.5 oder höher oder EJB-Module der Version 3.0 oder höher) nach Annotationen durchsucht, um JAX-WS-Services und -Clients zu identifizieren. Anwendungsmodule vor Java EE 5 (Webanwendungsmodule der Version 2.4 oder früher oder EJB-Module der Version 2.1 oder früher) werden aus Leistungsgründen standardmäßig nicht nach JAX-WS-Annotationen durchsucht. In Feature Pack for Web Services Version 6.1 werden die Webanwendungsmodule einer Version vor Java EE 5 standardmäßig gescannt, um die JAX-WS-Services zu identifizieren und die Webanwendungsmodule und EJB-Module einer Version vor Java EE 5 während der Anwendungsinstallation nach Service-Clients zu scannen. Da Module vor Java EE 5 ab WebSphere Application Server Version 7.0 während der Anwendungsinstallation bzw. des Serverstarts standardmäßig nicht nach Annotationen durchsucht werden, müssen Sie zur Gewährleistung der Abwärtskompatibilität mit dem Feature-Pack früherer Releases entweder die Eigenschaft "UseWSFEP61ScanPolicy" in der Manifest-Datei "META-INF/MANIFEST.MF" einer WAR-Datei (Webarchiv) oder eines EJB-Moduls konfigurieren oder die angepasste JVM-Eigenschaft (Java Virtual Machine) "com.ibm.websphere.webservices.UseWSFEP61ScanPolicy" auf den Servern definieren, damit die Module während der Anwendungsinstallation bzw. des Serverstarts durchsucht werden. Wenn Sie mehr über das Durchsuchen von Modulen nach Annotationen erfahren möchten, lesen Sie die Informationen zu JAX-WS-Annotationen.

Vorgehensweise

  1. Ermitteln Sie, ob die Web-Services mit SEI-Endpunkten oder mit der Providerschnittstelle definiert werden sollen. Wenn Sie eine Java-orientierte Abstraktion auf hoher Ebene bevorzugen, die die Details der Umwandlung zwischen Java-Objekten und ihrer XML-Darstellung verbirgt, sollten Sie die Verwendung SEI-basierter Endpunkte für die Entwicklung Ihrer Web-Services in Erwägung ziehen. Wenn Ihr Web-Service jedoch eher auf der XML-Nachrichtenebene arbeiten soll, sollten Sie die Verwendung providerbasierter Endpunkte in Erwägung ziehen.
  2. Annotieren Sie die Serviceendpunkte.
    1. Annotieren Sie den SEI-basierten Endpunkt mit der Annotation javax.jws.WebService.
      • Bei Verwendung eines SEI-basierten Endpunkts legen Sie für die Implementierungsklasse die Annotation javax.jws.WebService fest. Sie können eine Serviceendpunktschnittstelle (SEI) explizit referenzieren, indem Sie das Attribut @WebService.endpointInterface definieren, das den Endpunkt in dieser expliziten SEI angibt. In diesem Fall muss die referenzierte Java-Schnittstelle auch die Annotation javax.jws.WebService enthalten. Wenn das Attribut endpointInterface nicht definiert oder leer ist, wird die Implementierungs-Bean als implizite SEI betrachtet. Sie können die Annotation @WebMethod Methoden von Serviceendpunktschnittstellen hinzufügen, um die Java-WSDL-Zuordnungen anzupassen. Alle allgemein zugänglichen Methoden werden unabhängig davon, ob die Annotation @WebMethod angegeben ist oder nicht, als bereitgestellte Methoden betrachtet. Es ist nicht zulässig, eine Annotation vom Typ @WebMethod in einer Serviceendpunktschnittstelle zu verwenden, die das Attribut exclude enthält.
      • Wenn Sie eine implizite SEI verwenden, können Sie durch selektive Verwendung der Annotation @WebMethod differenzierter festlegen, wie die Methoden bereitgestellt werden. Eine ausführliche Erläuterung finden Sie in den Informationen zur Bereitstellung von Methoden in SEI-basierten JAX-WS-Web-Services.
    2. Legen Sie den providerbasierten Endpunkt mit der Annotation javax.xml.ws.WebServiceProvider fest.
      • Bei Verwendung eines providerbasierten Endpunkts legen Sie für die Implementierungsklasse die Annotation javax.xml.ws.WebServiceProvider fest. Diese Annotation darf nur eine Klasse angeben, die eine stark typisierte Klasse der Art javax.xml.ws.Provider.interface implementiert, wie z. B. Provider<Source> oder Provider<SOAPMessage>, im Gegensatz zu einer Klasse, die unbegrenzt ist, z. B. Provider<T>. Eine stark typisierte Klasse ist dadurch gekennzeichnet, dass sie einem bestimmten Java-Eingabe- und -Ausgabetyp zugeordnet ist, wie z. B. Source oder SOAPMessage.
        @WebServiceProvider(
                serviceName="StringProviderService", 
                wsdlLocation="META-INF/echostring.wsdl", 
                targetNamespace="http://stringprovider.sample.test.org")
      • Optional: Gemäß der Spezifikation JAX-WS 2.2 wird, wenn Sie einen providerbasierten Endpunkt definieren, damit die Providerimplementierung einen Nullwert zurückgibt, keine Antwort zurückgegeben. Wenn die Annotation javax.xml.ws.WebServiceProvider keinen WSDL-Wert spezifiziert und die Providermethode invoke() einen Nullwert zurückgibt, besteht das Standardverhalten der JAX-WS-Laufzeitumgebung darin, eine Antwort zurückzugeben, die sich aus einem SOAPEnvelope zusammensetzt, der einen leeren SOAPBody enthält. Sie können die JVM-Eigenschaft jaxws.provider.interpretNullAsOneway in true ändern, falls die JAX-WS-Laufzeitumgebung dieses Szenario als reine Anforderungsoperation interpretieren und keine Antwort zurückgeben soll.
  3. Machen Sie sich mit den bewährten Verfahren für die Bereitstellung von Methoden als Operationen in SEI-basierten JAX-WS-Web-Services vertraut, und wenden Sie diese an.

    Aufgrund der Mehrdeutigkeit in verschiedenen Web-Service-Spezifikationen bezüglich der Art und Weise, wie Methoden als Operationen für SEI-basierte Endpunkte bereitgestellt werden, sollten Sie unabhängig von der JAX-WS-Implementierung, die Sie verwenden, die bewährten Verfahren befolgen, um ein einheitliches Verhalten zu gewährleisten.

Ergebnisse

Sie haben die Serviceendpunktimplementierung definiert, die die Web-Service-Anwendung darstellt. Weitere Informationen zu den unterstützten JAX-WS-Annotationen finden Sie in der Dokumentation zu JAX-WS-Annotationen.

Beispiel für JavaBeans-Serviceendpunktimplementierung und -schnittstelle

Im folgenden Beispiel werden eine einfache explizite JavaBeans-Serviceendpunktimplementierung und die zugehörige Serviceendpunktschnittstelle veranschaulicht:
/** Auszug aus der Serviceimplementierungsdatei 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;

                }

}
/**  Beispielserviceschnittstelle EchoServicePortType.java  */

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 {


    /** ... der Methodenprozess ...*/
        @WebMethod

}
Im folgenden Beispiel wird eine einfache Providerserviceendpunktschnittstelle für eine Java-Klasse veranschaulicht:
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;
    }
}

Im Providerimplementierungsbeispiel wird der Typ javax.xml.transform.Source in der generischen Methode <Source> angegeben. Die generische Methode <Source> gibt an, dass sowohl der Eingabetyp als auch der Ausgabetyp Source-Objekte sind.

Nächste Schritte

Entwickeln Sie Java-Artefakte für JAX-WS-Anwendungen aus JavaBeans. Weitere Informationen hierzu finden Sie in der Dokumentation zum Generieren von Java-Artefakten für JAX-WS-Anwendungen.


Symbol, das den Typ des Artikels anzeigt. Taskartikel



Symbol für Zeitmarke Letzte Aktualisierung: 25.05.2016
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_devjaxwsendpt
Dateiname:twbs_devjaxwsendpt.html