From 185ffe47ebd92cf1cc40c9ad85411508be38c7c4 Mon Sep 17 00:00:00 2001 From: gumartinm Date: Sun, 11 Nov 2012 05:24:21 +0100 Subject: [PATCH] Final WSDL 2.0 description. --- capitulo5/capitulo5.tex | 71 ++++++++++++++++++++++++++++++++++++++++++++----- source/adslist.xsd | 25 +++++++++++++++++ source/binding.xml | 8 ++++++ source/interface.xml | 11 ++++++++ source/mobiads.wsdl | 46 ++++++++++++++++++++++++++++++++ source/service.xml | 9 +++++++ 6 files changed, 164 insertions(+), 6 deletions(-) create mode 100644 source/adslist.xsd create mode 100644 source/binding.xml create mode 100644 source/interface.xml create mode 100644 source/mobiads.wsdl create mode 100644 source/service.xml diff --git a/capitulo5/capitulo5.tex b/capitulo5/capitulo5.tex index 3918520..9b55d16 100644 --- a/capitulo5/capitulo5.tex +++ b/capitulo5/capitulo5.tex @@ -167,7 +167,7 @@ El término \emph{Web services} está típicamente asociado con operaciones o ac \subsection{REST} -\emph{REST} es un estilo de arquitectura que trata la Web como una aplicación centrada en recursos~\cite{C5:IBMREST}. De forma práctica, esto significa que cada URL en una aplicación RESTful representa un recurso. Las URLs son también fáciles de entender y recordar. Por ejemplo, una tienda de venta de libros puede definir la URL http://www.bookstore.com/books/ para una lista de libros que esa tienda vende y la URL http://www.bookstore.com/books/0321396/ para obtener detalles acerca de un libro determinado en función de su número ISBN. Esto es un claro contraste a las aplicaciones centradas en acciones, las cuales típicamente tienen largas y crípticas URLs describiendo acciones para realizar, tales como, http://www.bookstore.com/action/query?t=b\&id=111114532\&qp=0321396. Los parámetros de la query son usados para filtrar los resultados. +\emph{REST} es un estilo de arquitectura que trata la Web como una aplicación centrada en recursos~\cite{C5:IBMREST}. De forma práctica, esto significa que cada URL en una aplicación RESTful representa un recurso. Las URLs son también fáciles de entender y recordar. Por ejemplo, una tienda de venta de libros puede definir la URL \nolinkurl{http://www.bookstore.com/books/} para una lista de libros que esa tienda vende y la URL \nolinkurl{http://www.bookstore.com/books/0321396/} para obtener detalles acerca de un libro determinado en función de su número ISBN. Esto es un claro contraste a las aplicaciones centradas en acciones, las cuales típicamente tienen largas y crípticas URLs describiendo acciones para realizar, tales como, \nolinkurl{http://www.bookstore.com/action/query?t=b\&id=111114532\&qp=0321396}. Los parámetros de la query son usados para filtrar los resultados. El doctor Roy Fielding acuñó el término REST en su doctorado, donde él se refirió a el lenguaje HTTP y sus \emph{hyperlinks}\footnote{Sobre hyperlinks, ver: \url{http://en.wikipedia.org/wiki/Hyperlink}} como el motor de las aplicaciones basadas en estado. Esto significa que se espera que un recurso contenga \emph{hyperlinks}. Estos \emph{hyperlinks} son el método por el cual puede tomar lugar una transición que transfiere o cambia el estado de un recurso. Servicios Web REST hacen uso de \emph{hyperlinks}. @@ -177,7 +177,7 @@ Hay otro componente clave relacionado con las aplicaciones REST: las aplicacione \subsubsection{Retornando otros tipos de contenidos~\cite{C5:IBMREST}} -Los servicios Web generalmente devuelven datos como XML pero hay otros tipos de contenidos que son muy prácticos para los consumidores de servicios. Por ejemplo, en aplicaciones Ajax\footnote{\emph{Asynchronous JavaScript + XML}} suele ser preferible recibir datos del tipo JSON (\emph{JavaScript Object Notation}), por otro lado si el consumidor no es una máquina si no una persona que debe interpretar directamente los datos, probablemente quiera recibir estos datos como HTML, el cual puede ser fácilmente renderizado en el navegador Web. En el mundo HTTP, la selección del formato de los datos es conocida como \emph{content type negotiation}. En un \emph{content type negotiation}, el cliente especifica el tipo de contenido que prefiere y el que es aceptable, luego el servicio responde con el más apropiado tipo de contenido. Esto significa que un cliente puede pedir los datos desde un servicio Web como XML, y otro cliente puede pedir a ese mismo servicio Web los datos como JSON o algún otro tipo como puede ser YAML\footnote{Sobre YAML, ver: \url{http://www.yaml.org/}}. +Los servicios Web generalmente devuelven datos como XML pero hay otros tipos de contenidos que son muy prácticos para los consumidores de servicios. Por ejemplo, en aplicaciones Ajax\footnote{\emph{Asynchronous JavaScript + XML}} suele ser preferible recibir datos del tipo JSON (\emph{JavaScript Object Notation}), por otro lado si el consumidor no es una máquina si no una persona que debe interpretar directamente los datos, probablemente quiera recibir estos datos como HTML, el cual puede ser fácilmente renderizado en el navegador Web. En el mundo HTTP, la selección del formato de los datos es conocida como \emph{content type negotiation}. En un \emph{content type negotiation}, el cliente especifica el tipo de contenido que prefiere y el que es aceptable, luego el servicio responde con el tipo de contenido más apropiado. Esto significa que un cliente puede pedir los datos desde un servicio Web como XML, y otro cliente puede pedir a ese mismo servicio Web los datos como JSON o algún otro tipo como puede ser YAML\footnote{Sobre YAML, ver: \url{http://www.yaml.org/}}. Para dar a los clientes la capacidad para pedir un determinado tipo de contenido, se deben construir los servicios para que hagan uso de la cabecera HTTP \emph{Content-Type: text/html}. Una alternativa para aplicaciones que no entienden la cabecera \emph{Content-Type} es especificar un parámetro en la propia URL que represente el tipo de dato: xml, json, yaml, etc. @@ -219,9 +219,7 @@ WSDL 2.0 es un lenguaje XML. El elemento raíz de un documento WSDL 2.0 es el el Un esqueleto de un documento WSDL 2.0 es mostrado en el Listado~\ref{list:WSDL20skeleton}): -\definecolor{gray}{rgb}{0.9,0.9,0.9} -\definecolor{shadecolor}{named}{gray} -\lstset{language=XML, breaklines=false, backgroundcolor=\color{gray}, frame=single, captionpos=b, caption={Esqueleto de un documento WSDL 2.0}, label={list:WSDL20skeleton}} +\lstset{language=XML, basicstyle=\small, breaklines=true, frame=single, captionpos=b, caption={Esqueleto de un documento WSDL 2.0}, label={list:WSDL20skeleton}} \lstinputlisting{source/wsdl20skeleton.xml} La estructura de un documento WSDL 2.0 difiere de la WSDL 1.1. Las diferencias más importantes se detallan a continuación: @@ -230,7 +228,7 @@ La estructura de un documento WSDL 2.0 difiere de la WSDL 1.1. Las diferencias m \item El elemento raíz ha cambiado desde \emph{definitions} a \emph{description}. \item El elemento \emph{portType} ha sido reemplazado con el elemento \emph{interface} para reflejar mejor su uso. \item El elmento \emph{message} no existe como un elemento global. Las descripciones de los mensajes son ahora encapsuladas en el elemento \emph{interface}. - \item Un \emph{binding} se puede en WSDL 2.0 reutilizar. No necesita ahora ser asociado con un interfaz específico. La asociación puede ser realizada en la declaración del servicio. + \item En WSDL 2.0 un \emph{binding} se puede reutilizar. No necesita ahora ser asociado con un interfaz específico. La asociación puede ser realizada en la declaración del servicio. \end{itemize} El elemento \emph{types} contiene todas las definiciones de tipos que describen los mensajes del servicio Web. WSDL 2.0 puede ser usado con otros sistemas de tipado, pero prácticamente es únicamente utilizado con el esquema XML. @@ -240,3 +238,64 @@ El elemento \emph{interface} define las operaciones del servicio Web, incluyendo El elemento \emph{binding} define cómo un cliente puede comunicar con el servicio Web. En el caso de servicios Web REST, un binding especifica que los clientes pueden comunicarse con el servidor usando HTTP. El elemento \emph{service} asocia una dirección para el servicio Web con un interfaz y binding específicos. + +\subsection{Modelo WSDL 2.0 utilizado} + +\subsubsection{Definir el formato de mensajes para las operaciones} + +Como primer paso para desarrollar un servicio Web, se debe definir el formato de los mensajes XML de cada operación. Se necesita describir las estructuras específicas de los mensajes para que los clientes puedan saber qué mensaje enviar al servicio y qué mensaje esperar desde el servicio. En nuestro caso, el servicio Web\footnote{Por simplicidad se decidió un diseño con un solo servicio Web, si bien hubiera sido más adecuado crear dos servicios Web REST. El primer servicio retornaría una lista con URLs a anuncios concretos (por ejemplo en función de su ID) donde a su vez un segundo servicio Web REST que estuviera escuchando retornaría los datos de cada uno de esos anuncios.} tendrá un único mensaje de salida (\emph{output}). + +WSDL 2.0 soporta múltiples tipos de sistemas para la descripción del contenido de los mensajes, pero el esquema XML es el único que se usa. Para el caso particular de este proyecto, se debe crear el siguiente mensaje de salida: + +\begin{itemize} + \item \emph{adsList} representa el mensaje de salida. Contiene una secuencia de elementos ad. Cada elemento ad contiene los atributos: \emph{id}, \emph{text}, \emph{adname}, \emph{link} e \emph{image}. El \emph{id} es un identificador único del anuncio en el sistema, \emph{text} es un texto descriptivo con información sobre un anuncio, \emph{adname} es el nombre del anuncio, \emph{link} es una URL donde se puede encontrar más información sobre un anuncio y \emph{image} es una URL de donde se puede descargar la imagen asociada con un determinado anuncio. +\end{itemize} + +El esquema XML para el servicio se muestra en el Listado~\ref{list:XSDadsList}). + +\begin{figure}[H] +\lstset{language=XML, basicstyle=\small, breaklines=true, float=[P], floatplacement={P}, frame=single, captionpos=b, caption={Esquema XML para la lista de anuncios}, label={list:XSDadsList}} +\lstinputlisting{source/adslist.xsd} +\end{figure} + + +\subsubsection{Fichero WSDL servicio AdsList} + +Tras la definición del esquema, se puede crear el fichero WSDL que nos permite definir el servicio Web. En el Listado~\ref{list:WSDL20mobiads}) se muestra el fichero WSDL del servicio AdsList. + +\lstset{language=XML, basicstyle=\small, breaklines=true, float=[P], floatplacement={P}, frame=single, captionpos=b, caption={WSDL servicios AdsList}, label={list:WSDL20mobiads}} +\lstinputlisting{source/mobiads.wsdl} + +Los elementos más importantes del archivo WSDL mostrado en el Listado~\ref{list:WSDL20mobiads}) se explican a continuación. + +\subsubsection{Definición del servicio} + +La URL para obtener la lista de anuncios en función de las coordenadas GPS es \nolinkurl{http://users.mobiads.gumartinm.name/api/latitude/longitude/gpsads.json}. Para direccionar el servicio, se usa el elemento \emph{service} del WSDL, el cual requiere al menos un elemento hijo \emph{endpoint}. El atributo \emph{address} del elemento \emph{endpoint} es usado para la especificar la URL del servicio como se muestra en el Listado~\ref{list:WSDL20service}) El elemento \emph{endpoint} se usa también para asociar un binding con el servicio mediante el atributo \emph{binding}. El elemento \emph{servicio} también asocia un interfaz con el servicio mediante el atributo \emph{interface}. + +El documento WSDL 2.0 también requiere un espacio de nombres, por tanto también se define el \emph{targetNamespace} \nolinkurl{http://users.mobiads.gumartinm.name/adslist/wsdl}. + +\lstset{language=XML, basicstyle=\small, breaklines=true, float=[P], floatplacement={P}, frame=single, captionpos=b, caption={WSDL, servicio AdsList}, label={list:WSDL20service}} +\lstinputlisting{source/service.xml} + +\subsubsection{Definición del binding del servicio} + +La definición binding del servicio necesita especificar que el servicio comunica usando HTTP. Para hacer esto, se especifica el valor \nolinkurl{http://www.w3.org/ns/wsdl/http} para el atributo \emph{type} del elemento \emph{binding} del archivo WSDL. + +El binding puede de forma opcional referenciar un interfaz y en ese caso el binding puede también opcionalmente declarar un elemento \emph{operation} que es idéntico al elemento \emph{operation} definido en el interfaz. Hay cuatro verbos en la comunicación HTTP: GET, PUT, POST, DELETE. El servicio ads list es una petición de lectura, por tanto, comunica con HTTP GET. La declaración del binding HTTP del servicio puede ser vista en el Listado~\ref{list:WSDL20binding}) + +\lstset{language=XML, basicstyle=\small, breaklines=true, float=[P], floatplacement={P}, frame=single, captionpos=b, caption={WSDL, binding para servicio AdsList}, label={list:WSDL20binding}} +\lstinputlisting{source/binding.xml} + +\subsubsection{Definición de la operación del servicio} + +El elemento \emph{interface} y su hijo \emph{operation} son usados para definir las operaciones del servicio. En el caso de nuestro servicio, se define una única operación, \emph{getAdsbyGPS}. Después se especifican tres atributos en el elemento \emph{operation}: + +\begin{itemize} + \item \textbf{pattern:} Se usa para especificar el patrón de mensajes de intercambio (MEP por sus siglas en Inglés) para la operación. El MEP define la secuencia de mensajes en la operación y su dirección. En nuestro caso, se especifica el valor \nolinkurl{http://www.w3.org/ns/wsdl/in-out} para indicar que el servicio recibe un mensaje de entrada (en nuestro caso vacío) y envía un mensaje de salida (la lista con los anuncios). + \item \textbf{wsdlx:safe}: Proviene de las extensiones al espacio de nombres WSDL, en concreto este atributo declara que la operación es idempotente. Este tipo de operación no modifica el recurso y por tanto puede ser llamada tantas veces como se quiera proporcionando siempre los mismos resultados. +\end{itemize} + +El Listado~\ref{list:WSDL20interface}) muestra el código relacionado con el elemento \emph{interface} del archivo WSDL. + +\lstset{language=XML, basicstyle=\small, breaklines=true, float=[P], floatplacement={P}, frame=single, captionpos=b, caption={WSDL, interfaz para servicio AdsList}, label={list:WSDL20interface}} +\lstinputlisting{source/interface.xml} diff --git a/source/adslist.xsd b/source/adslist.xsd new file mode 100644 index 0000000..c1d172e --- /dev/null +++ b/source/adslist.xsd @@ -0,0 +1,25 @@ + + + + + + The response element for the GPSAds service. + + + + + + + + + + + + + + + + diff --git a/source/binding.xml b/source/binding.xml new file mode 100644 index 0000000..9fd541a --- /dev/null +++ b/source/binding.xml @@ -0,0 +1,8 @@ + + + The RESTfull HTTP binding for the GPS Ads service. + + + diff --git a/source/interface.xml b/source/interface.xml new file mode 100644 index 0000000..3d3804c --- /dev/null +++ b/source/interface.xml @@ -0,0 +1,11 @@ + + + + This operation returns a list of ads. + + + + + diff --git a/source/mobiads.wsdl b/source/mobiads.wsdl new file mode 100644 index 0000000..5ca9d76 --- /dev/null +++ b/source/mobiads.wsdl @@ -0,0 +1,46 @@ + + + + This is a WSDL 2.0 description of a service which is intended to retrive + ads depending on the calling GPS coordinates. + + + + + + + + This operation returns a list of ads. + + + + + + + + The RESTfull HTTP binding for the GPS Ads service. + + + + + + GPS Ads service: retrieve Ads by GPS coordinates. + + + + + diff --git a/source/service.xml b/source/service.xml new file mode 100644 index 0000000..96e2076 --- /dev/null +++ b/source/service.xml @@ -0,0 +1,9 @@ + + + GPS Ads service: retrieve Ads by GPS coordinates. + + + + -- 2.1.4