Handler in JAX-WS-Web-Services verwenden

Java™ API for XML Web Services (JAX-WS) bietet Ihnen eine standardisierte Methode für die Entwicklung interoperabler und portierbarer Web-Services. Mit JAX-WS-Handlern können Sie die Bearbeitung von Web-Service-Anforderungen und -Antworten anpassen.

Vorbereitende Schritte

Sie müssen eine EAR-Datei (Enterprise Archive) für die zu konfigurierenden Anwendungen haben. Wenn Sie in einer Umgebung des Typs "Thin Client for JAX-WS" arbeiten, müssen Sie nicht mit einer EAR-Datei anfangen. Für einige Handler wie Protokoll- und Trace-Handler muss nur die Server- oder Clientanwendung konfiguriert werden. Für andere Einsätze von Handlern, wie das Senden von Informationen in SOAP-Headern, müssen die Client- und Serveranwendungen mit symmetrischen Handlern konfiguriert werden.

Die Module in der EAR-Datei müssen die zu konfigurierenden Handlerklassen enthalten. Die Handlerklassen implementieren die Schnittstelle javax.xml.ws.handler.LogicalHandler<LogicalMessageContext> oder die Schnittstelle "javax.xml.ws.handler.soap.SOAPHandler<SOAPMessageContext>".
Hinweis: Wenn Sie eine eingehende SOAP-Nachricht (SOAPMessage) abfangen und dann bearbeiten, indem Sie z. B. einen Anhang (AttachmentPart) hinzufügen, müssen Sie den Abschnitt "setmessage" des SOAP-Nachrichtenkontextes (SOAPMessageContext) verwenden, um sicherzustellen, dass der Anhang zum SOAPMessageContext gehört. Damit wird gewährleistet, dass die JAX-WS-Laufzeit auf diese letzte SOAPMessage zugreifen kann, um die Anhänge richtig zu verarbeiten. Das folgende Beispiel veranschaulicht diesen Prozess.
 SOAPMessage m = context.getMessage(); 
 AttachmentPart ap1 = m.createAttachmentPart(); 
 ap1.setContent("abc", "text/plain");           
 m.addAttachmentPart(ap1);
 context.setMessage(m);                       

Informationen zu diesem Vorgang

Wie das Programmiermodell Java API for XML-based RPC (JAX-RPC) stellt das Programmiermodell JAX-WS eine Anwendungshandlerfunktion bereit, die Sie zum Bearbeiten einer Nachricht in einem eingehenden oder abgehenden Nachrichtenfluss verwenden können. Sie können der JAX-WS-Laufzeitumgebung Handler hinzufügen, um Anforderungs- und Antwortnachrichten weitergehend bearbeiten zu können. Handler können für eine Vielzahl von Zwecken eingesetzt werden, z. B. zum Erfassen und Protokollieren von Informationen oder zum Hinzufügen von Sicherheit und anderen Informationen zu einer Nachricht. Da außer SOAP noch weitere Protokolle unterstützt werden, stellt JAX-WS zwei unterschiedliche Klassifizierungen für Handler bereit. Der eine Handlertyp ist ein logischer Handler, der protokollunabhängig ist und die Nachricht im Nachrichtenfluss als XML-Nachricht (eXtensible Markup Language) abrufen kann. Die logischen Handler arbeiten auf der Basis von Nachrichtenkontexteigenschaften und Nachrichtennutzdaten. Diese Handler müssen die Schnittstelle "javax.xml.ws.handler.LogicalHandler" implementieren. Ein logischer Handler empfängt ein LogicalMessageContext-Objekt, aus dem er die Nachrichteninformationen extrahieren kann. Logische Handler können in SOAP- und XML/HTTP-basierten Konfigurationen verwendet werden.

Der zweite Handlertyp ist ein Protokollhandler. Die Protokollhandler arbeiten auf der Basis von Nachrichtenkontexteigenschaften und protokollspezifischen Nachrichten. Protokollhandler sind auf SOAP-basierte Konfigurationen beschränkt und müssen die Schnittstelle "javax.xml.ws.handler.soap.SOAPHandler" implementieren. Protokollhandler empfangen die Nachricht als "javax.xml.soap.SOAPMessage", aus der sie die Nachrichtendaten lesen.

Die JAX-WS-Laufzeitumgebung trifft keine Unterscheidung zwischen serverseitigen und clientseitigen Handlerklassen. Die Laufzeitumgebung unterscheidet nicht zwischen eingehenden und abgehenden Nachrichtenflüssen, wenn eine Methode "handleMessage(MessageContext)" oder "handleFault(MessageContext)" für einen bestimmten Handler aufgerufen wird. Sie müssen die Handler für den Server oder Client konfigurieren und in diesen Methoden eine angemessene Logik implementieren, die erkennt, ob es sich bei der aktuellen Nachricht um eine abgehende oder eingehende Nachricht handelt.

Wenn Sie Handler für Web-Service-Clientanwendungen verwenden möchten, müssen Sie der Serviceendpunktschnittstelle bzw. der generierten Serviceklasse die Annotation "@HandlerChain" hinzufügen und die Konfigurationsdatei für die Handlerkette angeben. Die Annotation "@HandlerChain" enthält ein Dateiattribut, das auf eine Konfigurationsdatei für die Handlerkette verweist, die Sie erstellen. Für Web-Service-Clientanwendungen können Sie die Handlerkette auch über das Programm mithilfe der API "Binding" erstellen. Wenn Sie die Klasse "handlerchain" über das Programm ändern möchten, verwenden Sie entweder die Standardimplementierung oder eine angepasste Implementierung der Methode "HandlerResolver".

Wenn Sie Handler für Ihre Serveranwendung verwenden möchten, müssen Sie die Annotation "@HandlerChain" in der Serviceendpunktschnittstelle oder in der Endpunktimplementierungsklasse definieren und die zugehörige Konfigurationsdatei für die Handlerkette angeben. Handler für den Server werden nur über die Annotation "@HandlerChain" in der Serviceendpunktschnittstelle oder in der Implementierungsklasse konfiguriert. Die Handlerklassen müssen in der EAR-Datei der Serveranwendung enthalten sein.

Für Server- und Clientimplementierungen von Handlern mithilfe der Annotation "@HandlerChain" müssen Sie die Position der Handlerkonfiguration als relativen Pfad, ausgehend von der annotierten Datei, oder als absoluten Pfad angeben. Beispiel:
@HandlerChain(file="../../common/handlers/myhandlers.xml")
oder
@HandlerChain(file="http://foo.com/myhandlers.xml")
Weitere Informationen zum Schema der Handlerkonfigurationsdatei finden Sie in der Spezifikation JSR 181.

Weitere Informationen zu JAX-WS-Handlern finden Sie in Kapitel 9 der Spezifikation JAX-WS.

Vorgehensweise

  1. Legen Sie fest, ob JAX-WS-Handler im Service oder im Client implementiert werden sollen.
  2. Konfigurieren Sie die Client-Handler, indem Sie die Annotation "@HandlerChain" in der Serviceinstanz oder in der Serviceendpunktschnittstelle definieren. Sie können die Handlerkette aber auch über das Programm ändern, um zu steuern, wie die Handlerkette zur Laufzeit gebildet wird. Wenn Sie sich für die Änderung der Handlerkette über das Programm entscheiden, müssen Sie festlegen, ob der Standardauflöser für Handler oder eine angepasste Implementierung eines Handlerauflösers verwendet werden soll, die in der Serviceinstanz registriert ist. Eine Serviceinstanz verwendet einen Handlerauflöser beim Erstellen von Bindungsprovidern. Wenn die Bindungsprovider erstellt werden, wird der bei einem Service registrierte Handlerauflöser verwendet, um eine Handlerkette zu erstellen. Diese Handlerkette wird anschließend zum Konfigurieren des Bindungsproviders verwendet.
    1. Verwenden Sie die Standardimplementierung eines Handlerauflösers. Die Laufzeitumgebung verwendet jetzt die Annotation "@HandlerChain" und die Standardimplementierung der Klasse "HandlerResolver", um die Handlerkette zu erstellen. Sie können die vorhandene Handlerkette aus dem Binding-Objekt abrufen, Handler hinzufügen und entfernen und anschließend die geänderte Handlerkette an das Binding-Objekt zurückgeben.
    2. Wenn Sie eine angepasste Implementierung eines Handlerauflösers verwenden möchten, definieren Sie die angepasste HandlerResolver-Klasse in der Serviceinstanz. Die Laufzeitumgebung verwendet die angepasste Implementierung der HandlerResolver-Klasse, um die Handlerkette zu erstellen, und die Standardlaufzeitimplementierung wird nicht verwendet. In diesem Szenario wird die Annotation "@HandlerChain" nicht gelesen, wenn die Handlerkette aus der Bindung abgerufen wird, nachdem die angepasste HandlerResolver-Instanz bei der Serviceinstanz registriert wurde. Sie können die vorhandene Handlerkette aus dem Binding-Objekt abrufen, Handler hinzufügen und entfernen und anschließend die geänderte Handlerkette an das Binding-Objekt zurückgeben.
  3. Konfigurieren Sie die Server-Handler, indem Sie die Annotation "@HandlerChain" in der Serviceendpunktschnittstelle oder in der Implementierungsklasse definieren. Wenn die Annotation "@HandlerChain" in der Serviceendpunktschnittstelle und in der Implementierungsklasse konfiguriert ist, hat die Definition in der Implementierungsklasse Vorrang.
  4. Erstellen Sie die XML-Konfigurationsdatei für die Handlerkette. Sie müssen eine XML-Konfigurationsdatei für die Handlerkette erstellen, auf die die Annotation "@HandlerChain" verweisen kann.
  5. Fügen Sie die XML-Konfigurationsdatei für die Handlerkette dem Klassenpfad der Serviceendpunktschnittstelle hinzu, wenn Sie die Server- oder Client-Handler mit der Annotation "@HandlerChain" konfigurieren. Außerdem müssen Sie die Handlerklassen, die in der XML-Konfigurationsdatei enthalten sind, in den Klassenpfad einfügen.
  6. Schreiben Sie eine eigene Handlerimplementierung.

Ergebnisse

Sie haben die Verwendung von Handlern in Ihrem JAX-WS-Web-Service oder Web-Service-Client aktiviert, um zusätzliche Verarbeitungsoperationen für den Austausch von Anforderungen und Antworten ausführen zu können.

Beispiel

Das folgende Beispiel veranschaulicht die Schritte, die ausgeführt werden müssen, um JAX-WS-Handler mit einer Annotation des Typs "@HandlerChain" in einer Serviceendpunktschnittstelle zu konfigurieren.

Die Annotation "@HandlerChain" hat ein Dateiattribut, das auf die XML-Konfigurationsdatei für eine Handlerkette verweist, die Sie erstellen. Die folgende Datei ist eine typische Handlerkonfigurationsdatei. Die Elemente "protocol-bindings", "port-name-pattern" und "service-name-pattern" sind Filter, über die die Services eingeschränkt werden können, die die Handler anwenden können.
<?xml version="1.0" encoding="UTF-8"?> 

<jws:handler-chains xmlns:jws="http://java.sun.com/xml/ns/javaee">
<!-- Anmerkung: Der Stern ('*") ist ein Platzhalterzeichen. -->

		<jws:handler-chain name="MyHandlerChain">
				<jws:protocol-bindings>##SOAP11_HTTP ##ANOTHER_BINDING</jws:protocol-bindings>
				<jws:port-name-pattern 
              xmlns:ns1="http://handlersample.samples.ibm.com/">ns1:MySampl*</jws:port-name-pattern>
        <jws:service-name-pattern 
              xmlns:ns1="http://handlersample.samples.ibm.com/">ns1:*</jws:service-name-pattern>
				<jws:handler>
						<jws:handler-class>com.ibm.samples.handlersample.SampleLogicalHandler</jws:handler-class>
				</jws:handler>
				<jws:handler>
						<jws:handler-class>com.ibm.samples.handlersample.SampleProtocolHandler2</jws:handler-class>
				</jws:handler>
				<jws:handler>
						<jws:handler-class>com.ibm.samples.handlersample.SampleLogicalHandler</jws:handler-class>
				</jws:handler>
				<jws:handler>
						<jws:handler-class>com.ibm.samples.handlersample.SampleProtocolHandler2</jws:handler-class>
				</jws:handler>
		</jws:handler-chain>
	
</jws:handler-chains>

</jws:handler-chains>

Sie müssen die Datei handler.xml und die in der Datei enthaltenen Handlerklassen Ihrem Klassenpfad hinzufügen.

Das folgende Beispiel zeigt eine Handlerimplementierung:
package com.ibm.samples.handlersample;

import java.util.Set;

import javax.xml.namespace.QName;
import javax.xml.ws.handler.MessageContext;
import javax.xml.ws.handler.soap.SOAPMessageContext;

public class SampleProtocolHandler implements
        javax.xml.ws.handler.soap.SOAPHandler<SOAPMessageContext> {

    public void close(MessageContext messagecontext) {
    }

    public Set<QName> getHeaders() {
        return null;
    }

    public boolean handleFault(SOAPMessageContext messagecontext) {
        return true;
    }

    public boolean handleMessage(SOAPMessageContext messagecontext) {
        Boolean outbound = (Boolean) messagecontext.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);
        if (outbound) {
            // Schritte für abgehenden Nachrichtenfluss einfügen
        }
        return true;
    }

}

Nächste Schritte

Implementieren Sie Ihre Web-Service-Anwendung.

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_jaxwshandler
Dateiname:twbs_jaxwshandler.html