Création d'une application de service Web JAX-RPC qui utilise WS-Addressing

Web Services Addressing (WS-Addressing) favorise l'interopérabilité entre les services Web en définissant un moyen standard de traiter les services Web et de fournir des informations d'adressage dans les messages. Cette tâche décrit les étapes requises pour la création d'un service Web JAX-RPC accessible via une référence de noeud final WS-Addressing. Cette tâche décrit également les étapes supplémentaires nécessaires pour utiliser des ressources avec état dans le cadre du service Web.

Avant de commencer

Les étapes décrites dans cette tâche s'appliquent aux serveurs et aux clients exécutés sur WebSphere Application Server.

Pourquoi et quand exécuter cette tâche

Effectuez cette tâche si vous créez un service Web qui utilise la spécification WS-Addressing.

Procédure

  1. Mettez en place une interface de service Web en créant ou en générant un document WSDL (Web Services Description Language) pour le service Web, qui renvoie une référence de noeud final au service cible. L'interface doit renvoyer une référence de noeud final, en utilisant une opération de fabrique ou un service de la fabrique distinct. Le service cible peut présenter une instance de ressource, par exemple un panier.
  2. Implémentez le service Web créé à l'étape précédente. Pour la partie WS-Addressing de l'implémentation, procédez comme suit :
    1. Créez une référence de noeud final qui référence le service Web en suivant les instructions indiquées dans Création de références de noeud final à l'aide d'API WS-Addressing propriété d'IBM.
    2. Facultatif : Si votre interface implique un service Web qui présente une instance de ressource, créez ou recherchez l'instance de ressource.
    3. Facultatif : Si vous utilisez une instance de ressource, récupérez l'ID ressource et associez-le à la référence de noeud final en tant que paramètre de la référence, à l'aide de la méthode EndpointReference.setReferenceParameter(QName resource_id_name, String value). L'ID ressource dépend de l'application et peut être généré lors de la création de l'instance de ressource.
      Avertissement : N'incluez pas d'informations sensibles dans l'identifiant de ressource, car celui-ci est propagé dans le message SOAP.
      Maintenant, la référence de noeud final cible la ressource.
    4. Renvoyez la référence de noeud final.
  3. Si votre service Web utilise des instances de ressource, étendez l'implémentation pour faire correspondre les messages entrants aux instances de ressource appropriées. Comme vous avez associé l'ID ressource à la référence de noeud final créée précédemment, tous les messages entrants ciblés sur la référence de noeud final contiendront les informations d'ID ressource sous forme de paramètre de la référence dans l'en-tête SOAP du message. Comme l'ID ressource est transmis dans l'en-tête SOAP, il n'est pas nécessaire de le présenter sur l'interface de service Web. Lorsque WebSphere Application Server reçoit le message, il place ces informations dans le contexte du message sur l'unité d'exécution. Etendez l'implémentation pour effectuer les opérations suivantes :
    1. Récupérez l'ID de l'instance de ressource dans le contexte du message, à l'aide de la méthode EndpointReferenceManager.getReferenceParameterFromMessageContext(QName resource_id_name).
    2. Réacheminez le message vers l'instance de ressource appropriée.
  4. Pour configurer un client de façon à ce qu'il communique avec le service, utilisez la référence de noeud final générée par le service lors de la première étape pour envoyer les messages au noeud final.
    1. Récupérez un objet Stub en recherchant le service dans l'interface JNDI (Java™ Naming and Directory Interface) ou créez un objet Call vide.
    2. Associez la référence du noeud final à l'objet proxy. Utilisez la méthode setProperty(String property_name, Object value) de l'objet Stub ou Call. Utilisez la constante WS-Addressing WSADDRESSING_DESTINATION_EPR comme nom de propriété et la référence du noeud final comme valeur.
      Cette procédure configure automatiquement l'objet Stub ou Call pour représenter le service Web (ou l'instance de ressource si votre interface utilise un service Web présentant une instance de ressource) de la référence du noeud final. Pour les objets Call, cette procédure inclut la configuration de l'interface et des métadonnées du noeud final (éléments portType et port) associées à la référence du noeud final.
      Remarque : Si les métadonnées de la référence du noeud final entrent en conflit avec les informations déjà associées au message sortant (par exemple, si l'objet Stub est configuré pour représenter une interface différente, une exception javax.xml.rpc.JAXRPCException est lancée lors des tentatives d'appel du noeud final.

    Les appels sur l'objet Stub ou Call sont désormais destinés au service Web ou à l'instance de ressource définis par la référence du noeud final. Lors d'un appel, le produit ajoute à l'en-tête du message les propriétés MAP appropriées, telles que le paramètre de référence contenu dans la référence du noeud final qui identifie une ressource cible.

Résultats

Le service Web et le client sont configurés de façon à utiliser les références de noeud final via la prise en charge de WS-Addressing.

Création d'une interface de service Web qui renvoie une référence de noeud final au service cible

Les exemples suivants correspondent aux étapes 1 à 4 de la procédure. Les exemples montrent comment une organisation informatique peut utiliser les services Web pour gérer un réseau d'imprimantes. Cette entreprise peut représenter chaque imprimante sous forme de ressource dont l'adressage est effectué via une référence de noeud final (EndpointReference). Les exemples suivants montrent comment coder un tel service à l'aide des API (application programming interfaces) WS-Addressing (Web Services Addressing) fournies par WebSphere Application Server et JAX-WS.

L'entreprise TI implémente un service PrinterFactory qui fournit un élément portType CreatePrinter. Cet élément portType accepte un message CreatePrinterRequest pour créer une ressource qui représente une imprimante logique et répond par une référence de noeud final qui est une référence à la ressource.

La définition WSDL de ce service PrinterFactory peut inclure le code suivant :
<wsdl:definitions targetNamespace="http://example.org/printer" ...
                  xmlns:pr=" http://example.org/printer">
  <wsdl:types>
    ...
    <xsd:schema...>
      <xsd:element name="CreatePrinterRequest"/>
      <xsd:element name="CreatePrinterResponse" 
                   type="wsa:EndpointReferenceType"/>
    </xsd:schema>
  </wsdl:types>
  <wsdl:message name="CreatePrinterRequest">
    <wsdl:part name="CreatePrinterRequest" 
               element="pr:CreatePrinterRequest" />
  </wsdl:message>
  <wsdl:message name="CreatePrinterResponse">
    <wsdl:part name="CreatePrinterResponse" 
               element="pr:CreatePrinterResponse" />
  </wsdl:message>
  <wsdl:portType name="CreatePrinter">
    <wsdl:operation name="createPrinter">
      <wsdl:input name="CreatePrinterRequest" 
                  message="pr:CreatePrinterRequest" />
      <wsdl:output name="CreatePrinterResponse"
                  message="pr:CreatePrinterResponse" />
    </wsdl:operation>
  </wsdl:portType>
</wsdl:definitions>

L'opération CreatePrinter dans l'exemple précédent renvoie un objet wsa:EndpointReference qui représente la ressource Printer créée. Le client peut utiliser cette référence de noeud final pour envoyer des messages à l'instance de service qui représente l'imprimante.

La méthode createPrinter illustrée dans l'exemple ci-dessous crée une référence de noeud final vers le service Printer. L'opération permet ensuite d'obtenir l'identificateur de l'instance de la ressource d'imprimante particulière, et l'associe avec la référence de noeud final. Enfin, la méthode createPrinter convertit l'objet EndpointReference, qui représente désormais la nouvelle imprimante, en un objet W3CEndpointReference et renvoie la référence du noeud final convertie.

import com.ibm.websphere.wsaddressing.EndpointReferenceManager;
import com.ibm.websphere.wsaddressing.EndpointReference;
import com.ibm.websphere.wsaddressing.jaxws.EndpointReferenceConverter;
import com.ibm.websphere.wsaddressing.jaxws.W3CEndpointReference;

import javax.xml.namespace.QName;

public class MyClass {

    // Create the printer
    ...

    // Define the printer resource ID as a static constant as it is required in later steps
    public static final QName PRINTER_ID_PARAM_QNAME = new QName("example.printersample",
                                                                 "IBM_WSRF_PRINTERID", "ws-rf-pr" ); 
    public static final QName PRINTER_SERVICE_QNAME = new QName("example.printer.com", "printer", "..."); 
    public static final String PRINTER_ENDPOINT_NAME = new String("PrinterService");
    
    public W3CEndpointReference createPrinter(java.lang.Object createPrinterRequest)
    throws Exception {
     // Create an EndpointReference that targets the appropriate WebService URI and port name.
     EndpointReference epr =  EndpointReferenceManager.createEndpointReference(PRINTER_SERVICE_QNAME, 
                                                                               PRINTER_ENDPOINT_NAME);

     // Create or lookup the stateful resource and derive a resource
     // identifier string.
     String resource_identifier = "...";

     // Associate this resource identifier with the EndpointReference as  
     // a reference parameter.
     // The choice of name is arbitrary, but should be unique     
     // to the service.
     epr.setReferenceParameter(PRINTER_ID_PARAM_QNAME,resource_identifier);
     // The endpoint reference now targets the resource rather than the service.
     ...

     return EndpointReferenceConverter.createW3CEndpointReference(epr);
    }
}

Grâce à l'implémentation du service Web décrite précédemment, l'instance de ressource de l'imprimante est maintenant associée à un identificateur unique imbriqué à la référence de noeud final. Cet identificateur devient un paramètre de référence dans l'en-tête SOAP des messages suivants ciblés sur le service Web, et peut être utilisé par le service Web pour faire correspondre les messages entrants à l'imprimante appropriée.

Lorsqu'un service Web reçoit un message contenant des propriétés d'adressage de message WS-Addressing, WebSphere Application Server traite ces propriétés avant que le message ne soit transmis au noeud final de l'application et il les définit dans le contexte du message dans l'unité d'exécution. L'application de service Web d'imprimante accède aux paramètres de référence associés au noeud final cible de l'objet WebServiceContext, comme le montre l'exemple suivant :

import com.ibm.websphere.wsaddressing.EndpointReferenceManager; 
...
 // Initialize the reference parameter name
 QName name = new QName(..);
 // Extract the String value.
 String resource_identifier = 
        EndpointReferenceManager.getReferenceParameterFromMessageContext(PRINTER_ID_PARAM_QNAME);

L'implémentation du service Web peut transférer les messages à partir de l'identité de l'imprimante obtenue avec la méthode getReferenceParameterFromMessageContext vers les instances d'imprimante appropriées.

Le client crée un proxy JAX-WS pour l'imprimante et le convertit en un objet BindingProvider. Il associe ensuite l'objet EndpointReference obtenu au contexte de demande de l'objet BindingProvider, comme illustré dans l'exemple ci-après.
import javax.xml.ws.BindingProvider;
...

 javax.xml.ws.Service service= ...;
 Printer myPrinterProxy = service.getPort(portName, Printer.class);
	
 javax.xml.ws.BindingProvider bp = (javax.xml.ws.BindingProvider)myPrinterProxy;
	 
 // Retrieve the request context for the BindingProvider object
 Map myMap = myBindingProvider.getRequestContext();  

 // Associate the endpoint reference that represents the new printer to the request context 
 // so that the BindingProvider object now represents a specific printer instance.
 myMap.put(WSADDRESSING_DESTINATION_EPR, destinationEpr);

...
L'objet BindingProvider représente désormais la nouvelle instance de ressource d'imprimante et peut être utilisé par le client pour envoyer des messages à l'imprimante via le service Web d'imprimante. Lorsque le client appelle l'objet BindingProvider, WebSphere Application Server ajoute les propriétés d'adressage de message appropriées à l'en-tête du message qui correspond dans ce cas à un paramètre de référence figurant dans la référence du noeud final identifiant la ressource d'imprimante cible.

Le client peut également utiliser un objet Stub ou Call JAX-RP qu'il peut configurer pour représenter la nouvelle imprimante. Voici un exemple d'utilisation de l'objet Call.

import javax.xml.rpc.Call;
...
 :
 // Associate the endpoint reference that represents the new printer with the call.
 call.setProperty(
        "com.ibm.websphere.wsaddressing.WSAConstants.
                             WSADDRESSING_DESTINATION_EPR ", epr);

Du point de vue du client, la référence de noeud final est opaque. Le client ne peut pas interpréter le contenu des paramètres de référence de noeud final et il ne doit pas tenter de les utiliser d'une autre manière. Les clients ne peuvent pas créer directement des instances de références de noeud final, car les paramètres des références sont privés pour le fournisseur de services et les clients doivent obtenir les références de noeud final auprès de celui-ci, par exemple via un service de fabrique de fournisseur, puis les utiliser pour diriger les opérations du service Web vers le noeud final représenté par la référence de noeud final, comme illustré ici.

Que faire ensuite


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_wsa_rap
Nom du fichier : twbs_wsa_rap.html