DECLARATION SOAP

version 2004.3 (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, 4e Dimension 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.

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

• Il peut également être nécessaire de retourner des valeurs d'une taille supérieure à 32 Ko (limite des arguments de type Texte).

• 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. 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 4e Dimension, 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 prédéfinies suivantes, placées dans le thème "Types champs et variables" :

Note : Les constantes suivantes ne sont pas utilisables dans le cadre de méthodes SOAP : Est un champ alpha, Est un pointeur, Est un tableau 2D, Est un tableau image, Est un tableau pointeur, Est une image, Est une sous table, Est une variable indéfinie.

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)" :

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, 4e Dimension 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 :

   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.

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

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