Utilisation de gestionnaires dans des services Web JAX-WS
JAX-WS (Java™ API for XML Web Services) offre un moyen standard de développement de services Web interopérables et portables. Utilisez les gestionnaires JAX-WS pour personnaliser les demandes de services Web ou la gestion des réponses.
Avant de commencer
Vous devez disposer d'un fichier EAR pour les applications à configurer. Si l'exécution s'effectue dans un environnement Thin Client for JAX-WS, il n'est pas nécessaire que vous commenciez avec un fichier EAR. Dans certains cas, comme la journalisation ou le traçage, seule l'application serveur ou client doit être configurée. Dans d'autres situations, comme l'envoi des informations des en-têtes SOAP, les applications client et serveur doivent être configurées avec des gestionnaires symétriques.
SOAPMessage m = context.getMessage();
AttachmentPart ap1 = m.createAttachmentPart();
ap1.setContent("abc", "text/plain");
m.addAttachmentPart(ap1);
context.setMessage(m);
Pourquoi et quand exécuter cette tâche
A l'instar du modèle de programmation JAX-RPC (Java API for XML-based RPC), le modèle de programmation JAX-WS offre une fonction de gestion d'applications permettant de manipuler un message sur un flux entrant ou sortant. Vous pouvez ajouter des gestionnaires à l'environnement d'exécution JAX-WS pour effectuer un traitement supplémentaire des messages de demande et de réponse. Vous pouvez utiliser des gestionnaires pour effectuer diverses actions, telles la capture et la consignation d'informations et l'ajout de la sécurité ou d'autres informations à un message. Etant donné le support des protocoles au-delà de SOAP, JAX-WS fournit deux différentes classifications pour les gestionnaires. Un type de gestionnaire est un gestionnaire logique indépendant des protocoles et peut obtenir un message dans le flux en tant que message XML. Les gestionnaires logiques peuvent être utilisés pour des propriétés de contexte de message et pour la charge des messages. Ces gestionnaires doivent implémenter l'interface javax.xml.ws.handler.LogicalHandler. Un gestionnaire logique reçoit un objet LogicalMessageContext à partir duquel le gestionnaire peut obtenir des informations de message. Il peut exister des gestionnaires logiques sur les configurations SOAP et XML/HTTP.
Le deuxième type de gestionnaire est un gestionnaire de protocole. Les gestionnaires de protocole peuvent être utilisés pour des propriétés de message et pour des messages spécifiques au protocole. Les gestionnaires de protocole sont limités aux configurations de type SOAP et doivent implémenter l'interface javax.xml.ws.handler.soap.SOAPHandler. Les gestionnaires de protocole reçoivent le message en tant qu'élément javax.xml.soap.SOAPMessage pour lire les données de message.
L'environnement d'exécution JAX-WS n'effectue aucune distinction entre les classes de gestionnaire côté client et côté serveur. L'environnement d'exécution n'effectue aucune distinction entre le flux entrant ou sortant lorsqu'une méthode handleMessage(MessageContext) ou handleFault(MessageContext) pour un gestionnaire spécifique est appelée. Vous devez configurer les gestionnaires pour le serveur ou le client et implémenter une logique suffisante avec ces méthodes pour détecter la direction des éléments entrants ou sortants du message en cours.
Pour utiliser les gestionnaires avec les applications client des services Web, vous devez ajouter l'annotation @HandlerChain à l'interface de noeud final de service ou la classe de service générée et fournir le fichier de configuration de chaîne de gestionnaires. L'annotation @HandlerChain contient un attribut de fichier qui désigne un fichier de configuration de chaîne de gestionnaires. Pour les applications de client de services Web, vous pouvez également configurer la chaîne de gestionnaires par programmation à l'aide de l'API Binding. Pour modifier la classe de chaîne de gestionnaires par programmation, utilisez une implémentation par défaut ou une implémentation personnalisée défaut de la méthode HandlerResolver.
Pour utiliser des gestionnaires avec votre serveur d'applications, vous devez définir l'annotation @HandlerChain sur l'interface SEI ou la classe d'implémentation de noeud final et fournir le fichier de configuration de chaîne de gestionnaires associé. Les gestionnaires du serveur sont configurés uniquement en définissant l'annotation @HandlerChain sur l'implémentation de noeud final de service ou la classe d'implémentation. Les classes de gestionnaire doivent être incluses dans le fichier EAR de l'application de serveur.
@HandlerChain(file="../../common/handlers/myhandlers.xml")
ou @HandlerChain(file="http://foo.com/myhandlers.xml")
Pour plus d'informations sur le schéma du fichier de configuration du gestionnaire, voir la spécification JSR 181. Pour plus d'informations sur les gestionnaires JAX-WS, voir le chapitre 9 de la spécification JAX-WS.
Procédure
Résultats
Vous disposez du service Web JAX-WS ou du client de services Web pour utiliser des gestionnaires afin d'effectuer un traitement supplémentaire de l'échange des messages de demande et de réponse.
Exemple
L'exemple suivant présente la procédure permettant de configurer les gestionnaires JAX-WS sur une interface SEI utilisant l'annotation @HandlerChain.
<?xml version="1.0" encoding="UTF-8"?>
<jws:handler-chains xmlns:jws="http://java.sun.com/xml/ns/javaee">
<!-- Note: The '*" denotes a wildcard. -->
<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>
Assurez-vous d'avoir ajouté le fichier handler.xml et les classes de gestionnaire se trouvant dans le fichier handler.xml de votre chemin d'accès aux classes.
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) {
// Include your steps for the outbound flow.
}
return true;
}
}