Retourner des images par Service Web (via SOAP)

Date de publication : Mars 2005

4ème Dimension propose la conversion automatique de pratiquement tous les types natifs 4D pour envoi dans une réponse SOAP, à l'exception des images. Heureusement, il est possible d'inclure des BLOBs dans les réponses SOAP de sorte que l'on peut inclure des images en les convertissant au préalable à l'aide de la commande IMAGE VERS BLOB.

I. Introduction
II. Résumé du système
III. Écouter et répondre aux requêtes SOAP
IV. Fournir une liste des images disponibles
Table Image
GetPictureList
Fournir une liste des formats d'images disponibles
V. Charger, convertir et retourner des images
VI. Tâche de client SOAP : récupérer une image
VII. Retourner des informations additionnelles
VIII. Bases exemples

I. Introduction

4ème Dimension version 2003 et ultérieure, propose la publication de méthodes comme Services Web. Concrètement les requêtes et réponses de Services Web sont des messages SOAP (Simple Object Access Protocol) qui suivent les règles d'encodage des données XML. 4ème Dimension propose la conversion automatique de pratiquement tous les types natifs 4D pour envoi dans une réponse SOAP, à l'exception des images. Heureusement, il est possible d'inclure des BLOBs dans les réponses SOAP de sorte qu'il est possible d'inclure des images en les convertissant au préalable à l'aide de la commande IMAGE VERS BLOB.

Le retour d'images via SOAP est utile dans plusieurs situations, par exemple les scénarios suivants :

Un système de publication Web demande des images statiques ou dynamiques par SOAP pour les inclure dans des pages Web;
Un système de base de données centralisé 4ème Dimension joue le rôle d'une bibliothèque d'images ou d'archivage pour un nombre indéterminé de clients SOAP;
Un système de base de données centralisé 4ème Dimension jour le rôle de pivot de distribution d'images pour un nombre indéterminé de clients.

Cette note technique détaille les mécanismes de conversion et "d'empaquetage" d'images dans les réponses SOAP. La base de démo comprend du code fonctionnel réalisant un système simple de serveur d'images reposant sur SOAP.

Note : Pour plus d'information sur les types de données supportés par SOAP, référez-vous au manuel de référence du langage de 4ème Dimension ou à la note technique 4D-200503-07-FR "Retourner des données par Web Service (via SOAP)".

II. Résumé du système

Le serveur d'image accomplit les tâches suivantes :

Écouter et répondre aux requêtes SOAP ;
Fournir une liste des images disponibles ;
Fournir une liste des formats d'images possibles ;
Charger, convertir et retourner les images.

Nous allons commenter chacune de ces tâches plus en détail.

III. Écouter et répondre aux requêtes SOAP

Pour publier des méthodes comme Services Web, les conditions suivantes doivent être remplies :

Le serveur Web natif de 4ème Dimension doit fonctionner ;
Les préférences ci-dessous doivent être activées :
Préférences -> Web -> Web Services -> Autoriser requêtes Web Services
La propriété ci-dessous doit être activée pour chaque méthode publiée :
Propriétés de la méthode/Offert comme Web Service

Une fois ces étapes de configuration effectués, 4ème Dimension gère automatiquement tous les aspects d'écoute et de réponse aux requêtes SOAP.

IV. Fournir une liste des images disponibles

Table Image

La démo propose des images stockées dans une table nommée [Images], représentée ci-dessous :

Le champ Name sert de clé unique pour les enregistrements de la table. En environnement de production, une clé du type entier long unique et non modifiable serait un meilleur choix. Une version améliorée du système pourrait gérer des attributs supplémentaires comme la date de prise de la photo, des notes sur le matériel photo et les réglages utilisés, le lieu de la prise de vue, des informations de contact, des mots-clés et le détail de la licence.

GetPictureList

La démo propose une méthode de Web Service SOAP nommée GetPictureList qui retourne un tableau comprenant les noms de toutes les images disponibles sous forme d'enregistrements dans la base. Voici un exemple de contenu de ce tableau :

Baby Rhino and Mother
Baby White Rhino
Cache flushing image
Day Gekko
Dog
Leopard
Magnifying glass
Spotted Eagle Rays
Superb Fairy Wren
Three Elephants
Yellow-Tailed Black Cockatoos
Zebra

Le code pour la fonction GetPictureList est fourni ci-dessous :

`--------------------
TOUT SELECTIONNER([Images])
TRIER([Images];[Images]Name)
TABLEAU ALPHA(80;getPicture_ImageNames_as;0)
SELECTION VERS TABLEAU([Images]Name;getPicture_ImageNames_as)
LIBERER ENREGISTREMENT([Images])

DECLARATION SOAP(getPicture_ImageNames_as;Est un tableau chaîne ;SOAP sortie ;"outPictureNames")
`--------------------

Dans une version améliorée du système, la fonction GetPictureList pourrait être réécrite pour accepter des arguments de recherche par taille d'image, auteur ou d'autres attributs comme la date ou les mots-clés.

Fournir une liste des formats d'images disponibles

4ème Dimension stocke et prévisualise nativement les images dans le format PICT. PICT constitue une famille de formats MacOS qui sont rarement visualisables dans les navigateurs Web ou sur d'autres plateformes. Heureusement, 4ème Dimension sait convertir les images en GIF et, si QuickTime 4 ou supérieur est installé, dans n'importe quel format supporté par l'installation Quicktime du serveur. En utilisant la commande LISTE TYPES IMAGES, le serveur d'images peut détecter tous les formats disponibles et les retourner sous forme de liste aux clients du Service Web. Un bénéfice de cette approche réside dans le fait que seul le serveur centralisé d'images requiert QuickTime. Les clients SOAP peuvent demander l'image dans un format adapté à l'affichage sur leur système, que ce soit GIF ou JPEG...

Le code de la méthode GetPictureFormatList publiée comme méthode SOAP GetPictureFormatList :

`--------------------
TABLEAU TEXTE(getPictureFormatMimeTypes_at;0)
COPIER TABLEAU(<>pictureFormatMimeTypes_at;getPictureFormatMimeTypes_at)
DECLARATION SOAP(getPictureFormatMimeTypes_at;Est un tableau texte ;SOAP sortie ;"outSupportedMIMETypes")
`--------------------

Cette méthode copie un tableau interprocess nommé <>pictureFormatMimeTypes_at dans un tableau process nommé getPictureFormatMimeTypes_at. Les types MIME sont chargés une fois au démarrage dans le tableau interprocess. Ces valeurs doivent être copiées dans un tableau process car les réponses SOAP ne peuvent retourner que le paramètre traditionnel $0, des variables ou des tableaux process.

Note : Pour plus d'information sur les sources de données supportées pour les réponses SOAP, référez-vous au manuel de référence du langage de 4ème Dimension ou à la note technique 4D-200503-07-FR "Retourner des données par Service Web (via SOAP)".

La liste des types MIME stockée dans le tableau <>pictureFormatMimeTypes_at array est remplie par une méthode 4D nommée pictureInitializeFormatCodes qui s'exécute au démarrage. La commande LISTE TYPES IMAGES retourne les codes de type QuickTime sur quatre caractères, non pas les types MIME. Les types MIME sont indépendants de plate-forme et constituent un choix mieux adapté aux Services Web. La méthode pictureInitializeFormatCodes convertit les codes QuickTime en types MIME. Dans la démo, la conversion de code QuickTime en type MIME est assurée grâce à la table [Picture_Format_Codes], représentée ci-dessous :

Le code de la méthode pictureInitializeFormatCodes :

   ` -----------------------------------------------------
   ` Réception des codes d'images depuis Quicktime
   ` -----------------------------------------------------
TABLEAU ALPHA(4;<>pictureFormatCodes_as;0)
LISTE TYPES IMAGES(<>pictureFormatCodes_as)

   ` -----------------------------------------------------
   ` Ajout de 'GIFf', si non présent, car il des supporté directement par 4D
   ` -----------------------------------------------------
C_ENTIER LONG($index)
$index:=0
$index:=Chercher dans tableau(<>pictureFormatCodes_as;"GIFf") `GIF ne requiert pas Quicktime
Si ($index<1)
   INSERER LIGNES(<>pictureFormatCodes_as;1;1)
   <>pictureFormatCodes_as{1}:="GIFf"
Fin de si

   ` -----------------------------------------------------
   ` Construction d'un tableau des types MIME
   ` -----------------------------------------------------
C_ENTIER LONG($count)
$count:=0
$count:=Taille tableau(<>pictureFormatCodes_as)

TABLEAU TEXTE(<>pictureFormatMimeTypes_at;$count)

C_ALPHA(4;$type_s)
Boucle ($index;$count;1;-1) ` Bouclons à l'envers car il se peut que nous détruisions des éléments en chemin
   $type_s:=<>pictureFormatCodes_as{$index}
   CHERCHER([Picture_Format_Codes];[Picture_Format_Codes]Code=$type_s)

   Si (Enregistrements trouves([Picture_Format_Codes])=1)
      <>pictureFormatMimeTypes_at{$index}:=[Picture_Format_Codes]MIME_Type
   Sinon
      SUPPRIMER LIGNES(<>pictureFormatCodes_as;$index;1)
      SUPPRIMER LIGNES(<>pictureFormatMimeTypes_at;$index;1)
   Fin de si

LIBERER ENREGISTREMENT([Picture_Format_Codes])

Fin de boucle

V. Charger, convertir et retourner des images

La démo propose plusieurs fonctions de Services Web pour retourner des images et des données sur les images. La plus simple est la méthode getPicture publiée comme méthode SOAP getPicture. La méthode attend deux paramètres d'entrée, un nom d'image et un type MIME d'image. Un développeur de client de Service Web peut découvrir les valeurs acceptées pour ces deux arguments en appelant les fonctions GetPictureList et GetPictureFormatList. Cette approche permet aux clients de construire dynamiquement et interactivement des requêtes valides afin d'obtenir des images dans des formats spécifiques.

Ci-dessous une version résumée de la méthode getPicture :

   ` -----------------------------------------------------
   ` Déclare les entrées/sorties pour 4DWSDL et la construction du message SOAP
   ` -----------------------------------------------------
DECLARATION SOAP($1;Est un texte ;SOAP entrée ;"inPictureName")
DECLARATION SOAP($2;Est un texte ;SOAP entrée ;"inPictureMimeType")
DECLARATION SOAP(getPicture_ResultPicture_x;Est un BLOB ;SOAP sortie ;"outPictureBlob")

   ` -----------------------------------------------------
   ` Déclare les paramètres pour l'exécution et la compilation
   ` -----------------------------------------------------
C_TEXTE($1;$pictureName_t)
C_TEXTE($2;$pictureMimeType_t)

   ` -----------------------------------------------------
   ` Prépare les valeurs de retour
   ` -----------------------------------------------------
C_BLOB(getPicture_ResultPicture_x)
   ` <-- variable de sortie (nous n'utilisons pas $0 car les images peuvent être importantes)
FIXER TAILLE BLOB(getPicture_ResultPicture_x;0)

   ` -----------------------------------------------------
   ` Effectue le contrôle d'erreur sur les entrées
   ` -----------------------------------------------------
C_ENTIER LONG($errorCode_l)
$errorCode_l:=0

C_ENTIER LONG($soapFaultType_l)
$soapFaultType_l:=SOAP erreur client

Si (Nombre de parametres<2)
   $errorCode_l:=1 ` Pas assez de paramètres

Sinon
   $pictureName_t:=$1
   $pictureMimeType_t:=$2
   CHERCHER([Images];[Images]Name=$pictureName_t)
   C_ALPHA(4;$format_s)
   $format_s:=""
   $format_s:=pictureGet4DCodeFromMimeType ($pictureMimeType_t)

   Au cas ou
      : ($format_s="")
      $errorCode_l:=2 ` Type MIME demandé non supporté ou non reconnu
      : (Enregistrements trouves([Images])=0)
      $errorCode_l:=3 ` Image demandée non trouvée
      : (Enregistrements trouves([Images])>1)
      $errorCode_l:=4 ` Trouvé plusieurs images
   Fin de cas

Fin de si ` (Nombre de parametres<2)

Si ($errorCode_l=0)
   ` -----------------------------------------------------
   ` Corps de la méthode
   ` -----------------------------------------------------
   ` Pas de $0 nécessaire. 4D lit les déclarations de sortie SOAP et retourne les valeurs des variables
   IMAGE VERS BLOB([Images]Picture;getPicture_ResultPicture_x;$format_s)
   LIBERER ENREGISTREMENT([Images])
Fin de si

Si ($errorCode_l#0)
   C_TEXTE($errorText_t)
   $errorText_t:=getPictureErrorText ($errorCode_l)
   ENVOYER ERREUR SOAP($soapFaultType_l;$errorText_t)
Fin de si

VI. Tâche de client SOAP : récupérer une image

Les BLObs inclus dans les messages SOAP sont convertis en textes base64 pour le transfert. Dans 4ème Dimension retrouver l'image initiale s'effectue simplement, comme le montre l'exemple de méthode proxy de client SOAP ci-dessous :

   ` -----------------------------------------------------
C_TEXTE($1;$name_t)
C_TEXTE($2;$mimeType_t)
C_POINTEUR($3;$picture_p)
$name_t:=$1
$mimeType_t:=$2
$picture_p:=$3
FIXER PARAMETRE WEB SERVICE("inPictureName";$name_t)
FIXER PARAMETRE WEB SERVICE("inPictureMimeType";$mimeType_t)

APPELER WEB SERVICE(requestGetAccessURL ;"ReturningPicturesWithSoap#getPicture";
"getPicture";"http://www.4d.com/namespace/default";Web Service dynamique )

Si (OK=1)
   C_BLOB($pictureBlob_x)
   LIRE RESULTAT WEB SERVICE($pictureBlob_x;"outPictureBlob";*) ` Nettoyage mémoire
   BLOB VERS IMAGE($pictureBlob_x;$picture_p->)

   ` NOTE:
   ` BLOB VERS IMAGE peut seulement convertir les formats compatibles Quickime 4 et au-delà
   ` Par exemple, les images MacPaint ( code = 'PNTG', MIME type = image/x-macpaint)
   ` ne sont pas toujours converties correctement. Dans de tels cas, le BLOB est formé correctement,
   ` mais l'image résultante est vide. Si vous disposez d'autres code de traitement d'images ou d'un plug-in
   ` vous pouvez les appliquer au BLOB au lieu d'utiliser BLOB VERS IMAGE
Fin de si
   ` -----------------------------------------------------

VII. Retourner des informations additionnelles

La table [Images] de la base de données de démo comprend plusieurs attributs de l'image : hauteur, largeur, taille brute, auteurs et description. En utilisant SOAP, il est facile d'écrire des méthodes qui retourne l'un ou plusieurs de ces attributs à la fois. Ces fonctions permettent aux clients SOAP d'agir plus intelligemment et sélectivement. Par exemple, demander une vignette avant de charger des images lourdes, préconstruire les balises HTML d'images avec les largeurs et hauteurs ou charger une description de l'image, tout cela est possible simplement avec les Services Web.

La démo implémente quelques-unes de ces idées avec les commandes décrites ci-dessous :

   · getPictureDate retourne une description de l'image, de sa taille, sa largeur, sa hauteur et des auteurs.

   · getPictureListExtended étend la commande getPictureList pour inclure la description, la taille, la largeur, la hauteur et les auteurs de chaque image.

   · getPictureWithType retourne l'image avec son code de type MIME.

   · getThumbnail retourne une vignette de l'image générée dynamiquement.

Note de réalisation : les sources d'images

La démo charge les images depuis les enregistrements pour des raisons de simplicité du code. Dans un système de production, il est souvent beaucoup plus efficace de stocker les images lourdes en dehors de la base de données dans des documents et de ne stocker dans la base que les chemins d'accès à ces images. Des plug-ins comme 4D Chart et 4D Draw sont très utiles pour créer des images à partir de données dynamiques ou saisies.

En pratique les images peuvent provenir de n'importe laquelle des sources ci-dessous :

Sources	Commandes à utiliser
4D Chart et autres plug-ins:	ch Zone vers image
Documents sur disque :	Ouvrir document et RECEVOIR PAQUET ou DOCUMENT VERS BLOB ou LIRE FICHIER IMAGE ou CHARGER ET COMPRESSER IMAGE
Documents sur réseau :	TCP_Open et TCP_receiveBLOB
Ressources PICT :	LIRE RESSOURCE IMAGE
Images de Bibliothèque :	LIRE IMAGE DANS BIBLIOTHEQUE
Enregistrements :	Les images peuvent être stockées de manière natives dans des enregistrements.

VIII. Bases exemples

Téléchargez les bases exemples :

Base 4D 2004

Base 4D 2003 Windows

Base 4D 2003 MacOS

__________________________________________________
Copyright © 1985-2008 4D SA - Tous droits réservés
Tous les efforts ont été faits pour que le contenu de cette note technique présente le maximum de fiabilité possible.
Néanmoins, les différents éléments composant cette note technique, et le cas échéant, le code, sont fournis sans garantie d'aucune sorte. L'auteur et 4D S.A. déclinent donc toute responsabilité quant à l'utilisation qui pourrait être faite de ces éléments, tant à l'égard de leurs utilisateurs que des tiers.
Les informations contenues dans ce document peuvent faire l'objet de modifications sans préavis et ne sauraient en aucune manière engager 4D SA. La fourniture du logiciel décrit dans ce document est régie par un octroi de licence dont les termes sont précisés par ailleurs dans la licence électronique figurant sur le support du Logiciel et de la Documentation afférente. Le logiciel et sa documentation ne peuvent être utilisés, copiés ou reproduits sur quelque support que ce soit et de quelque manière que ce soit, que conformément aux termes de cette licence.
Aucune partie de ce document ne peut être reproduite ou recopiée de quelque manière que ce soit, électronique ou mécanique, y compris par photocopie, enregistrement, archivage ou tout autre procédé de stockage, de traitement et de récupération d'informations, pour d'autres buts que l'usage personnel de l'acheteur, et ce exclusivement aux conditions contractuelles, sans la permission explicite de 4D SA.
4D, 4D Calc, 4D Draw, 4D Write, 4D Insider, 4ème Dimension ®, 4D Server, 4D Compiler ainsi que les logos 4e Dimension, sont des marques enregistrées de 4D SA.
Windows,Windows NT,Win 32s et Microsoft sont des marques enregistrées de Microsoft Corporation.
Apple, Macintosh, Power Macintosh, LaserWriter, ImageWriter, QuickTime sont des marques enregistrées ou des noms commerciaux de Apple Computer,Inc.
Mac2Win Software Copyright © 1990-2002 est un produit de Altura Software,Inc.
4D Write contient des éléments de "MacLink Plus file translation", un produit de DataViz, Inc,55 Corporate drive,Trumbull,CT,USA.
XTND Copyright 1992-2002 © 4D SA. Tous droits réservés.
XTND Technology Copyright 1989-2002 © Claris Corporation.. Tous droits réservés ACROBAT © Copyright 1987-2002, Secret Commercial Adobe Systems Inc.Tous droits réservés. ACROBAT est une marque enregistrée d'Adobe Systems Inc.
Tous les autres noms de produits ou appellations sont des marques déposées ou des noms commerciaux appartenant à leurs propriétaires respectifs.
__________________________________________________

Ce document est issu de http://www.developpez.com et reste la propriété exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise à l'obtention préalable de l'autorisation de l'auteur.