DECLARATION SOAP

version 11.2 (Modifiée)

DECLARATION SOAP (variable; type; entrée_sortie{; alias})

La commande DECLARATION SOAP permet de déclarer explicitement le type des paramètres utilisés dans une méthode 4D publiée comme Web Service.

Lorsqu'une méthode est publiée en tant que Web Service, les paramètres standard $0, $1... $n sont utilisés pour décrire les paramètres du Web Service auprès du monde extérieur (notamment dans le fichier WSDL). Le protocole SOAP exigeant que les paramètres soient explicitement nommés, 4D utilise par défaut les noms "FourD_arg0, FourD_arg1 ... FourD_argn".

Ce fonctionnement par défaut peut toutefois s'avérer problématique pour les raisons suivantes :

• Il n'est pas possible de déclarer $0 ou $1, $2, etc. en tant que tableau. Il est donc nécessaire d'utiliser des pointeurs, mais dans ce cas il reste à connaître le type des valeurs pour la génération du fichier WSDL.

• Il peut être utile ou nécessaire de personnaliser les noms des paramètres (entrants et sortants).

• Vous pouvez vouloir utiliser des paramètres tels que des structures XML et des références DOM.

• Il peut également être nécessaire de retourner des valeurs d'une taille supérieure à 32 Ko (limite des arguments de type Texte dans les bases de données en mode non Unicode).

• Enfin, ce fonctionnement rend impossible le retour de plus d'une valeur par appel (dans $0).

La commande DECLARATION SOAP permet de s'affranchir de ces limites. Vous pouvez exécuter cette commande pour chaque paramètre entrant et sortant et lui assigner un nom et un type.

Note : Même si la commande DECLARATION SOAP est utilisée, il est nécessaire de déclarer les variables et tableaux 4D dans la méthode Compiler_Web à l'aide les commandes du thème "Compilateur".

Passez dans variable la variable 4D à référencer dans l'appel du Web Service.

Attention, vous pouvez référencer uniquement des variables process ou les arguments des méthodes 4D ($0 à $n). Les variables locales et interprocess ne peuvent pas être utilisées.

Par défaut, seuls des arguments de type Texte pouvant être utilisés, les réponses du serveur SOAP sont en principe limitées à 32 Ko dans les bases de données en mode non Unicode. Il est toutefois possible de retourner des arguments SOAP d'une taille supérieure à 32 Ko, en utilisant des BLOBs. Pour cela, il suffit de déclarer les arguments en type BLOB avant d'appeler la commande DECLARATION SOAP (cf. exemple 4).

Note : Côté client, si vous souscrivez à ce type de Web Service avec 4D, l'assistant Web Services générera naturellement une variable de type Texte dans la méthode proxy. Pour pouvoir l'utiliser, il vous suffit de retyper cette variable de retour en BLOB dans la méthode proxy.

Passez dans type le type 4D correspondant. La plupart des types de variables et de tableaux 4D peuvent être employés. Vous pouvez utiliser les constantes ci-dessous, placées dans le thème "Types champs et variables", ainsi que, pour les types XML, deux constantes du thème "Web Services (Serveur)" :

Passez dans entrée_sortie une valeur indiquant si le paramètre traité est "entrant" (c'est-à-dire correspondant à une valeur reçue par la méthode) ou "sortant" (c'est-à-dire correspondant à une valeur retournée par la méthode). Vous pouvez utiliser les constantes prédéfinies suivantes, placées dans le thème "Web Services (Serveur)" :

Utilisation de types XML : Vous pouvez déclarer des variables de type "structure XML" et "référence DOM", aussi bien en entrée qu'en sortie, via les constantes Est un XML et Est une référence DOM. Lorsque des paramètres de ce type sont définis, aucun traitement ni encodage ne leur est appliqué, les données sont transmises telles quelles (cf. exemple 5).

• Paramètres sortants :

- Est un XML indique que le paramètre contient une structure XML,

- Est une référence DOM indique que le paramètre contient la référence DOM d'une structure XML. Dans ce cas, l'insertion de la structure XML dans le message SOAP équivaut à l'exécution de la commande DOM EXPORTER VERS VARIABLE.

Note : Dans le cas de références DOM utilisées en paramètres sortants, il est recommandé d'utiliser des références globales, créées par exemple au démarrage et closes à la fermeture de l'application. En effet, une référence DOM créée au sein du Web Service lui-même ne peut pas être refermée avec DOM FERMER XML sinon le Web Service ne retourne plus rien. Les appels multiples au Web Service impliquent alors la création d'autant de références DOM non refermées, ce qui peut provoquer une saturation de la mémoire.

• Paramètres entrants :

- Est un XML indique que le paramètre doit recevoir un argument XML envoyé par le client SOAP.

- Est une référence DOM indique que le paramètre doit recevoir la référence DOM d'une structure XML correspondant à l'argument XML envoyé par le client SOAP.

• Modification de la WSDL : Les structures XML seront déclarées par 4D du type "anyType" (indéterminé) dans la WSDL. Si vous souhaitez typer précisément une structure XML, vous devez sauvegarder le fichier WSDL et ajouter manuellement le schéma de données souhaité dans la section <types> de la WSDL.

Méthode COMPILER_WEB : Les arguments SOAP entrants référencés à l'aide de variables 4D (et non via les arguments des méthodes 4D) doivent être préalablement déclarés dans la méthode projet COMPILER_WEB. En effet, l'utilisation de variables process dans les méthodes Web Services nécessite leur déclaration avant l'appel de la méthode. La méthode projet COMPILER_WEB est appelée, si elle existe, à chaque requête SOAP acceptée. Par défaut, la méthode COMPILER_WEB n'existe pas. Vous devez la créer explicitement.

A noter que la méthode COMPILER_WEB est également appelée par le serveur Web de 4D lors de la réception de requêtes Web "classiques" de type POST (cf. section URLs et actions de formulaires).

Passez dans alias le nom de l'argument tel qu'il doit apparaître dans la WSDL et dans les échanges SOAP. Attention, ce nom doit être unique dans l'appel RPC (paramètres entrants et sortants confondus), sinon seule la dernière déclaration sera prise en compte par 4D.

Note : Les noms des arguments ne doivent pas débuter par un chiffre ni contenir d'espaces. En outre, pour éviter tout risque d'incompatibilité, il est recommandé de ne pas utiliser de caractères étendus (tels que des caractères accentués).

Si le paramètre alias est omis, 4D utilisera par défaut le nom de la variable ou FourD_argN pour les arguments des méthodes 4D ($0 à $n).

Note : La commande DECLARATION SOAP doit être incluse dans la méthode publiée comme Web Service. Il n'est pas possible de l'appeler d'une autre méthode.

(1) Cet exemple spécifie un nom de paramètre :

      ` Dans la méthode COMPILER_WEB
   C_ENTIER LONG($1)

      `Dans la méthode du service Web
   DECLARATION SOAP($1;Est un entier long;SOAP Entrée;"zipcode")
      ` Lors de la génération du fichier WSDL et des appels SOAP, le libellé 
      ` zipcode sera utilisé au lieu de fourD_arg1

(2) Cet exemple permet de récupérer un tableau de codes postaux sous forme d'entiers longs :

      `Dans la méthode COMPILER_WEB 
   TABLEAU ENTIER LONG(tab_codes;0)

      `Dans la méthode du service Web
   DECLARATION SOAP(tab_codes;Est un tableau entierlong;SOAP Entrée;"in_tab_codes")

(3) Cet exemple permet de référencer deux valeurs de retour sans spécifier de nom d'argument :

   DECLARATION SOAP(ret1;Est un entier long;SOAP Sortie)
   DECLARATION SOAP(ret2;Est un entier long;SOAP Sortie)

(4) Cet exemple permet au serveur SOAP de 4D de retourner un argument d'une taille supérieure à 32 Ko dans les bases de données en mode non Unicode :

   C_BLOB($0)
   DECLARATION SOAP($0; Est un texte ; SOAP sortie)

Notez le type Est un texte (et non Est un BLOB). Cette astuce permet un formatage correct de l'argument.

(5) Cet exemple illustre l'effet des différents types de déclarations :

   TOUT SELECTIONNER([Contact])

   `Construction d'une structure XML à partir de la sélection de Contacts et stockage du XML dans un BLOB
   C_BLOB(ws_vx_xmlBlob)
   getContactsXML (->ws_vx_xmlBlob) 
      `Récupération de la structure XML dans une variable texte
   C_TEXTE(ws_vt_xml)
   ws_vt_xml:=BLOB vers texte(ws_vx_xmlBlob;UTF8 Texte sans longueur) 
      `Récupération d'une référence DOM vers la structure XML
   C_TEXTE(ws_vt_refXML)
   ws_vt_refXML:=DOM Analyser variable XML(ws_vt_xml)

      `Test des différentes déclarations
   DECLARATION SOAP(ws_vx_xmlBlob;Est un BLOB ;SOAP Sortie ;"contactListsX") 
      `Le XML est converti en Base64 par 4D
 
   DECLARATION SOAP(ws_vt_xml;Est un Texte;SOAP Sortie;"contactListsText") 
      `Le XML est converti en texte par 4D (< > deviennent des entités)
 
   DECLARATION SOAP(ws_vt_xml;Est un XML;SOAP Sortie;"contactsXML") 
      `Le XML est passé en texte XML 

   DECLARATION SOAP(ws_vx_xmlBlob;Est un XML;SOAP Sortie;"contactsBlob") 
      `Le XML est passé en BLOB XML 

   DECLARATION SOAP(ws_vt_refXML;Est une référence DOM;SOAP Sortie;"contactByRef") 
      `Le XML est passé en tant que référence

ENVOYER ERREUR SOAP, Fichier donnees verrouille, Lire informations SOAP.

Thèmes Types champs et variables et Web Services (Serveur).