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.

Les modules du fichier EAR doivent contenir les classes de gestionnaire à configurer. Les classes de gestionnaire implémentent l'interface javax.xml.ws.handler.LogicalHandler<LogicalMessageContext> ou l'interface javax.xml.ws.handler.soap.SOAPHandler<SOAPMessageContext>.
A faire : Si vous interceptez un SOAPMessage entrant et le manipulez, par exemple en y ajoutant une pièce jointe, vous devez utiliser la partie setmessage de SOAPMessageContext pour vous assurer que la pièce jointe fait partie du SOAPMessageContext. Ceci permet de s'assurer que l'exécution JAX-WS peut accéder au dernier SOAPMessage pour pouvoir traiter correctement les parties de pièce jointe. L'exemple suivant illustre ce processus.
 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.

Pour des implémentations serveur et client de gestionnaires à l'aide de l'annotation @HandlerChain, vous devez spécifier l'emplacement de la configuration du gestionnaire sous la forme d'un chemin relatif à partir du fichier annoté ou d'une URL absolue. Exemple :
@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

  1. Déterminez si vous souhaitez implémenter les gestionnaires JAX-WS sur le service ou le client.
  2. Configurez les gestionnaires client en définissant l'annotation @HandlerChain sur l'instance de service ou l'interface SEI. Vous pouvez également modifier la chaîne de gestionnaires par programmation pour contrôler comment la chaîne de gestionnaires est intégrée à l'environnement d'exécution. Si vous choisissez de modifier par programmation la chaîne de gestionnaires, vous devez alors déterminer si vous utilisez le programme de résolution du gestionnaire par défaut ou si vous utilisez une implémentation par défaut d'un programme de résolution du gestionnaire enregistré sur l'instance de service. Une instance de service utilise un programme de résolution de gestionnaire lors de la création de fournisseurs de liaisons. Lorsque les fournisseurs de liaisons sont créés, le programme de résolution du gestionnaire enregistré avec un service permet de créer une chaîne de gestionnaires et cette dernière permet ensuite de configurer le fournisseur de liaisons.
    1. Utilisez l'implémentation par défaut d'un programme de résolution de gestionnaires. L'environnement d'exécution utilise maintenant l'annotation @HandlerChain et l'implémentation par défaut de la classe HandlerResolver pour générer la chaîne de gestionnaires. Vous pouvez obtenir la chaîne de gestionnaires existante à partir de la liaison, ajouter ou supprimer des gestionnaires puis retourner la chaîne de gestionnaires modifiée à l'objet Binding.
    2. Pour utiliser une implémentation personnalisée d'un programme de résolution de gestionnaire, définissez la classe HandlerResolver personnalisée sur l'instance Service. L'environnement d'exécution utilise l'implémentation par défaut de la classe HandlerResolver pour générer la chaîne de gestionnaires. L'implémentation d'exécution par défaut n'est pas utilisée. Dans ce scénario, l'annotation @HandlerChain n'est pas lue lors de l'extraction de la chaîne de gestionnaires à partir de la liaison une fois qu'une instance HandlerResolver personnalisée est enregistrée sur l'instance Service. Vous pouvez obtenir la chaîne de gestionnaires existante à partir de la liaison, ajouter ou supprimer des gestionnaires puis retourner la chaîne de gestionnaires modifiée à l'objet Binding.
  3. Configurez les gestionnaires de serveur en définissant l'annotation @HandlerChain sur la classe d'annotation ou l'interface SEI. Lorsque l'annotation @HandlerChain est configurée sur l'interface SEI et la classe d'implémentation, la classe d'implémentation est prioritaire.
  4. Créez le fichier XML de configuration de la chaîne de gestionnaires. Vous devez créer un fichier XML de configuration de chaîne de gestionnaires pour l'élément @HandlerChain à référencer.
  5. Ajoutez le fichier XML de configuration de chaîne de gestionnaires dans le chemin d'accès aux classes pour l'interface SEI lors de la configuration du serveur ou des gestionnaires de client utilisant l'annotation @HandlerChain. Vous devez également inclure les classes de gestionnaire se trouvant dans le fichier XML de configuration dans votre chemin d'accès aux classes.
  6. Ecrivez votre implémentation de gestionnaire.

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.

L'annotation @HandlerChain a un attribut de fichier qui désigne un fichier de configuration de chaîne de gestionnaires. Le fichier suivant présente un fichier de configuration de gestionnaire standard. Les éléments protocol-bindings, port-name-pattern et service-name-pattern sont des filtres pouvant être utilisés pour restreindre les services pouvant s'appliquer aux gestionnaires.
<?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.

L'exemple suivant présente une implémentation de gestionnaire :
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;
    }

}

Que faire ensuite

Déployez l'application de services Web.

Icône indiquant le type de rubrique Rubrique de tâche



Icône d'horodatage Dernière mise à jour: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_jaxwshandler
Nom du fichier : twbs_jaxwshandler.html