nuSOAP: Creación de Estructuras y Arreglos

Crear Estructuras con nuSOAP

En esta ocasión veremos como crear nuestras propias estructuras de datos para nuSOAP. Cabe destacar que si el Web Service SIEMPRE se va a consumir desde PHP, una forma simple y rápida para evitar tener que crear una estructura o por que simplemente no tienes bien definido que cosas va devolver el Web Service es indicar que va a retornar un array, ya que en PHP un mismo array puede almacenar distintos tipos de dato. Pero esta solución no la recomiendo si existe la posibilidad de algún día consumir el Web Service desde lenguajes fuertemente tipados (las variables solo aceptan un solo tipo de dato) por una causa que explicaré en otro artículo más adelante.

Para entender mejor esto recurriremos a la documentación de nuSOAP que pueden encontrar aquí. Una vez que descarguen la documentación de nuSOAP deben descomprimirlo y abran el archivo index.html una vez abierto veremos algo como esto:

doc

En la barra de la izquierda, en la carpeta de clases busquemos la clase wsdl y den clic en ella para ver la documentación de la clase:

Documentación de la clase WSDL de nuSOAP

Una vez ahí, busquemos en la sección llamada Method Summary una función llamada addComplexType() (esta es la función que nos permitirá agregar estructuras propias a nuSOAP) y den clic en el nombre de la función:

Función addComplexType() de nuSOAP

Ahora den clic sobre el nombre de la función para ver la documentación de forma más precisa:

Documentación de la función addComplexType() de nuSOAP

Aquí podemos ver los parámetros que lleva esa función, su valor por defecto y si son obligatorios.

NOTA: Los parámetros que están entre corchetes [] son opcionales, también podemos ver que tienen un valor por defecto en caso de que no se especifiquen.

 

Parámetros de la Función addComplexType()

  • El nombre de la estructura, y es el único parámetro obligatorio.
  • El tipo estructura que será, por defecto es un tipo complejo  (complexType).
  • El tipo de PHP que se utilizará para manejar la estructura (un arreglo asociativo).
  • El compositor:
    • Sequence: Indica la secuencia exacta de los párametros
    • Choice: Indica que debe de aparecer al menos uno de los elementos de la lista
    • All: Indica los elementos que deben aparecer, pero sin especificar el orden.
  • El tipo de restricción para la estructura, dado que sera un array siempre se usa http://schemas.xmlsoap.org/soap/encoding/:arrayType.
  • Los elementos de la estructura (si fuera una clase serian sus atributos)
  • Los atributos de los elementos (atributos de esquema)
  • Después va el tipo de dato a utilizar en el web service.

Aunque rara vez es necesario utilizar valores diferentes a los por defecto, es bueno conocer la documentación de nuSOAP, ya que casi todos los tutoriales que hay en Internet no lo mencionan ni hacen referencia a ella, difícilmente encontrarán información al respecto.

Bien ahora comenzaremos a construir nuestra estructura en nuSOAP, antes cabe destacar que podemos crear estructuras para definir el/los parámetro(s) de entrada o salida las funciones del Web Service. Una ves aclarado esto, primero definamos un Web Service a construir.

Web Service de Prueba

Desarrollar un Web Service con nuSOAP que reciba el número de control de un alumno y devuelva los datos generales del alumno:

  • Nombre completo (string; Paterno Materno Nombres)
  • Edad (int)
  • Sexo (char; H – Hombre, M – Mujer)
  • Fecha de Nacimiento (date; dia/mes/año)

Ahora que tenemos definidos los atributos o campos que deberá tener la estructura DatosGralesAlumno veamos la información que tenemos:

  • name: DatosGralesalumno
  • typeClass: complexType
  • phpType: struct
  • compositor: all (puede ser sequence)
  • elements:
    • Nombre
    • Edad
    • Sexo
    • Fecha de Nacimiento

Con esta información ahora escribamos el código, que quedaría de la siguiente forma:

Como pueden ver, en restrictionBase no hemos escrito nada, esto es por que no lo vamos a utilizar, si observan en la documentación verán que una cadena vacía es el valor por defecto de este parámetro, es por eso que enviamos una cadena vacía. Tampoco hemos utilizado todos los parámetros de la función, como había mencionado, no siempre se utilizan todos.

¿Como utilizo la estructura en una función?

Vamos a crear una función en el Web Service que reciba un xsd:string de entrada con el número de control del alumno, y va a devolver una estructura DatosGralesAlumno, quedando de la siguiente manera:

Como pueden observar en la linea 4, especificamos que va a devolver un tns:DatosGralesAlumno (esto aplica también para los parámetros de entrada), pero… ¿que significa tns?, si nos dirigimos a este sitio podemos observar la siguiente tabla:

Talba de prefijos utilizados en documentos WSDL

Donde se nos explica que tns significa literalmente “este espacio de nombres”, es decir el de nuestro Web Service, de esta forma le decimos al Web Service que DatosGralesAlumno es una estructura definida dentro de él mismo.

Con esto hemos terminado de declarar nuestra estructura y utilizarla en nuestro Web Service. Nos vemos en la siguiente entrega donde veremos como crear un Web Service y probarlo/consumirlo desde Mozilla Firefox.

2 thoughts on “nuSOAP: Creación de Estructuras y Arreglos

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

18 ÷ 2 =