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.
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.
@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
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.
<?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.
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;
}
}