4D v14.3

SOAP DECLARATION

Accueil

 
4D v14.3
SOAP DECLARATION

SOAP DECLARATION 


 

SOAP DECLARATION ( variable ; type ; entrée_sortie {; alias} )  
Paramètre Type   Description
variable  Variable in Variable référençant un argument SOAP entrant ou sortant
type  Entier long in Type 4D vers lequel pointe l’argument
entrée_sortie  Entier long in 1 = Entrée SOAP, 2 = Sortie SOAP
alias  Chaîne in Nom publié pour cet argument lors des échanges SOAP

La commande SOAP DECLARATION 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 SOAP DECLARATION 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 SOAP DECLARATION 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 SOAP DECLARATION (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) :

Constante Type Valeur
Est un BLOB Entier long 30
Est un booléen Entier long 6
Est un entier Entier long 8
Est un entier long Entier long 9
Est un numérique Entier long 1
Est un tableau booléen Entier long 22
Est un tableau chaîne Entier long 21
Est un tableau date Entier long 17
Est un tableau entier Entier long 15
Est un tableau entierlong Entier long 16
Est un tableau numérique Entier long 14
Est un tableau texte Entier long 18
Est un texte Entier long 2
Est une date Entier long 4
Est une heure Entier long 11
Est une variable chaîne Entier long 24

Constante Type Valeur Commentaire
Est un XML Entier long 36
Est une référence DOM Entier long 37

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 “” :

Constante Type Valeur
SOAP entrée Entier long 1
SOAP sortie Entier long 2

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.

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 SOAP DECLARATION 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.

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
 SOAP DECLARATION($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

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
 SOAP DECLARATION(tab_codes;Est un tableau entierlong;SOAP entrée;"in_tab_codes")

Cet exemple permet de référencer deux valeurs de retour sans spécifier de nom d’argument :

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

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)
 SOAP DECLARATION($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.

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
 SOAP DECLARATION(ws_vx_xmlBlob;Est un BLOB;SOAP sortie;"contactListsX")
  //Le XML est converti en Base64 par 4D
 
 SOAP DECLARATION(ws_vt_xml;Est un texte;SOAP sortie;"contactListsText")
  //Le XML est converti en texte par 4D (< > deviennent des entités)
 
 SOAP DECLARATION(ws_vt_xml;Est un XML;SOAP sortie;"contactsXML")
  //Le XML est passé en texte XML
 
 SOAP DECLARATION(ws_vx_xmlBlob;Est un XML;SOAP sortie;"contactsBlob")
  //Le XML est passé en BLOB XML
 
 SOAP DECLARATION(ws_vt_refXML;Est une référence DOM;SOAP sortie;"contactByRef")
  //Le XML est passé en tant que référence

 
PROPRIÉTÉS 

Produit : 4D
Thème : Web Services (Serveur)
Numéro : 782
Nom intl. : SOAP DECLARATION

 
HISTORIQUE 

Modifié : 4D v11 SQL Release 2

 
VOIR AUSSI  

Fichier donnees verrouille
SOAP ENVOYER ERREUR
SOAP Lire information

 
UTILISATION DE L'ARTICLE

4D - Langage ( 4D v14 R2)
4D - Langage ( 4D v14 R3)
4D - Langage ( 4D v13.5)
4D - Langage ( 4D v14.3)
4D - Langage ( 4D v14 R4)

Hérité de : DECLARATION SOAP ( 4D v11 SQL Release 6)