Biblioteca Técnica: SOAP Creando web services con el estándar JAX-WS 2.2 y Dinámica

Transcripción

1 Biblioteca Técnica: SOAP Creando web services con el estándar JAX-WS 2.2 y Dinámica Última actualización: Requiere framework v2.1.6 en adelante Contenido Sumario...2 Para aprender sobre SOAP y Web Services (teoría)...2 Para aprender sobre JAX-WS (práctica)...2 Requerimientos...3 Descargas...3 Agradecimientos...3 Modelo general...4 Diagrama de clases...4 Implementación e instalación...5 Creación del cliente Java Cliente PHP Mantener sesión desde el lado cliente Hacer un cliente configurable Leer el WSDL de una ubicación local Medir la velocidad de ejecución de un servicio Un cliente Java directo Entonando un cliente JAX-WS con Dinámica Biblioteca técnica Página 1 de 16

2 Sumario Este documento explica como crear paso a paso un web service, basándose en el API estándar JAX-WS v2.2, que permite fácilmente crear servicios SOAP con Java 6, y también enseña como publicarlos con Tomcat 6, dentro de una aplicación basada en el framework Dinámica. La implementación del servicio se apoya en facilidades provistas por el framework. También se muestran dos clientes de ejemplo para invocar este servicio, uno escrito en Java 6, y el otro en PHP, este último demuestra la interoperabilidad de un web service basado en JAX-WS v2.2. Esta es una solución muy fácil de implementar, eficiente y basada en código abierto. Recomendamos usar JAX-WS en vez de Axis u otras soluciones Java/SOAP, por ser un estándar básico de la plataforma J2SE, integrado con Java a partir de la versión 6. Para aprender sobre SOAP y Web Services (teoría) Si desconoce los fundamentos del estándar SOAP, se sugiere revisar estas referencias: A Gentle Introduction to SOAP A Busy Developer's Guide to SOAP New to Web services (by IBM developerworks) Para aprender sobre JAX-WS (práctica) - Introducing JAX-WS 2.0 With the Java SE 6 Platform, Part Introducing JAX-WS 2.0 With the Java SE 6 Platform, Part Implementing High Performance Web Services Using JAX-WS Implementación de referencia de JAX-WS Biblioteca técnica Página 2 de 16

3 Requerimientos En necesario que cuente con un ambiente de desarrollo del framework Dinámica (Tomcat6, Java6 y Eclipse 3.5), que se instala de acuerdo a estas instrucciones: Se asume que tiene experiencia básica con Dinámica, Tomcat, Eclipse y Java. Descargas La distribución light del último Tomcat 6 de producción que se usa con Dinámica, y viene lista para publicar web services con JAX-WS 2.2: La distribución light de Eclipse 3.5 para Dinámica y Tomcat 6: Java 6: Descargue el JDK 1.6 Update 18 o superior. Con este conjunto de software tiene lo último en plataforma de servicios web con Java, tanto en productividad como en rendimiento. Agradecimientos A Gustavo Dottori en Argentina por su colaboración al informarnos de las nuevas capacidades de publicación con JAX-WS v2.2 y por su aporte para el cliente PHP, y también a nuestros clientes en Venezuela que contrataron proyectos con web services y nos dieron la oportunidad de elaborar estos materiales. Biblioteca técnica Página 3 de 16

4 Modelo general Para ejemplificar la creación e implantación de un web service, crearemos un servicio que retorna el nombre de un cliente dado su código (usando la BD de demo de Dinámica), probaremos la publicación del servicio y construiremos dos clientes, uno en Java 6 y otro en PHP, usando APIs estándar de ambos lenguajes para la invocación de web services. Diagrama de clases Solo se escriben dos clases, Customer y CustomerImpl, la primera es una suerte de interfaz (no en el sentido estricto de Java), solo declara los servicios que exportamos como web services, usando anotaciones, una característica nueva del lenguaje (desde Java 5) y que hace particularmente fácil crear web services a partir de cualquier clase Java. Biblioteca técnica Página 4 de 16

5 Implementación e instalación Asumimos que tenemos un proyecto web basado en Dinámica, cargado en Eclipse, una aplicación vacía servirá, con su conexión a base de datos debidamente configurada. Se sugiere detener el servicio Tomcat. 1) Creamos un paquete service, dentro colocaremos nuestras dos clases y una plantilla SQL. La clase Customer es muy sencilla, solo define el servicio a exportar y se limita a invocar a una clase secundaria que implementa la lógica de negocios, y hace la interacción con la base de datos. package service; import public class Customer { public String findbyid(string customerid) throws Exception { CustomerImpl obj = new CustomerImpl(); String companyname = obj.findcustomer(customerid); return companyname; Lo importante es la anotación (@WebService) que define que los métodos públicos de esta clase deben ser vistos como Web Services, además del import correspondiente al API de servicios. Eso es todo. En este caso retornamos un tipo simple, un String, pero podría ser un tipo complejo, una clase Java tipo Bean, con métodos setxx/getxx, y a su vez compuesta por otros tipos complejos. Tenga en cuenta sin embargo que para que la interoperabilidad con otros lenguajes se dé, es prudente mantener la interfaz del servicio sencilla, fácil de representar en PHP o Visual Basic, Biblioteca técnica Página 5 de 16

6 además de Java. Dependerá de sus necesidades. Si los clientes del servicio serán escritos en Java 6, no tiene porque limitarse. La clase CustomerImpl: package service; import dinamica.*; public class CustomerImpl extends GenericTransaction { public String findcustomer(string id) throws Exception { //evitar ataques de inyeccion de sql String newid = StringUtil.replace(id, "'", "''"); try { //generar sql String sql = StringUtil.replace( getlocalresource("get-customer.sql"), "${id", newid ); //ejecutar I/O a BD Recordset rs = dbget("jdbc/dinamica", sql); //si no existe retorna un error if (rs.next()) return rs.getstring("companyname"); else throw new Exception("Customer not found:" + id); catch (Throwable e) { throw new Exception(e); Y la plantilla SQL: select * from demo.customers where customerid = '${id' Esta clase se limita a hacer una consulta a la BD, luego de ensamblar un query SQL usando el parámetro provisto. Nótese que los API de Dinámica hacen esta tarea muy sencilla en el caso de lecturas. Genera un Recordset, si vino vacío dispara un error, sino retorna el valor solicitado. Biblioteca técnica Página 6 de 16

7 2) Archivos de configuración Es necesario crear un archivo sun-jaxws.xml en el directorio /WEB-INF de la aplicación: <?xml version="1.0" encoding="utf-8"?> <endpoints xmlns=' version='2.0'> <endpoint name='customer' implementation='service.customer' url-pattern='/service/customer'/> </endpoints> Tendrá un endpoint por cada clase que exporta servicios. Nótese que la ruta para invocarlos comienza por /service/. Esto depende de como se configure el servlet de SOAP en web.xml. En el archivo /WEB-INF/web.xml hay que añadir en el sitio correcto (respetando el orden de los elementos) lo siguiente: <!--jax-ws listener--> <listener> <listener-class> com.sun.xml.ws.transport.http.servlet.wsservletcontextlistener </listener-class> </listener> <!--jax-ws servlet--> <servlet> <servlet-name>soapserver</servlet-name> <servlet-class> com.sun.xml.ws.transport.http.servlet.wsservlet </servlet-class> <load-on-startup>1</load-on-startup> </servlet> Y en la sección de los mappings de servlets <!--jax-ws service mapping--> <servlet-mapping> <servlet-name>soapserver</servlet-name> <url-pattern>/service/*</url-pattern> </servlet-mapping> Biblioteca técnica Página 7 de 16

8 El archivo web.xml solo necesitará tocarlo una vez, pero el archivo sun-jaxws.xml se debe actualizar si publica otro EndPoint. 3) Arrancar Tomcat y probar la publicación del servicio Invocar el WSDL del servicio usando el browser: Debería ver una respuesta en XML que describe la metadata del servicio, este URL es utilizado por los clientes para poder invocar al servicio. Biblioteca técnica Página 8 de 16

9 Ya estamos listos para crear un cliente Java 6 que se conecte a nuestro servicio usando el protocolo SOAP. Creación del cliente Java 6 1) Crear un proyecto Java normal con Eclipse 2) En el directorio de los fuentes del proyecto (/src), crear un archivo.bat con este contenido: set url= wsimport.exe -p services.customer -d./ -s./ -verbose NOTA: El directorio /bin de Java debería estar en el path de sistema para que el comando wsimport sea encontrado, sino ponga la ruta completa al comando. Si su aplicación no se llama "demo" ajuste el nombre en el URL. Ejecute este archivo, refresque el proyecto, verá que fue creado el paquete services.customer, que contiene varias clases, en general no necesitamos tocar estas clases para nada, excepto quizá si cambia la dirección URL del WSDL de nuestro servicio, que está definida en la clase CustomerService.java dentro de este paquete. 3) Crear una clase con método main() para poder invocar y probar el servicio: import services.customer.*; public class TestService { public static void main(string[] args) { //obtener referencia a objeto remoto Customer service = new CustomerService().getCustomerPort(); try { //invocar servicio System.out.println(service.findByID("BERGS")); catch (Throwable e) { e.printstacktrace(); Es un cliente muy simple, necesita importar el paquete de clases utilitarias que se generó con el programa wsimport.exe, esto crea la sensación de que estamos usando un objeto local, cuando Biblioteca técnica Página 9 de 16

10 en realidad todo ocurre vía protocolo SOAP. Nótese que usamos Throwable para interceptar el posible error que el servicio declara que puede arrojar. Si corre el servicio con el ID BERGS recibe la respuesta: Berglunds snabbköp. Pero si usa un ID que no existe, entonces se genera una excepción: services.customer.exception_exception: java.lang.exception: Customer not found:bergsxx at sun.reflect.nativeconstructoraccessorimpl.newinstance0(native Method) at sun.reflect.nativeconstructoraccessorimpl.newinstance(unknown Source) at sun.reflect.delegatingconstructoraccessorimpl.newinstance(unknown Source) at java.lang.reflect.constructor.newinstance(unknown Source) Cliente PHP Programas PHP pueden interactuar con nuestro servicio, de manera simple y rápida. Para este ejemplo usamos PHP v5.2.3 con la extensión de SOAP instalada. El código cliente: <?php $client = new SoapClient( ' array( 'trace' => 1, 'soap_version' => SOAP_1_1, 'style' => SOAP_DOCUMENT, 'encoding' => SOAP_LITERAL ) ); try { $wrapper->arg0 = new SoapVar( 'BERGS', XSD_STRING ); $response = $client-> soapcall( 'findbyid', array( $wrapper ) ); if( $response ) if( $response->return ) print( $response->return ); catch(exception $e) { echo 'Message: '.$e->getmessage(); Biblioteca técnica Página 10 de 16

11 ?> Con PHP5 incluso podemos capturar una posible excepción y recibir el mensaje de error generado por el servicio en Java, tal como lo hace el cliente Java. Mantener sesión desde el lado cliente A veces los web services requieren de sesión, es decir, entre una llamada y otra debe mantenerse la sesión con el cliente (una comunicación stateful), cosa que no es muy común con los web services, pero puede llegar a ser necesario cuando invoca una serie de servicios en secuencia, y la primera invocación es una especie de Login, por ejemplo. Con JAX-WS esto es fácil de implementar, una vez que obtiene el objeto para invocar los servicios, debe poner un valor en una propiedad del objeto que por debajo hace la solicitud http del protocolo SOAP. En este ejemplo AdminService es la clase del objeto remoto, en la línea resaltada en amarillo se activa el uso de sesión. //crear el objeto remoto AdminService obj = new AdminService_Service().getAdminService(); //activar uso de sesion con el servidor ((BindingProvider)obj).getRequestContext().put(BindingProvider.SESSION_MAINTAIN_PROPERTY, true); Hacer un cliente configurable Por defecto, cuando generamos un cliente usando wsimport, se crea una clase XxxxService, que permite obtener una referencia al objeto que nos permite hacer la llamada SOAP como si fuera una llamada local. Siguiendo nuestro caso de ejemplo, esta clase seria así: package services.customer; import java.net.malformedurlexception; import java.net.url; import javax.xml.namespace.qname; import javax.xml.ws.service; import javax.xml.ws.webendpoint; import javax.xml.ws.webserviceclient; /** Biblioteca técnica Página 11 de 16

12 * This class was generated by the JAXWS SI. * JAX-WS RI 2.0_02-b08-fcs * Generated source version: 2.0 * = "CustomerService", targetnamespace = " wsdllocation = " public class CustomerService extends Service { private final static URL CUSTOMERSERVICE_WSDL_LOCATION; static { URL url = null; try { url = new URL(" catch (MalformedURLException e) { e.printstacktrace(); CUSTOMERSERVICE_WSDL_LOCATION = url; public CustomerService(URL wsdllocation, QName servicename) { super(wsdllocation, servicename); public CustomerService() { super(customerservice_wsdl_location, new QName(" "CustomerService")); /** * * returns Customer = "CustomerPort") public Customer getcustomerport() { return (Customer)super.getPort(new QName(" "CustomerPort"), Customer.class); Como puede ver el URL del WSDL del servicio queda "cableado" en esta clase. A veces generamos el cliente contra un server de desarrollo, luego tenemos que apuntar a uno de producción, y estar recompilando la clase para cambiar el valor del URL que apunta al WSDL no debería ser la solución, es mejor parametrizarla o hacerla configurable, añadiendo un constructor que reciba un objeto URL: Biblioteca técnica Página 12 de 16

13 public CustomerService(URL url) { super(url, new QName(" "CustomerService")); Si su cliente es una clase Transaction (extiende a GenericTransaction) entonces pueden leer el url de un parámetro de contexto, así: URL url = new URL(getContext().getInitParameter("wsdl-location")); Customer obj = new CustomerService(url).getCustomerPort(); De esta manera el mismo cliente -sin cambios de código- pasa de un ambiente de desarrollo a uno de producción. Leer el WSDL de una ubicación local Basándonos en esta mejora, se puede incorporar otra: leer el WSDL de una ubicación local, evitando demoras por tener que leerlo del servidor remoto. Bastaría con indicar un URL que haga referencia a un directorio local, ejemplo: file:c:/servicios/customer.wsdl. Este archivo WSDL si deberá contener la ruta al servicio remoto, normalmente se ubica al final del archivo. Para obtener este archivo y almacenarlo localmente, navegue con el browser al WSDL y luego proceda a grabarlo como un archivo XML local. Medir la velocidad de ejecución de un servicio Utilizando el filtro PerformanceFilter que viene incorporado con Dinámica, bastaría definir un mapping hacia /service/* por ejemplo, para que el framework genere una traza de los tiempos de ejecución de todas las solicitudes relacionadas con servicios SOAP publicados por la aplicación. <!--performance filter mapping--> <filter-mapping> <filter-name>performancefilter</filter-name> <url-pattern>/service/*</url-pattern> </filter-mapping> Para mayor información consulte la documentación sobre trazas de rendimiento con Dinámica: Biblioteca técnica Página 13 de 16

14 Un cliente Java directo Existe una manera de invocar en Java un web service, sin utilizar el cliente JAX-WS ni el WSDL del servicio, se trata de hacer una invocación usando un API de cliente HTTP, enviando la petición XML de acuerdo al estándar SOAP, y luego parsear la respuesta, a sabiendas de cómo debe venir formado el XML de respuesta, el cual se puede estudiar con un Proxy cuando usamos un cliente JAX-WS. En nuestro ejemplo estamos usando el componente HTTPClient, viejo pero bueno: Lo que sigue es un fragmento de un cliente directo, que invoca el mismo servicio que se creó al principio de esta guía. import HTTPClient.*; import dinamica.xml.*;... public static void main(string[] args) throws Exception { String xml = "<?xml version=\"1.0\"?>" + "<S:Envelope xmlns:s=\" + "<S:Body><ns2:findByID xmlns:ns2=\" + "<arg0>bergs</arg0>" + "</ns2:findbyid>" + "</S:Body>" + "</S:Envelope>"; Este es el parámetro de búsqueda. HTTPConnection con; NVPair headers[] = new NVPair[1]; HTTPResponse rsp = null; con = new HTTPConnection("http", " ", 80); headers[0] = new NVPair("Content-Type", "text/xml; charset=utf-8"); con.setdefaultheaders(headers); byte buf[] = xml.getbytes(); rsp = con.post( "/devel/service/findcustomer", buf ); Document doc = new Document(rsp.getInputStream()); Element e = doc.getelement("//return"); System.out.println(e.getString()); En este elemento vendrá el valor de retorno del servicio. Así enviamos la petición. Biblioteca técnica Página 14 de 16

15 Entonando un cliente JAX-WS con Dinámica Al instanciar un cliente de un web service, si la interfaz es muy compleja, con muchos métodos y parámetros de tipos compuestos (clases), entonces el tiempo de instanciación del Proxy -el objeto que nos permite invocar al web service como si fuera local- puede ser inaceptable, de 3 segundos o mas en cada invocación. Asumiendo que tiene una clase que extiende a GenericTransaction, y que en el método service() de esta clase invoca a un web service para resolver cierta lógica de negocios, es en este punto que experimentará el retraso si la interfaz del servicio es compleja. La solución es usar una variable modular en su clase, de tipo ThreadLocal, que permite tener una variable que es privada o local a cada Thread, y que será inicializada solo la primera vez que invoque el Action que usa a esta clase. El uso de ThreadLocal elimina la contención entre Threads ya que no tienen que compartir una variable, y por lo tanto no hay sincronización no bloqueos. Permite cachear el Proxy del web service de manera segura, resolviendo un problema de rendimiento y también de concurrencia. Es una solución avanzada. Para implementarlo, en la clase que invoca al web service, que debe extender a GenericTransacion, o puede ser un Servlet si no está usando Dinámica, tiene que declarar una variable a nivel modular (de clase), de esta manera: private static final ThreadLocal<XxxService> proxy = new ThreadLocal<XxxService>() { ; protected XxxService initialvalue() { URL url = null;; XxxService obj = null; try { url = new URL("file:c:/tomcat6/webapps/devel/Xxx.wsdl"); obj = new XxxService_Service(url).getXxxService(); catch (MalformedURLException e) { e.printstacktrace(); return obj; Lo que está resaltado en amarillo es lo que tendrá que cambiar, ya que la función initialvalue() debe retornar un objeto del tipo de su Proxy. Así mismo puede parametrizar la ubicación del WSDL, en este ejemplo aparece cableado para efectos de simplificar el ejemplo, pero bien podría leerse la ubicación de un System Property pasado a Tomcat al momento de su ejecución. Biblioteca técnica Página 15 de 16

16 Luego en el código que invoca al web service, solo debe llamar la función get() de la variable proxy para obtener un objeto que le permita invocar los métodos remotos del web service: XxxService obj = proxy.get(); Solo la primera invocación será costosa, el resto de las invocaciones tardarán 0 milisegundos, resolviendo un problema potencial de rendimiento en su lógica de negocios, y es muy superior como técnica a implementar un pool de conexiones, porque no requiere de sincronización, pero al mismo tiempo es seguro por la naturaleza del ThreadLocal. Cada Thread de Tomcat que llega a procesar un request o Action que usa su clase, tendrá una de estas variables ThreadLocal. Si se crea un nuevo Thread producto de la carga que está procesando Tomcat, la primera invocación en este Thread pagará el precio de la instanciación del proxy, pero las siguientes invocaciones serán instantáneas. Biblioteca técnica Página 16 de 16