WSDL INSPECTOR

Alcance
Lenguajes: Java, .NET, Visual Basic
Interfaces: Win, Web

Introduccin
El WSDL Inspector permite a partir del WSDL de un web service definir los tipos de
datos necesarios en GeneXus para poder consumir el web service en forma
transparente sin tener que preocuparse de los protocolos involucrados en el proceso y
la definicin del mismo.

Descripcin
El WSDL de un web service es un archivo que describe al mismo; brinda toda la
informacin necesaria para poder consumirlo.
GeneXus brinda una herramienta llamada WSDL Inspector que permite a partir del
WSDL de un web service definir en la base de conocimientos todo lo necesario para
poder consumir los mtodos del web service en forma transparente.
Para acceder al WSDL Inspector hay que ejecutar la opcin Tools/WSDL Inspector. La
misma esta solo accesible desde Design.

En Web Service URL se debe ingresar el camino hacia el WSDL. Puede ser
referenciado por medio del protocolo http (por ej.
http://api.google.com/GoogleSearch.wsdl ) o file (por ej.
file:C:\Servicios\AmazonWebServices.wsdl).
Una vez ingresado el camino del WSDL se debe presionar el botn Inspect, con lo
cual en caso de no existir ningn error se mostrar la informacin de los distintos
mtodos que brinda el web service, junto con los tipos de datos necesarios para
poder consumirlos.
Para poder importar la informacin necesaria dentro de la base de conocimientos
que permita consumir el web service se debe presionar el botn Add Reference.
En la imagen anterior se muestra la informacin de un web service simple, el cual
cuenta con un solo mtodo llamado BabelFish que recibe dos parmetros de entrada
de tipo Carcter y retorna otro parmetro de tipo Carcter.
El siguiente ejemplo muestra otro caso en el cual el web service cuenta con mas de
un mtodo y se necesita definir nuevos tipos de datos(ArrayOfNewsCategoty,
NewsCategoty, ArrayOfBusnessShortNews, BusnessShortNews):

Add Reference
Como se mencion anteriormente al presionar el botn Add Reference se genera
dentro de la base de conocimientos los tipos de datos necesarios para poder consumir
el web service en forma trasparente. O sea, se genera un tipo de datos que identifica
el web service y en caso de que el mismo necesite nuevos tipos de datos se genera
un tipo de datos estructurado para cada uno de ellos.
De esta forma se puede definir una variable a la cual asignarle el tipo de datos
definido para el web service y utilizando los mtodos de la misma poder invocar a los
distintos mtodos que el web service provee. Si para consumir el mtodo se
necesitan tipos de datos estructurados hay que crear variables con los tipos de datos
estructurados creados por el Inspector.

Invocacin de los mtodos de un web service

Mtodo sin tipos de datos estructurado
Volvamos entonces a la primera imagen para poder mostrar en un caso sencillo como
poder consumir un web service.
En este caso al presionar el botn Add Reference se agrega a los tipos de datos que
maneja
GeneXus,
el
tipo
net_xmethods_wwwsd_BabelFishService.BabelFishService.

(Notar que en el nombre asignado al tipo de datos esta precedido por el namespace
que identifica al web service, de esta forma GeneXus asegura que no van a existir
dos tipos de datos con el mismo nombre para distintos web services).
De esa forma se puede definir una variable a la cual asignarle ese tipo de datos;
llamaremos a la misma ws.
Luego podremos invocar utilizando la variable ws a cualquiera de los mtodos que
el web service provee (en este caso solo uno) de la siguiente forma:
&result = &ws.BabelFish(&traslationmode, &source)
Donde &result, &traslationmode y &source son variables de tipo character.
Eso es todo!, de esta forma se puede invocar a un web service en forma sencilla sin
tener que preocuparse de los protocolos involucrados en el proceso y la definicin del
mismo; solamente se tuvo que dar la ubicacin de su WSDL y GeneXus se encarg de
esconder la complejidad y definir un tipo de datos que represente al web service.
Mtodo con tipo de datos estructurado

Ahora vamos a consumir un webservice que utiliza dos tipos de datos estructurados.
Al importar el webservice en GeneXus se crea la siguiente:

Un nuevo tipo de datos correspondiente al webservice

(com_swanandmokashi.Horoscope)

Un tipo de dato estructurado llamado ZodiacSigns con la siguiente

definicin:

ZodiacSign
Character(9999)

DailyForecast Character(9999)
Un tipo de dato estructurado llamado ArrayOfZodiacSigns con la
siguiente definicin:

ArrayOfZodicSigns collection of ZodiacSigns

Para consumir el webservice se tiene el siguiente cdigo:

&array = &ws.GetHoroscope()
For &item in &array
&SodiacSign = &item.ZodiacSign
&ForeDailiy = &item.DailyForecast
load
endfor
Donde:
&ws es de tipo com_swanandmokashi.Horoscope
&array es de tipo ArrayOfZodicSigns
&item es de tipo ZodiacSigns
De esta forma se consume un webservice que usa tipos de datos estructurados.
NOTA: En el caso de tipos de datos booleanos, se debe utilizar el tipo de datos
numrico N(1). El valor 1 se corresponde con el True, y el 0 con el False.

Uso de locations en el consumo de web services

De la misma forma que con el llamado de los procedimientos SOAP, es posible
modificar diferentes parmetros de la invocacin de web services utilizando los
locations.
El nombre del location (indicado en el tag
<GXLocation name=> del archivo
location.xml, que debe utilizarse es el nombre que
GeneXus le asigna al tipo de datos creado por el Wsdl Inspector para el servicio,
sustituyendo el ultimo punto (.) por un underscore (_).
Por ejemplo, en el caso del webservice de Horscopo anterior, en GeneXus el tipo de
datos para el servicio muestra:
com_swanandmokashi.Horoscope
El location que se deber utilizar en este caso es:
com_swanandmokashi_Horoscope
El archivo location.xml debe de estar en el directorio corriente y solo se toma en
cuenta en tiempo de ejecucin.
Por ejemplo si se quiere redireccionar el web service a localhost:88 se tiene que tener
un location.xml de la siguiente forma:

<GXLocations>
<GXLocation name="com_swanandmokashi_Horoscope">
<Common>
<Host>localhost</Host>
<Port>88</Port>
</Common>
<HTTP>
<BaseURL>/HomePage/WebServices/</BaseURL>
</HTTP>
</GXLocation>
</GXLocations>

Ejemplo
En el GXOpen se encuentra una KB de ejemplo en la cual se consumen tres web
services; GXChart (servidor de grficas), Babelfish (traductor de textos) y GetJoke
(provee chistes agrupados por categoras).
El mismo puede ser obtenido en http://www.gxopen.com/main/hproject.aspx?176

Consideraciones

Para consolidar objetos que tengan variables de tipos de datos asociados a web
services, es necesario previamente agregar la referencia con el WSDL Inspector
en la KB destino. Otra opcin es copiar los archivos asociados al web service
desde el directorio <dir.KB>\kbdata\usrtypes de la KB origen a la destino (se
generan dos archivos con extensiones .ari y .xml por cada web service agregado,
que contienen las definiciones del mismo). Adems, luego de consolidarlo, es
necesario en el objeto borrar y volver a definir la/s variable/s de ese tipo, de lo
contrario se producir un error de especificacin:
spc0056, Internal error. Variable <variable> definition is incorrect or
not available. Data:<tipo>.

Cuando se compila un objeto main se compilan todos tipos de datos definidos en

lugar de compilar solo los usados por ese main.

No se puede utilizar el WSDL Inspector para consumir web services con los
generadores VFP y C/SQL

WEB SERVICES

Abstract
En los ltimos tiempos ha surgido con mucha fuerza el concepto de web
services, incluso afirmndose que el mismo cambiara la forma de programar
las aplicaciones orientadas a Internet hacia una arquitectura orientada a
servicios. Todo esto se ha visto potenciado luego del anuncio de Microsoft de su
nueva estrategia .NET que est basada en el modelo de web services.

Este documento describe que son los web services y como es la arquitectura
general del modelo, adicionalmente se provee una introduccin de los
estndares en los cuales se basa este modelo como ser SOAP, WSDL y UDDI.

Qu es un web service?
Un web service es una aplicacin que puede ser descripta, publicada,
localizada e invocada a travs de una red, generalmente Internet. Combinan
los mejores aspectos del desarrollo basado en componentes y la Web.
Al igual que los componentes, los web services son funcionalidades que se
encuentran dentro de una caja negra, que pueden ser reutilizados sin
preocuparse de cmo fueron implementados. A diferencia de la actual
tecnologa de componentes, no son accedidos por medio de protocolos
especficos del modelo de objetos como ser RMI, DCOM o IIOP; sino que son
accedidos utilizando protocolos web como ser HTTP y XML.
La interface de los web services esta definida en trminos de los mensajes que
el mismo acepta y retorna, por lo cual los consumidores de los web services
pueden ser implementados en cualquier plataforma y en cualquier lenguaje de
programacin, solo tiene que poder crear y consumir los mensajes definidos
por la interface de los web services.

El modelo de web services.

La arquitectura bsica del modelo de web services describe a un consumidor,
un proveedor y ocasionalmente un corredor (broker). Relacionados con estos
agentes estn las operaciones de publicar, encontrar y enlazar.
La idea bsica consiste en que un proveedor publica su servicios en un
corredor, luego un consumidor se conecta el corredor para encontrar los
servicios deseados y una vez que lo hace se realiza un lazo entre el consumidor
y el proveedor.

Cada entidad puede jugar alguno o todos los roles.

Por todo lo anterior hay ciertos requerimientos a la hora de desarrollar o

consumir un web services:

Una forma estndar de representar los datos.

XML es la opcin obvia para este requerimiento.

Un formato comn y extensible de mensajes.

SOAP es el elegido en este caso; SOAP es un protocolo liviano para el
intercambio de informacin. Ms adelante en este documento lo veremos con
ms detalle.

Un lenguaje comn y extensible para describir los servicios.

La opcin en este caso es WSDL. Es un lenguaje basado en XML desarrollado
en forma conjunta por IBM y Microsoft. Lo veremos con ms detalle mas
adelante en este documento.

Una forma de descubrir los servicios en Internet.

UDDI se utiliza en este caso; el mismo especifica un mecanismo para
publicar y localizar los servicios por parte de los proveedores y
consumidores respectivamente. Se ver con ms detalle mas adelante
en este documento.

Ventajas y retos.
Los web services apuntan a ser la piedra fundamental de la nueva generacin
de sistemas distribuidos. Estos son algunos puntos para fundamentar esta
afirmacin:

Interoperabilidad:
Cualquier web service puede interactuar con otro web service. Como los web
services pueden ser implementados en cualquier lenguaje, los desarrolladores
no necesitan cambiar sus ambientes de desarrollo para producir o consumir
web services.

Ubicuidad:
Los web services se comunican utilizando HTTP y XML. Por lo tanto
cualquier dispositivo que soporte estas tecnologas pueden implementar
o acceder web services. Muy pronto estarn presentes en telfonos,
autos e incluso mquinas expendedoras, las que avisarn a la central
cuando el stock sea menor al indicado.

Encapsular reduce la comlejidad

Todos los componentes en un modelo de web services son web service. Lo
importante es la interface que el servicio provee y no como esta
implementado, por lo cual la complejidad se reduce.

Fcil de utilizar:
El concepto detrs de los web services es fcil de entender, incluso existen
toolkits de vendedores como IBM o Microsoft que permiten a los
desarrolladores crear web services en forma rpida y fcil.

Soporte de la Industria:
Todos las empresas de software importantes soportan SOAP, e incluso estn
impulsando el desarrollo de web services. Por ejemplo la nueva plataforma de
Microsoft .NET esta basada en web services, haciendo muy simple el
desarrollo de los mismos que luego podran ser consumidos por un web
service desarrollado utilizando VisualAge de IBM y viceversa.

A la vez hay ciertos retos tcnicos que los web services tienen que sortear para poder
tener xito. Muchos de estos retos estn relacionados con el ambiente abierto en el
que tienen que sobrevivir. Estos son algunos de esos puntos:

Descubrimiento:
Como un web service se anuncia para ser descubierto por otro servicio? Qu
pasa si el servicio se cambio o se movi luego de ser anunciado?
WSDL y UDDI son dos nuevos estndares que manejan este punto.

Confiabilidad:
Algunos web services son ms confiables que otros. Cmo puede ser medida
esa confiabilidad y comunicada? Qu pasa cuando un web service esta offline en forma temporaria? Localizamos y utilizamos un servicio alternativo
brindado por otra empresa o esperamos a que el servicio este de nuevo online?

Seguridad:
Muchos web services son publicados para ser utilizados sin ninguna
restriccin, pero muchos otros van a necesitar autenticacin para que los
utilicen solo los usuarios autorizados. Cmo autentifica a los usuarios un web
service? Lo hace a nivel del mtodo que lo implementa o utiliza otro web
service para realizar la autenticacin?

Responsabilidad
En caso de que el web service no sea de acceso libre, Cmo puedo definir
cuantas veces un consumidor puede acceder al web service una vez

contratado? Cmo se cobra su uso? Cmo se indica que un servicio ya no

esta ms en lnea?

Tecnologas asociadas
El modelo de web services est basado en ciertas tecnologas emergente que
es el resultado del trabajo de varias compaas y organizaciones entre las
cuales se destacan IBM y Microsoft.
Estas tecnologas son SOAP, WSDL y UUDI.

SOAP (Simple Object Access Protocol)

SOAP es un protocolo para el intercambio de informacin en un ambiente
descentralizado y distribuido. Es el protocolo ms utilizado para realizar el
intercambio de informacin en el modelo de web services.
Esta basado en XML y potencialmente puede ser utilizado en combinacin con
una variedad de protocolos de comunicacin, siendo el ms utilizado HTTP. Por
lo tanto se utiliza HTTP para transportar la informacin, y XML para representar
la misma.
El protocolo completo se puede encontrar en http://www.w3.org/TR/soap

EL MODELO DE COMUNICACIN DE SOAP

El modelo de comunicacin de SOAP es muy similar al de HTTP. Un cliente hace
un requerimiento (request), el servidor que esta escuchando los requerimientos
lo atiene y responde (response) brindando la informacin solicitada o enviando
un mensaje de error en caso de que el requerimiento no haya sido vlido.

El mensaje SOAP consiste en un elemento envelope SOAP obligatorio, un

cabezal SOAP opcional y un cuerpo SOAP obligatorio como un documento XML.
El cabezal SOAP es utilizado para definir informacin acerca del requerimiento,
mientras que el cuerpo SOAP contiene el mtodo llamado y los parmetros con
los que se llama al mismo.

Todo esto es un modelo de mensajes request/response con una forma de

describir un conjunto de mtodos y pasarle a los mismos parmetros. Esto
parece la base del protocolo RPC y de hecho es el uso ms comn de SOAP. El
potencial es entregar esto sobre Internet utilizando HTTP para realizar
comunicaciones entre organizaciones permitiendo realizar comunicaciones
entre aplicaciones con diferente plataforma, sistema operativo y lenguaje de
programacin.

A continuacin se muestra un mensaje SOAP embebido en un request HTTP:

Este ejemplo invoca al servicio StockQuote llamando al mtodo

GetLastTradePrice con el smbolo DIS por parmetro.

Este es la respuesta al requerimiento anterior, el cual retorna el precio de la

accin solicitada:

Si usted quedo asustado por la aparente complejidad del protocolo SOAP

pensando lo engorroso que sera armar los mensajes de requerimiento y
parsear los mensajes de respuesta despreocpese; la mayora de los lenguajes
de programacin proveen o proveern soporte para realizar esto. La idea
fundamental consiste en utilizar algn objeto al cual se le brinda un WSDL y se
le indica que mtodo se quiere llamar y con que parmetros. Esto arma en
tiempo de ejecucin el mensaje SOAP, lo manda y parsea el resultado
adjudicndoselo a alguna variable en forma trasparente para el usuario como si
hubiera hecho un call comn.

WSDL: Web Services Description Language

WSDL es un lenguaje basado en XML que se utiliza para describir un Web
Services. Ha sido suministrado por la W3C por estandarizacin.
Un archivo con formato WSDL provee informacin de los distintos mtodos
(operaciones) que el Web Services brinda, muestra cmo accederlos y que
formatos deben de tener los mensajes que se envan y se reciben. Es como un
contrato entre el proveedor del servicio y el cliente, en el cual el proveedor se
compromete a brindar ciertos servicios solo si el cliente enva un requerimiento

con determinado formato. Es el documento principal a lo hora de documentar

un Web Services, pero puede no ser el nico. En la mayora de los casos es
conveniente que este acompaado por un documento escrito en lenguaje
natural que brinde informacin de que es lo que hace cada uno de los mtodos
brindados por el Web Services as como tambin ejemplos, por ejemplo, de los
mensajes SOAP que espera y responde el servicio.

En forma resumida podramos decir que un archivo WSDL describe lo siguiente:

Mensajes que el servicio espera y mensajes que el servicio responde.

Protocolos que el servicio soporta.

A donde mandar los mensajes.

FORMATO DE UN ARCHIVO WSDL:

A continuacin se muestra como es el formato bsico de un archivo WSDL. La
especificacin completa de este lenguaje se puede encontrar en
http://www.w3.org/TR/wsdl.html

Un archivo con formato WSDL bsicamente contiene los siguientes elementos:

Type: Describe los tipos no estndar usados por los mensajes (Message).

Message: Define los datos que contienen los mensajes pasados de un punto a
otro.

PortType: Define una coleccin de operaciones brindadas por el servicio. Cada

operacin tiene un mensaje de entrada y uno de salida que se corresponde con
algn Message antes definido.

Binding: Describe los protocolos que se utilizan para llevar a cabo la

comunicacin en un determinado PortType; actualmente los protocolos
soportados son SOAP, HTTP GET, HTTP POST y MIME, siendo SOAP el ms
utilizado.

Port: Define una direccin (URL) para un determinado Binding

Service: Define una coleccin de Ports.

El siguiente es un ejemplo de archivo WSDL:

El mismo define dos mensajes (Simple.foo y Simple.fooResponse), luego define
un mtodo llamado foo el cual recibe el mensaje Simple.foo y retorna el
mensaje Simple.fooResponse. A continuacin se define un binding para el
mtodo foo asocindolo con el protocolo SOAP. Por ltimo se da una URL fsica
que implementa lo antes descrito.

INTERFASE E IMPLEMENTACIN
La estructura bsica de archivo con formato WSDL podra ser dividido en dos
partes lgicas: la interfase del servicio, y la implementacin del mismo.

Esta divisin lgica divide los elementos de la siguiente forma:

Interface del servicio:
Type, Message, PortType, Binding.
Contiene una definicin abstracta y reusable del servicio que puede ser
instanciada y referenciada por distintos proveedores del mismo.

Implementacin del servicio:

Port, Service.
Contiene una implementacin de una determinada Interface del servicio.

A partir de esta divisin lgica se puede definir por medio de una Interfase del
servicio una estndar para realizar, por ejemplo, ordenes de compras que
puede ser reutilizada e implementada por todas las empresas, sin tener que
redefinir cada una de ellas la interfase.

Si al igual que con SOAP se siente preocupado por la complejidad de los

archivos WSDL de nuevo despreocpese; la mayora de los lenguajes de
programacin proveen o proveern herramientas para generar en forma
automtica el archivo WSDL a partir de un determinado mtodo o funcin.

UDDI (Universal Description, Discovery and Integration).

UDDI (www.uddi.org) es un proyecto inicialmente propuesto por Ariba,
Microsoft e IBM; es un estndar para registrar y descubrir web services. La idea
es que las distintas empresas registran su informacin acerca de los web
services que proveen para que puedan ser descubiertas y utilizadas por
potenciales usuarios.
La informacin es ingresada al registro de empresas UDDI, un servicio
lgicamente centralizado, y fsicamente distribuido a travs de mltiples nodos
los cuales replican su informacin en forma regular. Una vez que una empresa
se registra en un determinado nodo del registro de empresas UDDI la
informacin es replicada a los otros nodos y queda disponible para ser
descubierta por otras empresas.

EL ESQUEMA UDDI
El modelo de informacin base utilizado por los registros UDDI es definido en
un esquema XML. Este esquema define cuatro tipos bsicos de informacin,
cada uno de los cuales proveen la clase de informacin que un usuario necesita
saber para utilizar un web service de otra empresa.
Los cuatro tipos de informacin son:

Informacin del negocio.

Este tipo de informacin esta definido en el elemento businessEntity.
Contiene informacin de la empresa, como ser su nombre, los contactos, el
tipo de empresa, etc.

Informacin del servicio.

Dentro del elemento businnessEntity se encuentran los elementos
businessServices, estos elementos contienen informacin sobre web services
generalmente agrupados por procesos de negocio o categoras de servicios.

Informacin del enlace (binding).

Dentro de cada elemento businessServices se encuentran los
elementos bindingTemplate. Cada uno de ellos brinda una direccin
fisica para hacer contacto con los servicios descriptos anteriormente.

Informacin sobre las especificaciones del servicio.

Cada bindingTemplate tiene asociado un tModel, el cual brinda informacon
sobre las especificaciones del servicio, por ejemplo, como tienen que ser los
mensajes que el servicio espera y responde, etc.

Un tModel puede ser asociado con elementos bindingTemplate de

distintas empresas que brindan la misma especificain del servicio.
Utilizando entonces los tModels se pueden encontrar todas las
empresas que brindan tal servicio.

Por ms informacin sobre el esquema UDDI:

http://www.uddi.org/pubs/ProgrammersAPI_v2.pdf

API UDDI
El acceso al registro UDDI, ya sea para realizar bsquedas o para ingresar o modificar
un registro, se puede realizar a travs de una pgina web que implemente el acceso o
utilizando ciertas interfaces (web services) que provee la especificacin de UDDI.
Estas interfaces estn descriptas en una API, que puede ser dividida en dos partes
lgicas, la API de consultas y la API de publicacin.

Por ms informacin sobre la API UDDI:

http://www.uddi.org/pubs/ProgrammersAPI_v2.pdf

Un ejemplo
Las formas en que se puede realizar negocios utilizando web services es muy
variada. El consumidor podra pagar por utilizar los servicios brindados por un
proveedor, o el proveedor podra pagar para que aparezcan los servicios que l
ofrece en un determinado consumidor, o incluso existen casos en los cuales ni
el consumidor ni el proveedor pagan por consumir o proveer los servicios en
forma respectiva. Este es el caso que se presenta a continuacin.
El ejemplo es tomado de la vida real y es sobre la compaa area Southwest.
En su portal http://www.southwest.com/ , esta compaa area permite hacer
reservas de boletos, pero adems como valor agregado a los clientes permite
hacer reservas de hoteles y reservas de alquileres de autos. Los datos para
poder realizar estas reservas estn tomados de web services que brindan los
distintos hoteles y rentadoras de autos.
Este es un ejemplo de uso de web services en el cual ni el consumidor ni los
proveedores pagan; a ambos le sirve este intercambio ya que la compaa de
aviones le brinda un valor agregado a sus clientes, y los hoteles y rentadoras
de autos estn expuestos a ser contratos por potenciales clientes. Es ms,
estas empresas no publicaron sus servicios para que fueran exclusivamente
utilizados por la compaa area, sino que los mismos pueden ser descubiertos
y utilizados por cualquier empresa que los necesite.
Claramente se muestra en este ejemplo el gran poder de los web services, y la
ventaja que tendrn las empresas que los sepan utilizar en forma adecuada
con respecto a las otras. Imagnese en este caso si usted fuera a reservar
boletos de avin y pudiera elegir por una compaa que adems de reservar los
boletos le permitiera hacer la reserva de hotel, y otra que no; por cual hara la
reserva? Por otro lado imagine que usted es dueo de una rentadora de autos y
sabe que su competencia esta brindando sus servicios en un portal de una
compaa area y usted no, qu hara?.