Project:Omega.org

Par Apple Computer, Inc. © 2003 (Dernière mise à jour Septembre 2002),

Traduit par Thierry, 18/06/2003.

Ce chapitre aborde la façon de tirer profit des Services Web qui sont disponibles dans Mac OS X et présente un nouveau framework qui supporte le WebServicesCore au sein du framework Core Services.

Boîtes à Outils des Services Web

Il y a actuellement plus de 50 implémentations différentes de XML-RPC tout comme il y a plus de 80 implémentations de SOAP disponibles pour les développeurs. Beaucoup de ces implémentations sont fournies sous forme de boîtes à outils (toolkits). Ces boîtes à outils XML-RPC et SOAP fonctionne en général en établissant une liaison entre l’environnement d’exécution (runtime) d’un langage et un format de séquençage. La boîte à outils requise devrait correspondre à votre modèle d’objets dans la plupart des cas.

Si, par exemple, vous avez une application écrite en Java, vous utiliserez probablement une des implémentations établies de Java SOAP ou XML-RPC du fait que ces boîtes à outils s’adapteront à votre modèle d’objets. Ainsi, la boîte à outil pour Services Web la plus utile sera celle qui sera le mieux adaptée à votre environnement d’exécution et au framework de votre application.

Support des Services Web sous Mac OS X (10.1 ou plus)

Le support de SOAP 1.1 et de XML-RPC sont fournis dans Mac OS X (10.1) via les événements Apple––les mêmes “Apple events” que vous pouvez utiliser, par exemple, pour écrire un script basé sur le Finder. XML-RPC et SOAP 1.1 sont en effet tous les deux “fondus” dans le Apple Event Manager. Du fait que ce support est directement là dans le Event Manager, vous obtenez le support d’AppleScript “pour rien”.

La plate-forme Macintosh apporte aux développeurs un accès de haut niveau très populaire aux Services Web publiques et entreprises. Un des avantages qui font la différence tient dans le fait que vous n’avez pas à aller sur Internet et télécharger la boîte à outils pour enfin vérifier que vos clients ont la même.

Un Apple event est une méthode de communication interprocess. Le support des Services Web fonctionne par “détournement” d’un mode d’adressage––typeApplicationURL––pour un Apple event. Sous Mac OS X (10.1 ou plus), en utilisant un Apple event distant, vous pouvez envoyer une méthode binaire à une autre application ou à un autre ordinateur Mac OS X et, pour les modes d’adressage qui sont HTTP, ces méthodes sont traitées comme un Service Web.

Cela est accompli sans aucun changement d’API du Apple Event Manager, seulement par l’autorisation de types de donnée supplémentaires pour lesquels il est suggéré au Apple Event Manager que la méthode à invocationer utilisera le framework spécifique SOAP.

Exemple Canonique : XML-RPC au-dessus d’Apple Event

L’exemple canonique XML-RPC, avec à la fois un message et une réponse, est assez simple :

1. Vous invocationez une méthode, example.getStateName, sur le serveur <http://betty.userland.com:80/RPC2>.
2. Quand vous en arrivez à envoyer le message, vous ouvrez une connexion HTTP.
3. Puis vous faites un post HTTP vers ce site avec un document XML. Le document XML prend un seul nombre entier comme paramètre et renvoi une chaîne.

Envoyer un Message

La structure XML illustrée dans le Listing 2-1 comporte à la fois un nom de méthode <examples.getStateName> et un paramètre.

La balise élémentaire est <i4>, ce qui indique que l’élément est typé en nombre entier long.

Le serveur répond et spécifie que la valeur de retour pour cette méthode est la chaîne “South Dakota”. Le server renvoie un tableau constitué des 50 états et l’élément 41 du tableau sans ordre particulier.

Listing 2-1 : Une structure XML spécifiant le nom d’une méthode et un paramètre

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
    <methodName>examples.getStateName</methodName>
    <params>
        <param>
            <value>
                <i4>41</i4>
            </value>
        </param>
</params>
</methodCall>

Obtenir une Réponse

Listing 2-2 : Une structure XML avec la valeur de retour spécifiée

<?xml version="1.0"?>
<methodResponse>
    <params>
        <param>
            <value>South Dakota</value>
        </param>
    </params>
</methodResponse>

Utiliser les Apple Events pour Cibler un Site Web

Le processus d’utilisation des Apple events pour cibler un site Web est direct, comme illustré dans l’exemple de code de cette section. Vous n’aurez qu’à suivre simplement ces étapes :

1. Créer la liste des paramètres pour l’invocation de la méthode. Dans cet exemple, vous créez une liste avec un seul nombre entier. Puis, placer la valeur 41 dans la liste des paramètres.
2. Créer l’objet direct. Dans l’implémentation Apple Event des Services Web, l’objet direct contient à la fois le nom de la méthode et la liste des paramètres, du fait que cela est transféré au sous-système qui gère les invocations RPC. L’objet direct d’un invocation à Service Web XML-RPC et SOAP contient deux champs : le champ keyRPCMethodParam et le champ keyRPCMethodName.
3. Créer l’evènement que vous souhaitez envoyer. Tout comme dans le Apple Event Manager normal, vous créez l’évènement cible, dans ce cas une URL applicative de type caractère, puis vous indiquez à cet l’emplacement que vous allez poster l’évènement. Vous créez l’evènement avec un ID spécial de classe évènementielle, kAERPCClass.
4. Envoyer l’évènement et gérer la réponse. Les Apple events peuvent être envoyés de manière synchrone ou asynchrone. Si la réponse est asynchrone, vous verrez la réponse sous la forme d’un Apple event.

Dans cet exemple, vous envoyer l’évènement et attendez la réponse. Cela ouvre la connexion vers le site distant, envoie l’évènement, obtient la réponse et la renvoie dans un descripteur d’Apple event. Vous pouvez alors tirer de la réponse l’objet direct, qui est une chaîne de caractères.

Créer la Liste des Paramètres

Vous créez la liste des paramètres, qui se résume à un seul nombre entier.

AEDesc paramList;AECreateList(NULL, 0, true, &paramList);
SInt32 ixState = 41;AEPutPtr(&paramList, 0, typeSInt32, &ixState, sizeof(ixState));

Créer l’Objet Direct pour un Apple XML-RPC

Dans ce cas, l’objet direct est un enregistrement.

AERecord directObject;AECreateList(NULL, 0, true, &directObject);

L’objet comporte deux champs :

AEPutParamDesc(&directObject, keyRPCMethodParam, &paramList)
            AEPutParamPtr(&directObject, keyRPCMethodName, typeChar,
?
            “examples.getStateName”, strlen(...))

Vous placez la liste des paramètres dans l’objet direct. Remarquez que cette liste de paramètre n’est constituée que d’un seul élément.

AEList paramList;
AECreateList(NULL, 0, false, &paramList);
SInt32 ixState = 41;
AEPutPtr(&paramList, 0, typeSInt32, &ixState, sizeof(ixState));
AEPutParamDesc(&directObject, keyRPCMethodParam, &paramList);
AEDIsposeDesc(&paramList);

Vous placez le nom de la méthode à invocationer dans l’objet direct.

const char* methodName = "examples.getStateName";
AEPutParamPtr(&directObject, kRPCMethodName, typeChar, methodName, strlen(methodName));

Créer l’Evènement

Vous décrivez l’adresse (le point final).

AEDesc addr; AECreateDesc(typeApplicationURL, "http://betty.userland.com/RPC2", strlen(...), &addr); 

Vous construisez l’évènement.

AEDesc event;
AECreateAppleEvent(kAERPCClass, kAEXMLRPCScheme, &addr, ..., &event);
AEPutParamDesc(&event, keyDirectObject, &directObject);

Envoyer l’Evènement

Vous envoyez l’évènement puis attendez la réponse.

AEDesc reply;
AESend(&event, &reply, kAEWaitReply, ..., ...);

AEGetParamPtr(&reply, keyDirectObject, typeChar,
                buffer, sizeof(buffer), ..., &actualSize);
printf(“State: %.*sn”, actualSize, buffer);

La réponse de la méthode est contenue à l’intérieur de l’objet direct de la réponse Apple event.

Cette séquence d’actions est illustrée dans la Figure 2-1.

Figure 2-1 : Une séquence d’actions utilisées pour cibler un site Web en utilisant les Apple Events

Utiliser les Web Services Core sous Mac OS X version 10.2

Bien que la méthode reposant sur les Apple Events décrite page précédente est pratique et facile à implémenter, il se peut qu’elle décrive un processus placé à un niveau trop haut dans la pile protocole, au sein de la chaîne des librairies du système. Certains développeurs pourront peut-être souhaiter un framework plus avancé avec des fonctionnalités de bas niveau. Dans ce but, Mac OS X version 10.2 introduit un nouveau framework qui implémente WebServicesCore à l’intérieur des Core Services.

Ce framework de bas niveau se positionne aux côtés de CFNetwork, de Core Foundation et de CarbonCore, comme illustré Figure 2-2. Cela constitue un sous-framework, placé dans l’ombre des CoreServices, qui vous permet d’accèder au modèle basique de l’environnement d’exécution du système Mac OS X. Il est disponible pour toutes les applications, les plugins, les outils et les démons.

Le framework n’a aucune dépendance vis à vis du Window Server ou de la fenêtre de login. Vous n’avez pas à être un utilisateur en mode Console, vous pouvez donc vous en servir à partir de n’importe quelle application CGI. Il est complètement intégré au système Mac OS X, au sein des Core Services, et s’appuit sur CFXMLParser et CFNetwork. Le framework est sans thread et basé sur la boucle d’exécution.

Il vous encourage à lancer des requêtes dans la boucle d’exécution et à recevoir une réponse de manière asynchrone. Du fait qu’il est basé sur le Core Foundation, vous devez créer des objets de type CFType pour vos chaînes, enregistrements, dictionnaires et tables. Si vous êtes un programmeur Objective-C, vous disposez de ponts “sans péage” vers les types Objective-C. C’est aussi une API procédurale simple.

La Figure 2-2 illustre la position des WS Core aux côtés des Core Services de Mac OS X version 10.2.

Figure 2-2 : WS Core aux côtés des Core Services de Mac OS X version 10.2

Ensemble de Fonctions Bas Niveau

L’API WebServicesCore, qui est décrite dans le chapitre 3, “Services Web : Référence”, est indépendante du protocole. Que ce soit pour SOAP ou XML-RPC, c’est la même chose. La différence tient dans les propriétés que vous mettez en place avec l’objet WSMethodinvocationRef. Vous pouvez avoir des opérations synchrones de type “one-shot”, ou des opérations asynchrones avec rinvocations.

Le framework est basé sur des avancées de CFNetwork, donc quand CFNetwork est évolue, WSCore évolue en même temps. Vous obtenez un support avancé des pare-feux et des proxies. Il y a un accès total au CFHTTPMessage.

L’approche est conceptuellement similaire à celle de la programmation CFStream. Ce modèle est un peu plus simple en cela que les invocations synchrones vous donnent un seul rinvocation avec le résultat de l’invocation.

Le framework apporte le support HTTP / HTTPS en version 1.0. De futures versions supporteront probablement d’autres modes de transport.

WSMethodinvocationRef

L’objet le plus utile de l’API WebServicesCore est une structure opaque invocationée WSMethodinvocationRef. Cette structure est créée de la manière suivante :

1. Vous invocationez une méthode à l’intérieur du framework, en lui communiquant l’URL d’un point final, un nom de méthode et un paramètre prototype qui spécifie le style d’encodage, c’est à dire, si c’est une méthode XML-RPC ou SOAP v1.1 que vous souhaitez envoyer.
2. Vous ajoutez alors des propriétés à la référence de l’invocation qui peuvent contrôler certaines des règles de séquençage et des options de transport, telles que l’action SOAP ou l’espace de nommage de la méthode.
3. Vous passez les paramètres de l’invocation en CFTypes. Puis vous pouvez soit la plannifier dans une boucle d’exécution, soit l’invocationer de manière synchrone. Elle vous renvoie un dictionnaire en guise de résultat.

Création de l’Objet WSMethodinvocationRef

Vous créez l’objet WSMethodinvocationRef en utilisant la méthode WSMethodinvocationCreate, qui prend comme argument l’URL CF ou NS. Le nom de la méthode est du type CFString. Le protocole est une de ces constantes CFString :

• kWSXMLRPCProtocol
• kWSSOAP1999Protocol

L’en-tête sous Mac OS X version 10.2 est : WSMethodinvocation.h

WSMethodinvocation—Réglage des Paramètres

Ensuite, vous réglez les paramètres de l’invocation. L’invocation que vous effectuez, “WSMethodinvocationSetParameters”, prend comme argument la référence sur laquelle vous allez positionner les paramètres. Un doctionnaire contenant le nom des paramètres et leur valeurs, et une table, optionnelle pour les messages SOAP, qui spécifie dans quel ordre les paramètres doivent être séquencés. La table n’est pas optionnelles pour les invocations de méthodes XML-RPC du fait que XML-RPC se base sur la position des paramètres qu’il doit connaître. Quelques méthodes SOAP requièrent que cet ordre soit aussi spécifié par le fournisseur de services. C’est pour cela que vous pourriez souhaiter avoir le second paramètre de la table.

Le CFDictionary contient le nom du paramètre et un CFType pour la valeur du paramètre, qui peut avoir l’un des types primitifs CFTypes ou un type composé. Les types qui sont automatiquement séquencés sont CFBoolean, CFNumber, CFDate, CFString, CFData, CFArray, CFDictionary. Vous pouvez aussi ajouter des clés méta-données à un CFDictionary pour spécifier des espaces de nommage personnalisé, quand il sera séquencé pour SOAP, et l’ordre des paramètres. Vous pouvez construire des types complexes en CFDictionary.

Les types sont séquencés en utilisant l’encodage “Section 5” de SOAP. L’information relative au type lorsque le type est personnalisé n’est pas présente dans l’invocation. Si vous avez des types personnalisés, vous devez écrire votre propre code d’organisation du dictionnaire, à moins qu’un analyseur WSDL sensible au shéma soit rendu disponible.

Construction du Dictionnaire et de la Table Ordre des Paramètres

Les étapes suivantes décrivent comment vous devriez construire le CFdictionary et la table ordre des paramètres.

1. Vous invocationez CFDictionaryAddValue avec un dictionnaire transformable que vous avez créé :
   

   CFDictionaryAddValue(dict, CFSTR(“param1”), CFSTR(“Steve”));
   CFDictionaryAddValue(dict, CFSTR(“param2”), CFSTR(“John”));
   CFArrayAddValue(order, CFSTR(“param1”));
   CFArrayAddvalue(order, CFSTR(“param2”));
   WSMethodinvocationSetParameters(ref, values, order);

2. Ajoutez les noms de paramètre à la table des noms de paramètre.
3. Réglez les paramètres sur la réf.
4. Invoquez la avec un simple invocation : WSMethodinvocationInvoke.

En résultat, vous aurez un CFDictionary, que vous devrez libérer. Cela n’est pas le résultat réel de la méthode. Le CFDictionary contient le résultat de la méthode tout comme des informations optionnelles de déboguage provenant de la requête, le XML sortant et retourné, les en-têtes HTTP et les erreurs HTTP, de façon à ce les données soient aussi disponibles dans ce dictionnaire au cas où il y aurait une erreur de transport réseau.

Les en-têtes SOAP sont retournées sous la forme de CFStringRef dans un CFArray kWSSOAPHeaderValues.

Les erreurs réseau doivent en principe être documentées (kWSNetworkStreamFaultString).

WSMethodinvocation—Dictionnaire RésultantVous faites cette invocation et si …

WSMethodResultIsFault(resultDict)CFTypeRef faultString = CFDictionaryGetValue(result, kWSFaultString)

Alors :

kWSFaultCode, kWSFaultExtra

Sinon, pas d’erreur :

CFTypeRef myResult = CFDictionaryGetValue(?result, kWSMethodinvocationResult)

Le résultat de cela est un CFString.

WSMethodinvocation—Asynchrone

1. Réglez le client (connexion en retour). Cela comprend le pointeur d’informations que vous souhaiterez passer à votre rinvocation, tout comme certains rinvocations réglés pour le pointeur d’informations pour lui permettre d’être une référence comptée.
2. Une fois que vous réglé le rinvocation, vous pouvez programmer cette invocation dans une ou plusieurs boucles d’exécution. Alors que ces boucles s’exécuteront, l’invocation va traverser sa machine de résidence, ce qui résultera en l’obtention de données ou d’une erreur. Une fois terminée, elle invocationera votre rinvocation durant cette boucle d’exécution et vous pourrez traiter le résultat.
3. Rinvocation invoqué dans la boucle d’exécution lorsque l’invocation est terminée.
4. Peut être programmée sur plusieurs boucles pour implémenter des groupes de threads.

Support WSDL

Actuellement, la première release des Services Web ne comprend pas une API WDSL. Un outil est disponible dans /Developer/Tools/WSMakeStubs pour générer des “stubs” statiques. Cet outil analyse le WSDL et produit des modèles en C++, Objective-C et AppleScript. Divers degrès de complexité sont disponibles dans les stubs générés. Le stub adhère à l’encodage “Section 5” et l’organisation simple.

Textes originaux en anglais sur developer.apple.com : WebServices - Tasks

Thierry Développer pour le Web Mac OS X, Service Web, SOAP, WSDL, XML-RPC