SOAP DECLARATION

versión 11.2 (Modificado)

SOAP DECLARATION (variable; tipo; entrada_salida{; alias})

El comando SOAP DECLARATION permite declarar explícitamente el tipo de los parámetros utilizados en un método 4D publicado como servicio Web.

Cuando se publica un método como servicio Web, los parámetros estándar $0, $1... $n se utilizan para describir los parámetros del servicio Web al mundo exterior (más particularmente en el archivo WSDL). El protocolo SOAP necesita que los parámetros sean nombrados explícitamente; 4D utiliza por defecto los nombres "FourD_arg0, FourD_arg1 ... FourD_argn".

Este funcionamiento por defecto puede ser problemático por las siguientes razones:

• No es posible declarar $0 o $1, $2, etc. como un array. Por lo tanto, es necesario utilizar punteros; sin embargo, en este caso, es necesario conocer el tipo de los valores para la generación del archivo WSDL.

• Luego, puede ser útil o necesario personalizar los nombres de los parámetros (entrantes y salientes).

• Si lo desea, puede utilizar parámetros como las estructuras XML y referencias DOM.

• Igualmente, es necesario devolver los valores de un tamaño superior a 32 KB (limite de los argumentos de tipo Texto).

• Por último, este funcionamiento hace imposible devolver más de un valor por llamada RPC (en $0).

El comando SOAP DECLARATION le permite liberar estos límites. Puede ejecutar este comando para cada parámetro entrante y saliente y asignarle un nombre y un tipo.

Nota: Incluso si se utiliza el comando SOAP DECLARATION, siempre es necesario declarar las variables y los arrays 4D ven el método Compiler_Web utilizando los comandos del tema "Compilador".

En variable, pase la variable 4D a referenciar cuando llame al servicio Web.

Advertencia: Puede referenciar únicamente las variables proceso o los argumentos de los métodos 4D ($0 a $n). Las variables locales e interproceso no pueden utilizarse.

Por defecto, como sólo pueden utilizarse los argumento de tipo texto, las respuestas del servidor SOAP están limitadas a l32 KB. Sin embargo, es posible devolver argumentos SOAP con un tamaño mayor a 32 KB, utilizando BLOBs. Para exceder este límite, simplemente necesita declarar los argumentos como BLOBs antes de llamar al comando SOAP DECLARATION (ver ejemplo 4).

Nota: Del lado del cliente, si suscribe este tipo de servicio Web con 4D, el asistente de servicios Web generará naturalmente una variable de tipo Texto en el método proxy. Para poder utilizarla, sólo necesita digitar nuevamente esta variable como un BLOB en el método proxy.

En tipo, pase el tipo 4D correspondiente. Pueden ser utilizados la mayoría de los tipos de variables y arrays 4D. Puede utilizar las siguientes constantes predefinidas, ubicadas en el tema "Field and Variable Types":

En entrada_salida, pase un valor indicando si el parámetro procesado es "entrante" (es decir corresponde a un valor recibido por el método) o "saliente" (por ejemplo corresponde a un valor devuelto por el método). Puede utilizar las siguientes constantes predefinidas, ubicadas en el tema "Web Services (Servidor)":

Utilización de tipos XML: puede declarar las variables de tipo "estructura XML" y "DOM reference", de entrada y salida, vía las constantes Is XML y Is DOM reference. Cuando los parámetros de este tipo son definidos, no se aplica ningún proceso ni codificación y los datos se trasmiten "tal cual" (ver ejemplo 5).

• Parámetros de salida:

- Is XML indica que el parámetro contiene una estructura XML,

- Is DOM reference indica que el parámetro contiene la referencia DOM de una estructura XML. En este caso, la inserción de la estructura XML en el mensaje SOAP es equivalente a ejecutar el comando DOM EXPORT TO VAR.

Nota: en el caso de las referencias DOM utilizadas como parámetros de salida, se recomienda utilizar las referencias globales, creadas, por ejemplo, al inicio o al cierre de la aplicación. De hecho, una referencia DOM creada dentro del Web Service mismo no puede cerrarse con DOM CLOSE XML, de lo contrario el Web Service no devuelve nada. Las llamadas múltiples al Web Service implican por lo tanto la creación de múltiples referencias DOM no cerradas, las cuales pueden provocar una saturación de la memoria.

- Is XML indica que el parámetro debe recibir un argumento XML enviado por el cliente SOAP.

- Is DOM reference indica que el parámetro debe recibir la referencia DOM de una estructura XML correspondiente al argumento XML enviado por el cliente SOAP.

• Modificación del WSDL: las estructuras XML serán declaradas por 4D como "anyType" (tipo indeterminado) en el WSDL. Si quiere dar un tipo preciso a una estructura XML, debe guardar el archivo WSDL y añadir manualmente el esquema de datos que quiere en la sección <types> del WSDL.

Método COMPILER_WEB: los argumentos SOAP entrantes referenciados con la ayuda de variables 4D (y no por los argumentos de métodos 4D) deben ser declarados primero en el método de proyecto COMPILER_WEB. De hecho, el uso de variables de proceso en los métodos Web Services necesitan ser declaradas antes de la llamada al método. Se llama el método de proyecto COMPILER_WEB, si existe, para cada petición SOAP aceptada. Por defecto, el método COMPILER_WEB no existe. Usted debe crearlo específicamente.

Note que el método COMPILER_WEB también es llamado por el servidor Web de 4D durante la recepción de peticiones Web "convencionales" de tipo POST (ver la sección URLs y acciones de formularios).

En alias, pase el nombre del argumento que debe aparecer en WSDL y en los intercambios SOAP.

Advertencia: Este nombre debe ser único en la llamada RPC (parámetros entrantes y salientes), de lo contrario, sólo la última declaración será tenida en cuenta por 4D.

Nota: Los nombres de los argumentos no deben comenzar por un número ni contener espacios. Además, para evitar riesgos de incompatibilidad, se recomienda no utilizar caracteres extendidos (tales como caracteres con acentos).

Si se omite el parámetro alias, 4D utilizará, por defecto, el nombre de la variable o FourD_argN para los argumentos de los métodos 4D ($0 a $n).

Nota: El comando SOAP DECLARATION debe estar incluido en el método publicado como servicio Web. No es posible llamarlo desde otro método.

1. Este ejemplo especifica un nombre de parámetro:

      ` En el método COMPILER_WEB 
   C_LONGINT($1)

      ` En el método del servicio Web 
      ` Durante la generación del archivo WSDL y las llamadas SOAP, la palabra 
      ` zipcode se utilizará en lugar de fourD_arg1
   SOAP DECLARATION($1;Is LongInt;SOAP Input;"zipcode")

2. Este ejemplo se utiliza para recuperar un array de códigos postales en forma de enteros largos:

   `En el método COMPILER_WEB 
   ARRAY LONGINT(codes;0)

   `En el método del servicio Web 
   SOAP DECLARATION(codes;LongInt array;SOAP Input;"in_codes")

3. Este ejemplo se utiliza para referenciar dos valores devueltos sin especificar un nombre de argumento:

   SOAP DECLARATION(ret1;Is LongInt;SOAP Output)
   SOAP DECLARATION(ret2;Is LongInt;SOAP Output)

4. Este ejemplo permite al servidor 4D SOAP devolver un argumento de un tamaño mayor a 32 KB:

   C_BLOB($0)
   SOAP DECLARATION($0; Is Text; SOAP Output)

Note el tipo Is Text (y no Is BLOB). Esto permite que el argumento sea procesado correctamente.

5. This Ejemplo illustrates the results of different types of declarations:

   ALL RECORDS([Contactos])

      `Construcción de una estructura XML de la selección de contactos y almacenar el XML en un BLOB
   C_BLOB(ws_vx_xmlBlob)
   obtenerContactosXML (->ws_vx_xmlBlob) 
      `Recuperar la estructura XML en una variable de tipo texto
   C_TEXT(ws_vt_xml)
   ws_vt_xml:=BLOB to text(ws_vx_xmlBlob;UTF8 text without length) 
      `Recuperar una referencia DOM a la estructura XML
   C_TEXT(ws_vt_xmlRef)
   ws_vt_xmlRef:=DOM Parse XML variable (ws_vt_xml)

      `Prueba las diferentes declaraciones
   SOAP DECLARATION(ws_vx_xmlBlob;Is BLOB ;SOAP Output ;"contactListsX") 
      `El XML se convierte en Base64 por 4D
 
   SOAP DECLARATION(ws_vt_xml;Is Text;SOAP Output;"contactListsText") 
      `El XML se convierte en texto por 4D (< > become entities)
 
   SOAP DECLARATION(ws_vt_xml;Is XML;SOAP Output;"xmlContacts") 
      `El XML se pasa a texto XML 

   SOAP DECLARATION(ws_vx_xmlBlob;Is XML;SOAP Output;"blobContacts") 
      `El XML se pasa a un blob XML

   SOAP DECLARATION(ws_vt_xmlRef;Is DOM reference;SOAP Output;"contactByRef") 
      `El XML se pasa como una referencia

Get SOAP info, Is data file locked, SEND SOAP FAULT.

Temas Tipos de campos y variables y Servicios Web (Servidor).