DENODO ITPILOT 4.0 GUÍA DEL DESARROLLADOR NOTA Este documento es confidencial y propiedad de denodo technologies (en adelante denodo). Ninguna de las partes del documento puede ser copiada, fotografiada, fotocopiada, transmitida electrónicamente, almacenada en un sistema de gestión documental o reproducida mediante cualquier otro mecanismo sin la autorización previa o por escrito de denodo. copyright © 2007 Queda prohibida la reproducción total o parcial de este documento sin la autorización por escrito de denodo technologies ITPilot 4.0 Guía del Desarrollador ÍNDICE PREFACIO...........................................................................................................................................................................I ALCANCE .....................................................................................................................................................................I QUIÉN DEBERÍA USAR ESTE DOCUMENTO..........................................................................................................I RESUMEN DE CONTENIDOS....................................................................................................................................I 3.1 CONEXIÓN AL SERVIDOR..................................................................................................................... 4 3.2 OBTENCIÓN DE WRAPPERS................................................................................................................ 5 3.3 UTILIZACIÓN DE WRAPPERS .............................................................................................................. 5 3.4 PROCESAMIENTO DE RESULTADOS DE CONSULTAS.................................................................... 6 3.5 EJEMPLO DE UTILIZACIÓN.................................................................................................................. 8 4.1 INTRODUCCIÓN ................................................................................................................................... 10 4.2 FORMATO DE REPRESENTACIÓN DE UN WRAPPER.................................................................... 10 4.2.1 Función de Inicialización de Parámetros Buscables......................................... 11 4.2.2 Función principal .................................................................................................... 11 4.2.3 Función de Generación de Estructura de Salida.............................................. 11 4.3 GUÍA DE COMPONENTES ITPILOT PREDEFINIDOS....................................................................... 11 4.3.1 Introducción ............................................................................................................ 11 4.3.2 Estructuras de Datos............................................................................................... 11 4.3.3 Funciones comunes ............................................................................................... 15 4.3.4 Add Record To List.................................................................................................. 17 4.3.5 Condition ................................................................................................................. 18 4.3.6 Create List ................................................................................................................ 19 4.3.7 Create Persistent Browser ...................................................................................... 20 4.3.8 Diff ............................................................................................................................. 21 4.3.9 Expression................................................................................................................. 24 4.3.10 Extractor ................................................................................................................... 25 4.3.11 Fetch......................................................................................................................... 26 4.3.12 Filter ........................................................................................................................... 27 4.3.13 Form Iterator ............................................................................................................ 28 4.3.14 Get Page ................................................................................................................. 33 4.3.15 Init .............................................................................................................................. 34 4.3.16 Iterator ...................................................................................................................... 39 4.3.17 JDBCExtractor ......................................................................................................... 40 4.3.18 Loop .......................................................................................................................... 42 4.3.19 Next Interval Iterator............................................................................................... 43 4.3.20 Output ...................................................................................................................... 45 4.3.21 Record Constructor ................................................................................................ 46 4.3.22 Record Sequence .................................................................................................. 47 4.3.23 Release Persistent Browser..................................................................................... 48 4.3.24 Repeat...................................................................................................................... 49 4.3.25 Script ......................................................................................................................... 50 4.3.26 Sequence................................................................................................................. 51 4.3.27 Store File ................................................................................................................... 53 4.3.28 Thread....................................................................................................................... 54 4.4 COMPONENTES A MEDIDA EN WRAPPERS JAVASCRIPT ......................................................... 55 4.4.1 Desarrollo de Componentes a Medida.............................................................. 55 4.4.2 Utilización de Componentes a Medida.............................................................. 56 4.5 DESARROLLO DE WRAPPERS ........................................................................................................... 56 BIBLIOGRAFÍA ............................................................................................................................................................... 57 ITPilot 4.0 Guía del Desarrollador ITPilot 4.0 Guía del Desarrollador ÍNDICE DE FIGURAS Figura 1 Ejemplo de ejecución de una consulta sobre un wrapper........................................................................ 9 ITPilot 4.0 Guía del Desarrollador PREFACIO ALCANCE Denodo ITPilot permite acceder y extraer datos fácilmente desde fuentes de información web semi-estructuradas. Este documento es una introducción al desarrollo de aplicaciones utilizando wrappers creados mediante Denodo ITPilot. QUIÉN DEBERÍA USAR ESTE DOCUMENTO Este documento está dirigido a desarrolladores que quieran conocer con detalle cómo se desarrollan aplicaciones que saquen partido de las funcionalidades avanzadas de automatización y extracción de datos web proporcionadas por Denodo ITPilot. La información detallada precisa para instalar el sistema y administrarlo se proporciona en otros manuales, que serán referenciados a medida que sea necesario. RESUMEN DE CONTENIDOS Más concretamente, en este documento: • Se presentan las tareas fundamentales que son necesarias para desarrollar una aplicación que utilice los wrappers generados mediante Denodo ITPilot. • Se describe la tarea de exportación de un wrapper como Web Service y su despliegue. • Se detalla cómo utilizar el API de desarrollo ofrecida por Denodo ITPilot. • Se muestra un ejemplo de desarrollo de una aplicación que utiliza un wrapper instalado en un servidor de ejecución de Denodo ITPilot. • Se explica en detalle cómo desarrollar wrappers, utilizando los componentes JavaScript de Denodo ITPilot. Prefacio i ITPilot 4.0 1 Guía del Desarrollador INTRODUCCIÓN Denodo ITPilot es la solución de Denodo Technologies que permite extraer y estructurar datos presentes en fuentes web. Este proceso se realiza mediante la construcción de una abstracción de la fuente web deseada, denominada “wrapper” o envoltorio, que independiza a las aplicaciones cliente de las dificultades asociadas a acceder y extraer los datos deseados. ITPilot proporciona un entorno distribuido y escalable de generación, ejecución y mantenimiento de “wrappers”. Véase [USER] y [GENER] para más información sobre cómo crear, instalar y mantener wrappers utilizando Denodo ITPilot Este manual describe el API JAVA de desarrollo que permite la construcción de clientes que utilicen los wrappers previamente creados e instalados. Se exponen las directrices básicas para el uso del API, se describen sus principales componentes y se proporcionan algunos ejemplos de uso. Véase la documentación Javadoc [JDOC] para mayor detalle sobre clases, atributos y operaciones. Además, este manual explica cómo acceder a los wrappers a través de Web Services exportados en el entorno de ejecución. Introducción 2 ITPilot 4.0 2 Guía del Desarrollador DESPLIEGUE E INVOCACIÓN DE WEB SERVICES DE ACCESO A WRAPPERS ITPILOT Los wrappers almacenados en el servidor de ejecución pueden ser invocados de dos manera diferentes. Por una parte, se puede utilizar el API Java nativo de ITPilot para acceder a los wrappers, obtener su estructura de datos, y ejecutar consultas sobre ellos desde una aplicación Java; su descripción se puede encontrar en el apartado 3. Otra opción es la de exponer estos wrappers a través de Web Services. Para un wrapper determinado, se puede generar un Web Service que contendrá las siguientes operaciones: • Una operación que contiene todos los parámetros buscables y obligatorios. • Opcionalmente, otra operación con todos los parámetros buscables y obligatorios, más aquellos buscables y optativos que hayan sido seleccionados en el proceso de generación del Web Service (este proceso se encuentra definido en [USER]). El servidor de ejecución de ITPilot genera un Web Service como un fichero .war que puede ser desplegado en cualquier servidor de aplicaciones J2EE. Se puede acceder a ese Web Service utilizando cualquier cliente o generador de clientes Web Service que cumpla los estándares SOAP/1.2 [SOAP] y WSDL 1.1 [WSDL], como las herramientas wsdl2java de Apache Axis [AXIS], o .wsdl de NET Framework [DOTNET]. El WSDL a partir del cuál se generan los clientes puede obtenerse o del fichero local creado por ITPilot, o mediante la URL de acceso al WSDL del Web Service, http://<dominio>:<puerto>/<nombre_de_servicio>/services/<nombre_de_servicio>?wsdl. La distribución de ITPilot, en el directorio samples/itpilot/itp-clients contiene un cliente ejemplo generado con Apache Axis. El fichero README residente en esa ruta contiene información detallada acerca de cómo generar, compilar y ejecutar los ficheros que componen la aplicación cliente. Despliegue e Invocación de Web Services de Acceso a Wrappers ITPilot 3 ITPilot 4.0 3 Guía del Desarrollador API DE DESARROLLO ITPILOT Denodo ITPilot dispone de una API JAVA para el desarrollo de aplicaciones sobre los wrappers creados con el mismo. Esta API ha sido probada exitosamente con J2SE 1.4.x y 1.5.x. Esta API permite, entre otras funciones, conectarse a un servidor de ejecución de Denodo ITPilot, obtener una referencia a un wrapper instalado en dicho servidor y realizar la ejecución de consultas sobre él. También permite una serie de tareas adicionales como obtener la lista de wrappers instalados en el servidor o activar el mantenimiento automático de un wrapper determinado. El primer paso en la utilización del API es conectarse a un servidor de ejecución de Denodo ITPilot. Esto se realiza construyendo una instancia de la clase com.denodo.itpilot.client.HTMLWrapperServerProxy. Dicha instancia permitirá, entre otras tareas, obtener una lista de los wrappers disponibles en el servidor y obtener una referencia a un wrapper concreto, representado a través de una instancia de la clase HTMLWrapperProxy. Dicha instancia podrá ser utilizada para realizar diversas tareas sobre el wrapper, la más importante de las cuáles es la ejecución de consultas. Al invocar una consulta sobre el wrapper, los resultados serán devueltos a la aplicación de forma asíncrona (esto es, los primeros resultados de la consulta serán accesibles a la aplicación a medida que se vayan obteniendo de la fuente, sin necesidad de esperar a la recepción de todos los resultados). Los siguientes subapartados se ocupan con más detalle de cada una de las etapas que se han mencionado: conexión al servidor, obtención de referencias a wrappers, ejecución de acciones sobre los mismos y procesamiento de consultas. Una descripción exhausiva del API a nivel de programación puede encontrarse en la documentación Javadoc [JDOC]. 3.1 CONEXIÓN AL SERVIDOR Existen dos posibilidades para realizar la conexión a un servidor de ejecución de ITPilot en función de si Denodo Virtual DataPort [DPORT] está instalado o no en la misma localización que ITPilot. Si se ha instalado Denodo ITPilot en solitario entonces debe utilizarse el modo de conexión al servidor por defecto (constructor HTMLWrapperServerProxy(String host, int port) ) indicando la máquina y puerto dónde se ejecuta el servidor. Si Denodo ITPilot está instalado conjuntamente con Denodo Virtual DataPort, entonces DataPort será utilizado como servidor de ejecución para ITPilot. En ese caso, en la conexión al servidor será posible especificar cualquier base de datos creada en el servidor Virtual DataPort y utilizar cualquier usuario definido en el mismo. Las acciones permitidas al usuario serán coherentes con los permisos asignados a dicho usuario en el servidor DataPort para la base de datos especificada (véase [DPORT] para más información sobre la estructura de bases de datos, permisos y usuarios de Denodo Virtual DataPort). En este caso podrá utilizarse el constructor HTMLWrapperServerProxy(String host, int port, String dbName, String login, String password). En este constructor deben especificarse, además de la máquina y puerto en la que se ejecuta el servidor, el nombre de la base de datos del servidor Virtual DataPort a la que se desea conectar, el identificador de usuario con el que se desea acceder y la contraseña asociada al mismo. Es importante resaltar que, aunque esté instalado Virtual DataPort, es posible igualmente acceder al servidor utilizando el modo por defecto (constructor HTMLWrapperServerProxy(String host, int API de Desarrollo ITPilot 4 ITPilot 4.0 Guía del Desarrollador port) ). En ese caso, se accederá a una base de datos por defecto llamada ‘itpilot’. Para el acceso se utilizará el usuario predefinido ‘admin’ cuya contraseña asociada es también ‘admin’. 3.2 OBTENCIÓN DE WRAPPERS Tal y como se ha comentado en la sección anterior, la conexión al servidor de ejecución consiste en la creación de una instancia de la clase com.denodo.itpilot.client. HTMLWrapperServerProxy. Esta clase dispone de métodos para la obtención de información sobre el servidor de ejecución y para acceder a los wrappers presentes en el mismo: • • • • • • 3.3 Collection getHTMLWrapperNames(). Obtiene una colección con el nombre de los wrappers presentes en el servidor de ejecución. Nótese que si se está utilizando Virtual DataPort como servidor de ejecución, la conexión se habrá realizado a una base de datos de Virtual DataPort y se obtendrán sólo los wrappers asociados a dicha base de datos. HTMLWrapperProxy getHTMLWrapper(String wpName). Obtiene una referencia al wrapper del nombre especificado como parámetro. Collection getDatabaseNames(). Este método sólo puede ser utilizado por usuarios con permisos de administración en Virtual DataPort. Devuelve una colección con el nombre de las bases de datos que existen en el servidor. void deleteWrapper(String wpName). Elimina del servidor el wrapper con el nombre especificado como parámetro. void loadWrapper(String vql). Acepta como argumento de entrada el VQL que define una colección de wrappers, que carga en el servidor de ejecución. String getVQL(). Devuelve la descripción VQL de todos los wrappers del servidor de ejecución de ITPilot. UTILIZACIÓN DE WRAPPERS Una vez obtenida una referencia a un wrapper (instancia de la clase HTMLWrapperProxy) es posible realizar diversas operaciones sobre él a través de los métodos de dicha clase. Para ejecutar una consulta sobre el wrapper utilizaremos el método: HTMLWrapperResultIterator query(Map params). La consulta a ejecutar se representa como un mapa de pares nombre de atributo/valor. Los nombres de atributo deben corresponderse con los nombres de los parámetros de entrada especificados durante la creación del wrapper. Los valores deben especificarse como cadenas de caracteres. Esto es así incluso en el caso en que los parámetros de entrada esperados por el wrapper sean de otro tipo. Por ejemplo, si un wrapper espera un parámetro de tipo float, y deseamos asignarle en la invocación el valor 3.25, deberemos pasar como valor la cadena “3.25”. En el caso de valores de los tipos float, double y date, es importante asegurarse de que los valores se proporcionan de acuerdo a la configuración de internacionalización de la máquina en la que está instalado el servidor de ejecución en el que corre el wrapper. Es importante también tener en cuenta que para que la consulta se ejecute correctamente, debe especificarse un valor para todos los atributos obligatorios. Ver [GENER] para más información sobre el proceso de generación de wrappers en ITPilot. Aunque la mayor parte de las aplicaciones no lo precisarán, es posible obtener el esquema de un wrapper utilizando el método: HTMLWrapperMetaRegisterRawVO getSchema() API de Desarrollo ITPilot 5 ITPilot 4.0 Guía del Desarrollador Este método devuelve el esquema de los resultados que devolverá el wrapper y las características de los campos atómicos que forman parte del mismo. El esquema del wrapper fue definido durante la generación del mismo (ver [GENER]). Los resultados devueltos por un wrapper siguen una estructura jerárquica. Cada tupla consta de un valor para cada uno de los atributos que componen la respuesta del wrapper. Cada atributo puede ser atómico o compuesto. Los valores de los atributos atómicos pueden ser de cualquiera de los tipos básicos disponibles en ITPilot: int, long, float, double, text, date, boolean o blob. Los valores de los atributos compuestos serán de tipo array de registros. Cada registro estará formado a su vez por una serie de campos cuyos valores podrán, nuevamente, ser atómicos o compuestos. Por ejemplo, un wrapper que devuelve información sobre películas puede tener un esquema en el que cada resultado sea una tupla compuesta por los campos TITULO, DIRECTOR, y EDICIONES. TITULO y DIRECTOR son campos atómicos y EDICIONES es un campo compuesto conteniendo información sobre las diversas ediciones de la película disponibles (DVD, VHS, corte del director, etc.). El valor de EDICIONES es un array de registros dónde cada registro contiene los campos FORMATO, PRECIO y DESCRIPCION, todos ellos atómicos. La invocación a getSchema() devuelve una instancia de la clase HTMLWrapperMetaRegisterRawVO , la cuál representa el esquema de un registro “jerárquico” de la forma de los descritos anteriormente. Véase la documentación Javadoc para una descripción detallada de los métodos proporcionados por HTMLWrapperMetaRegisterRawVO. También es posible acceder a las características de los diversos campos atómicos que componen el esquema. La información sobre estos campos atómicos se representa mediante instancias de la clase HTMLWrapperMetaSimpleRawVO. En particular, puede obtenerse su tipo (mediante el método java.lang.Class getType()), si el valor se obtiene o no de la fuente (es decir, se indica si es un campo de búsqueda que no se encuentre en el esquema de salida), si un campo es o no un parámetro de búsqueda (método boolean isSearchStatus()) y, en ese caso, si es o no obligatorio (método boolean isMandatoryStatus()). Además, si han sido definidos durante el proceso de generación, también es posible obtener la expresión regular (método java.lang.String getRegexp() ) y los alias definidos para cada campo (método java.util.List getTextValues()). Por último, el método: void setMaintenance(boolean value) permite fijar programáticamente si un wrapper debe o no ser mantenido automáticamente por el servidor de mantenimiento de ITPilot. 3.4 PROCESAMIENTO DE RESULTADOS DE CONSULTAS El método query para la ejecución de consultas sobre un wrapper devuelve como resultado una instancia de la clase com.denodo.itpilot.client.HTMLWrapperResultIterator. Esta clase (que implementa la interfaz java.util.Iterator) permite acceder “asíncronamente” a los resultados de la consulta efectuada. El que los resultados sean accedidos de forma “asíncrona” significa que el servidor devolverá los resultados de la consulta a medida que estos vayan siendo obtenidos de la fuente (debe recordarse que el wrapper obtiene la información de la fuente en tiempo real a través de la red). El método hasNext() permite comprobar si quedan elementos por devolver. Debido al comportamiento asíncrono de esta clase, este método debería de ser utilizado antes de acceder a cada elemento, para asegurar que los datos se encuentran disponibles. API de Desarrollo ITPilot 6 ITPilot 4.0 Guía del Desarrollador El método next() de HTMLWrapperResultIterator obtiene el siguiente resultado. En este caso, cada resultado será una instancia de la clase: com.denodo.vdb.vdbinterface.client.printer.standard.StandardRowVO. El valor de cada campo del esquema de salida puede obtenerse invocando el método: com.denodo.vdb.vdbinterface.common.clientResult.vo.sentences.ValueVO getValue (String fieldname) donde fieldname es el nombre del campo deseado. El método next() devolverá una excepción del tipo NoSuchElementException si no hay datos disponibles en el momento de su ejecución, aunque al wrapper todavía le queden resultados por devolver. De ahí la necesidad de utilizar el método hasNext() previamente. Tal y cómo se ha comentado en la sección anterior, el valor de un campo puede ser atómico o compuesto. Si es atómico, la instancia de ValueVO pertenecerá a la subclase SimpleVO. SimpleVO es una clase abstracta cuyas subclases se corresponden con los tipos básicos disponibles en ITPilot: TextVO, IntVO, LongVO, FloatVO, DoubleVO, DateVO, BooleanVO, BlobVO. Las subclases IntVO, LongVO, FloatVO, DoubleVO y BooleanVO proporcionan un método getXXX (donde XXX representa el nombre del tipo de datos) para acceder a su valor. Por ejemplo, IntVO proporciona el método: java.lang.Integer getInt() En el caso de BlobVO, se proporciona el método: java.lang.Byte[] getBytes() En el caso de DateVO, se proporciona el método: long getTime() Además, la superclase SimpleVO proporciona una representación del valor como cadena de caracteres accesible a través del método getValue(). Véase la documentación Javadoc para más detalle [JDOC]. Si el valor es compuesto, la instancia de ValueVO representará un array de registros (subclase ArrayVO). Utilizando su método getValues() podrá obtenerse una lista de los registros que contiene (instancias de la subclase RegisterVO). Véase la documentación Javadoc para ver información más detallada sobre los métodos y propiedades de la clase ValueVO y sus subclases. Otro aspecto importante del procesamiento de consultas es el tratamiento de los posibles errores que puedan producirse (e.g. error de conexión a la fuente de datos). Para ello existen otros dos métodos de la clase HTMLWrapperResultIterator: • • boolean checkErrors(). Permite comprobar si se ha producido algún error durante la ejecución de la consulta. Devuelve ‘true’ si ha habido algún error y ‘false’ en caso contrario. String getErrorDescription(). En caso de que se hayan producido errores, permite obtener una descripción textual de los mismos. En caso contrario devuelve null. API de Desarrollo ITPilot 7 ITPilot 4.0 3.5 Guía del Desarrollador EJEMPLO DE UTILIZACIÓN En esta sección se muestra un ejemplo sencillo de utilización del API. La aplicación comienza conectándose a un servidor de ejecución instalado en la máquina ‘acme’ en el puerto 9999. Seguidamente, obtiene una referencia al wrapper llamado “Movies” cuyo esquema es el mismo utilizado como ejemplo en la sección anterior: {TITLE, DIRECTOR, EDITIONS {FORMAT, PRICE, DESCRIPTION}}, siendo TITLE y DIRECTOR campos de búsqueda opcionales. A continuación, se realiza una consulta sobre el wrapper utilizando el parámetro de entrada DIRECTOR con el valor “Woody Allen” y se procesan sus resultados mostrándolos por la salida estándar. Para el procesamiento de los resultados, se navega a través de la estructura jerárquica de elementos ValueVO. En primer lugar se obtienen los objetos SimpleVO que representan a los campos atómicos TITLE y DIRECTOR. Posteriormente se realiza la navegación a través del campo compuesto EDITIONS, que es representado mediante un objeto ArrayVO que contiene un objeto RegisterVO por cada edición de la película. Cada uno de estos registros contiene los campos atómicos FORMAT, PRICE y DESCRIPTION. Todos los campos atómicos son de tipo text, excepto el campo PRICE, que es de tipo double. Finalmente, se comprueban los posibles errores producidos durante la ejecución. package com.denodo.itpilot.client; import import import import import import import import import java.util.List; java.util.HashMap; java.util.Map; java.util.Iterator; com.denodo.vdb.vdbinterface.common.clientResult.vo.sentences.ValueVO; com.denodo.vdb.vdbinterface.common.clientResult.vo.sentences.SimpleVO; com.denodo.vdb.vdbinterface.common.clientResult.vo.sentences.ArrayVO; com.denodo.vdb.vdbinterface.common.clientResult.vo.sentences.RegisterVO; com.denodo.vdb.vdbinterface.client.printer.standard.StandardRowVO; public class EjemploITPilot { public static void main(String args[]) { try { // Connect to server HTMLWrapperServerProxy server = new HTMLWrapperServerProxy ("acme",9999); // Get Wrapper HTMLWrapperProxy wrapper = server.getHTMLWrapper("Movies"); // Prepare query params Map queryParams = new HashMap (); queryParams.put ("DIRECTOR","Woody Allen"); // Execute query HTMLWrapperResultIterator results = wrapper.query(queryParams); // Iterate results int numOfTuples = 0; while (results.hasNext()) { API de Desarrollo ITPilot 8 ITPilot 4.0 Guía del Desarrollador numOfTuples++; StandardRowVO tuple = (StandardRowVO) results.next(); /* Process each tuple */ System.out.print(numOfTuples + ". "); //Get and print atomic fields: TITLE, DIRECTOR SimpleVO titleVO = (SimpleVO)tuple.getValue("TITLE"); String title = (String)titleVO.getValue(); System.out.println("TITLE:"+ title); SimpleVO directorVO = (SimpleVO)tuple.getValue("DIRECTOR"); String director = (String)directorVO.getValue(); System.out.println("DIRECTOR:" + director); // Get EDITIONS array ArrayVO editionsVO = (ArrayVO)tuple.getValue("EDITIONS"); // Iterate over EDITION registers int numEditions=0; Iterator editions = editionsVO.getValues().iterator(); while (editions.hasNext()) { numEditions++; System.out.println("EDITION: " + numEditions); RegisterVO editionVO = (RegisterVO)editions.next(); SimpleVO formatVO = (SimpleVO)editionVO.getValue("FORMAT"); String format = (String)formatVO.getValue(); System.out.println("\t FORMAT:" + format); DoubleVO priceVO = (DoubleVO)editionVO.getValue("PRICE"); Double price = priceVO.getDouble(); System.out.println("\t PRICE:" + price); SimpleVO descriptionVO=(SimpleVO)editionVO.getValue("DESCRIPTION"); String description = (String)descriptionVO.getValue(); System.out.println("\tDESCRIPTION:" + description); } System.out.println(""); } // Check errors if (results.checkErrors()) System.out.println("Error: " + results.getErrorDescription()); } catch(Exception e) { System.err.println("Error trying to access server ... "); } finally { // ... } } } Figura 1 Ejemplo de ejecución de una consulta sobre un wrapper API de Desarrollo ITPilot 9 ITPilot 4.0 4 4.1 Guía del Desarrollador DESARROLLO DE WRAPPERS ITPILOT EN JAVASCRIPT INTRODUCCIÓN Aunque Denodo provee una herramienta de generación de wrappers basada en componentes gráficos que permite crear programas envoltorio de acceso a fuentes semi-estructuradas (web, Adobe PDF o Microsoft Word) sin necesidad de desarrollo, ITPilot permite al usuario generar sus propios wrappers completos en JavaScript. La versión de JavaScript soportada por Denodo ITPilot es la 1.5, que es conforme a la versión 3.0 del estándar ECMA [ECMA262]. Los siguientes capítulos presuponen un conocimiento básico previo del lenguaje JavaScript. La sección 4.2 presentará el formato de representación en JavaScript de los wrappers ITPilot. Esto permitirá entender en la sección 4.3 cómo interactuar con los componentes ITPilot predefinidos en un wrapper, y cómo desarrollar wrappers completos en JavaScript, siguiendo las indicaciones de la sección 4.4. 4.2 FORMATO DE REPRESENTACIÓN DE UN WRAPPER Un wrapper ITPilot se estructura en JavaScript tal y como se muestra en la Tabla 1. Tabla 1: Esqueleto de un Wrapper ITPilot en JavaScript function getInit() { var start = new Init(); start.setText("INITPARAM", OBLIGATORY); return start; } function getOutputSchema() { var structureOutput = new Record_Structure("OUT_REC"); structureOutput.setText("ATTRIBUTE_1"); structureOutput.setText("ATTRIBUTE_2"); structureOutput.setText("ATTRIBUTE_3"); return structureOutput; } function main() { ... } En cada script se encuentran tres funciones, una obligatorio y dos opcionales: 1. función main(): es la única obligatoria, y contiene la implementación del componente. 2. función getInit(): esta función ha de utilizarse para devolver el conjunto de parámetros buscables. 3. función getOutputSchema(): esta función se utiliza para devolver la estructura de los objetos de salida, si existen.1 Las funciones se corresponden, grosso modo, con la definición del proceso definido mediante componentes, con los parámetros de entrada definidos en el componente de inicialización, y con el registro de salida tal y como lo recibe el componente de salida, respectivamente. 1 Desde la versión 4.0SP1 esta función, anteriormente llamada getMetadata, pasa a denominarse getOutputSchema. Se mantiene la compatibilidad hacia atrás, pero se recomienda vivamente la utilización de la nueva nomenclatura. Desarrollo de Wrappers ITPilot en JavaScript 10 ITPilot 4.0 4.2.1 Guía del Desarrollador Función de Inicialización de Parámetros Buscables En esta función se describen los parámetros de entrada del wrapper ITPilot. En el ejemplo, la primera línea de la función, var start = new Init();, es la que se encarga de crear un nuevo objeto de inicialización de parámetros. Este objeto se describe más adelante en la sección 4.3 de Catálogo de Componentes. 4.2.2 Función principal En la función principal es donde se desarrolla la lógica del wrapper. En esta función se pueden crear instancias de objetos que representan los diferentes componentes de ITPilot, tanto predefinidos como creados a medida (véase [GENER] para más información sobre cómo crear componentes a medida con ITPilot). Las funciones expuestas por cada uno de los componentes predefinidos en ITPilot se describen y explican en el apartado 4.3. 4.2.3 Función de Generación de Estructura de Salida Esta función es la que determina, si existe, cuál es la estructura de salida del wrapper. La estructura es un registro de datos definido mediante el objeto RecordStructure, que se define en el catálogo del apartado 4.3. 4.3 GUÍA DE COMPONENTES ITPILOT PREDEFINIDOS 4.3.1 Introducción En este capítulo se presenta la lista de componentes ITPilot predefinidos. Cada componente se representa como un objeto instanciable en JavaScript, con una serie de funciones que se describe y explican a continuación. NOTA: Algunos de los parámetros para las funciones descritas en cada componente pueden ser omitidos (invocando el método con menos parámetros). No se puede omitir un parámetro si se desea establecer el valor de otro situado a su derecha. Cuando un parámetro sea opcional, se indicará en la descripción de cada función el valor por defecto. Por ejemplo, para el objeto RECORD_STRUCTURE (ver apartado 4.3.2.1): rs.setText("FIELD") es equivalente a rs.setText("FIELD", ".*", OPTIONAL) rs.setText("FIELD", OBLIGATORY) no es válido. Debe usarse rs.setText("FIELD", ".*", OBLIGATORY) ". 4.3.2 Estructuras de Datos ITPilot define como estructuras de datos los tipos Lista y la de un registro de datos definido mediante el objeto Record Structure. A continuación se define cada uno de ellos. 4.3.2.1 Estructura Registro • Objeto: Record_Structure • Descripción: .representa una estructura de datos que permite definir la estructura de un registro concreto. Suele utilizarse en la función getOutputSchema() del wrapper (ver 4.2.3). Desarrollo de Wrappers ITPilot en JavaScript 11 ITPilot 4.0 • Guía del Desarrollador Funciones: o Constructor(name) - o o o o name: nombre del registro a crear setText(field, regexp, type): creación de un nuevo campo de tipo Cadena de Caracteres en el registro. - field: nombre del nuevo campo. - regexp (opcional): expresión regular de formación de la cadena de caracteres. Por defecto, si no se desea ningún tipo de restricción, el valor es “.*”. - type (opcional): indica si el parámetro es obligatorio o no. Por defecto se asume que el campo es opcional. Cuando se crea un componente a medida (ver sección 4.4) a partir de un programa envoltorio de ITPilot, se genera una instancia Record_Structure con las opcionalidades descritas como parámetros de entrada de ese componente. setLink(field, type): creación de un nuevo campo de tipo Enlace en el registro. - field: nombre del nuevo campo. - type (opcional): indica si el parámetro es obligatorio o no. Por defecto se asume que el campo es opcional. Cuando se crea un componente a medida (ver sección 4.4) a partir de un programa envoltorio de ITPilot, se genera una instancia Record_Structure con las opcionalidades descritas como parámetros de entrada de ese componente. setInt(field, type): creación de un nuevo campo de tipo Entero en el registro. - field: nombre del nuevo campo. - type (opcional): indica si el parámetro es obligatorio o no. Por defecto se asume que el campo es opcional. Cuando se crea un componente a medida (ver sección 4.4) a partir de un programa envoltorio de ITPilot, se genera una instancia Record_Structure con las opcionalidades descritas como parámetros de entrada de ese componente. setBoolean(field, type): creación de un nuevo campo de tipo Booleano en el registro. - field: nombre del nuevo campo. - type (opcional): indica si el parámetro es obligatorio o no. Por defecto se asume que el campo es opcional. Cuando se crea un componente a medida (ver sección 4.4) a partir Desarrollo de Wrappers ITPilot en JavaScript 12 ITPilot 4.0 Guía del Desarrollador de un programa envoltorio de ITPilot, se genera una instancia Record_Structure con las opcionalidades descritas como parámetros de entrada de ese componente. o o o o o setLong(field, type): creación de un nuevo campo de tipo Long en el registro. - field: nombre del nuevo campo. - type (opcional): indica si el parámetro es obligatorio o no. Por defecto se asume que el campo es opcional. Cuando se crea un componente a medida (ver sección 4.4) a partir de un programa envoltorio de ITPilot, se genera una instancia Record_Structure con las opcionalidades descritas como parámetros de entrada de ese componente. setFloat(field, type): creación de un nuevo campo de tipo Flotante en el registro. - field: nombre del nuevo campo. - type (opcional): indica si el parámetro es obligatorio o no. Por defecto se asume que el campo es opcional. Cuando se crea un componente a medida (ver sección 4.4) a partir de un programa envoltorio de ITPilot, se genera una instancia Record_Structure con las opcionalidades descritas como parámetros de entrada de ese componente. setDouble(field, type): creación de un nuevo campo de tipo Double en el registro. - field: nombre del nuevo campo. - type (opcional): indica si el parámetro es obligatorio o no. Por defecto se asume que el campo es opcional. Cuando se crea un componente a medida (ver sección 4.4) a partir de un programa envoltorio de ITPilot, se genera una instancia Record_Structure con las opcionalidades descritas como parámetros de entrada de ese componente. setBlob(field, type): creación de un nuevo campo de tipo BLOB (Binary Large Object) en el registro. - field: nombre del nuevo campo. - type (opcional): indica si el parámetro es obligatorio o no. Por defecto se asume que el campo es opcional. Cuando se crea un componente a medida (ver sección 4.4) a partir de un programa envoltorio de ITPilot, se genera una instancia Record_Structure con las opcionalidades descritas como parámetros de entrada de ese componente. setDate(field, regexp, format, type): creación de un nuevo campo de tipo Fecha en el registro. - field: nombre del nuevo campo. Desarrollo de Wrappers ITPilot en JavaScript 13 ITPilot 4.0 o o o Guía del Desarrollador - regexp (opcional): expresión regular de formación de la cadena de caracteres. Por defecto, si no se desea ningún tipo de restricción, el valor es “.*”. - format (opcional): formato del tipo fecha siguiendo las indicaciones de [DATEFORMAT]. Por defecto, su valor es "d-MMM-yyyy H'h' m'm' s's'". - type (opcional): indica si el parámetro es obligatorio o no. Por defecto se asume que el campo es opcional. Cuando se crea un componente a medida (ver sección 4.4) a partir de un programa envoltorio de ITPilot, se genera una instancia Record_Structure con las opcionalidades descritas como parámetros de entrada de ese componente. setRegister(record, type): creación de un campo de tipo registro. - record: nombre del registro. - type (opcional): indica si el parámetro es obligatorio o no. Por defecto se asume que el campo es opcional. Cuando se crea un componente a medida (ver sección 4.4) a partir de un programa envoltorio de ITPilot, se genera una instancia Record_Structure con las opcionalidades descritas como parámetros de entrada de ese componente. setArray(name, structure, type): creación de un nuevo campo de tipo Array en el registro. - name: nombre del array. - structure: estructura de datos que representa la estructura de los registros contenidos en el array. - type (opcional): indica si el parámetro es obligatorio o no. Por defecto se asume que el campo es opcional. Cuando se crea un componente a medida (ver sección 4.4) a partir de un programa envoltorio de ITPilot, se genera una instancia Record_Structure con las opcionalidades descritas como parámetros de entrada de ese componente. toString(): transforma el registro a una cadena de caracteres para su representación. NOTA: para asignar valores a los campos de un registro, se ha de utilizar el objeto RECORD_CONSTRUCTOR, explicado en el apartado 4.3.21. 4.3.2.2 Lista de Registros • Objeto: List • Funciones: o setListName(listName): nombre de la lista Desarrollo de Wrappers ITPilot en JavaScript 14 ITPilot 4.0 o 4.3.3 listName: nombre de la lista. add(obj): adición de un elemento a la lista - o Guía del Desarrollador obj: elemento a añadir. toArray(): transforma la lista en un array de objetos JavaScript. Funciones comunes Algunos de estas funciones son comunes a todos o casi todos los componentes, por lo que se muestran en esta primera sección. Se explicitará en el catálogo aquellos componentes que no dispongan de alguno de las funciones “comunes”. 4.3.3.1 • Función onError onError(errorId, errorAction). Indica al componente el comportamiento que debe tener en caso de que se produzca algún tipo de error. Se pueden realizar varias invocaciones de la función onError con valores del parámetro errorId diferentes. - - errorId: indica el tipo de error cuyo comportamiento se quiere gestionar. Los posibles valores son los siguientes: RUNTIME_ERROR: error ocurrido durante la ejecución del componente. CONNECTION_ERROR: error que ocurre cuando hay algún tipo de problema de conexión con la fuente web. HTTP_ERROR: error producido por un error http. TIMEOUT_ERROR: si la fuente web tarda en contestar, se produce este error. El tiempo de espera es configurable. Si el wrapper se utiliza en el entorno de ejecución, este parámetro se configura en el pool de navegadores utilizado (ver [USER]). En el entorno de generación que nos ocupa, este valor se configura en el fichero ITPAdminConfiguration.properties disponible en <DENODO_HOME>/conf/itp-admintool, con la propiedad IEBrowser.MAX_DOWNLOAD_TIME. SEQUENCE_ERROR: error que se produce cuando hay algún problema con la secuencia (la secuencia no está bien escrita, algún comando no ha podido ser ejecutado, etc.). errorAction: acción a realizar cuando se produzca el error indicado en el parámetro anterior. Los posibles valores son los siguientes: ON_ERROR_RAISE: parar la ejecución del wrapper, indicando la procedencia del error. Desarrollo de Wrappers ITPilot en JavaScript 15 ITPilot 4.0 4.3.3.2 • Guía del Desarrollador ON_ERROR_IGNORE: ignorar el error, continuando con la ejecución del wrapper. En general, los componentes que tienen algún tipo de valor de retorno devuelven “null” en caso de error, excepto en los casos de los componentes FILTER (4.3.12) y RECORD CONSTRUCTOR (0). En los casos de LOOP (4.3.17), REPEAT (4.3.23) y CONDITION (4.3.5), aunque devuelvan “null”, se evaluará como “false” en caso de utilizarse en una condición. ON_ERROR_RETRY: volver a ejecutar el wrapper. El número de reintentos e intervalo de tiempo entre reintentos se configura en cada parámetro. ON_ERROR_RETRY_IGNORE: volver a ejecutar el wrapper, tal y como ocurre con la opción ON_ERROR_RETRY, pero continuando con la ejecución del wrapper en caso de que tras los reintentos el error se siga ejecutando. Función debugLevel debugLevel(level): permite indicar el nivel de traza que se va a utilizar en la ejecución de este componente. Los posibles niveles se definen numéricamente entre 0 y 5, donde 0 significa que no se almacenará ningún mensaje de traza, y 5 que todos los mensajes de traza de todos los tipos serán escritos en el fichero de traza. Los tipos de traza son los siguientes: - TRACE DEBUG INFO WARN ERROR FATAL Desarrollo de Wrappers ITPilot en JavaScript 16 ITPilot 4.0 4.3.4 Guía del Desarrollador Add Record To List • Objeto: Add_Object_To_List • Descripción: añade un registro a una lista • Funciones: o Constructor() o exec(record, list): ejecuta la función. - record: registro a añadir a la lista - list: lista a la cuál se añade el registro. Desarrollo de Wrappers ITPilot en JavaScript 17 ITPilot 4.0 4.3.5 Guía del Desarrollador Condition • Objeto: Condition • Descripción: permite definir una condición. Dos conexiones de salida determinan el flujo del proceso dependiendo de si la condición se cumple o no. • Funciones: - Constructor(expr) - expr: este parámetro define la expresión de condición. Se expresa como una cadena de caracteres (e.g. MyCondition = new Condition("($0 <= $1)" indica que de la lista de elementos que se pasan al componente en el método exec, el valor del primero ha de ser menor o igual al valor del segundo). exec(elements): función principal del componente Condition. Efectúa la operación de condición, devolviendo “true” o “false” dependiendo de si la condición descrita en el constructor se cumple cuando se aplica sobre los elementos del parámetro de entrada. elements: este parámetro, que ha de seguir el formato “[ELEMENTO1, ELEMENTO2, …, ELEMENTON]”, determina los elementos sobre los cuáles se efectua la condición. Desarrollo de Wrappers ITPilot en JavaScript 18 ITPilot 4.0 4.3.6 Guía del Desarrollador Create List • Objeto: Create_List • Descripción: crea una lista vacía. • Funciones: o Constructor(listname). Crea una lista vacía - o listname: nombre de la lista de registros a crear. exec(). Ejecuta el componente. Desarrollo de Wrappers ITPilot en JavaScript 19 ITPilot 4.0 4.3.7 Guía del Desarrollador Create Persistent Browser • Objeto: Create_Persistent_Browser • Descripción: permite crear un navegador persistente, es decir, un navegador que se mantiene activo tras la ejecución del programa envoltorio que lo arrancó. • Funciones o Constructor(): crea un navegador persistente y devuelve su manejador. o exec(). Ejecuta el componente. Desarrollo de Wrappers ITPilot en JavaScript 20 ITPilot 4.0 4.3.8 Guía del Desarrollador Diff • Objeto: Diff • Descripción: El componente Diff permite comparar dos páginas, devolviendo las diferencias existentes entre ellas, en cuanto al código HTML obtenido. • Funciones: - - - Constructor(additionPrefixLabel, additionSuffixLabel, deletionPrefixLabel, deletionSuffixLabel, tokenSeparator) additionPrefixLabel: indica cuál es el prefijo a utilizar al generar la página resultado para el contenido nuevo (por defecto, etiqueta HTML de fondo en verde). additionSuffixLabel: indica cuál es el sufijo a utilizar al generar la página resultado para el contenido nuevo (por defecto, etiqueta HTML de fin de fondo en verde). deletionPrefixLabel: indica cuál es el prefijo a utilizar al generar la página resultado para el contenido eliminado (por defecto, etiqueta HTML de fondo en rojo). deletionSuffixLabel: indica cuál es el sufijo a utilizar al generar la página resultado para el contenido nuevo (por defecto, etiqueta HTML de fin de fondo en rojo). tokenSeparator: se utiliza para indicar la cadena de caracteres que servirá como separador de los elementos de las páginas HTML cuando se genera la página resultado, de manera que cada uno de ellos se pueda identificar adecuadamente. diff (baseCode, finalCode): devuelve “true” si ambas páginas son iguales, “false” si son diferentes baseCode: cadena de caracteres con el contenido de la página de origen. finalCode: cadena de caracteres o un objeto página con el contenido de la página destino. exec (baseCode, finalCode): ejecuta el componente Diff, devolviendo una cadena de caracteres que representa el contenido HTML de estas páginas, indicando las diferencia entre ambas. baseCode: cadena de caracteres con el contenido de la página de origen. Desarrollo de Wrappers ITPilot en JavaScript 21 ITPilot 4.0 - nullWhenEquals: “true” implica que se devolverá “null” si ambas páginas se consideran iguales,; “false” indica que se devolverá la página resultado. setIgnoreTagAttributes(simplifyTags): esta función indica que el componente no tenga en cuenta los atributos de las etiquetas HTML cuando se realiza la comparación entre ambas páginas. - deletionSuffixLabel: indica cuál es el sufijo a utilizar al generar la página resultado para el contenido nuevo (por defecto, etiqueta HTML de fin de fondo en rojo). setNullWhenEquals(nullWhenEquals): indica que si la página resultado es igual a alguna de las dos páginas de entrada, el componente devuelva “null” en lugar de la página en sí. - deletionPrefixLabel: indica cuál es el prefijo a utilizar al generar la página resultado para el contenido eliminado (por defecto, etiqueta HTML de fondo en rojo). setDeletionSuffixLabel(deletionSuffixLabel): permite modificar la etiqueta de finalización de datos eliminados. - additionSuffixLabel: indica cuál es el sufijo a utilizar al generar la página resultado para el contenido nuevo (por defecto, etiqueta HTML de fin de fondo en verde). setDeletionPrefixLabel(deletionPrefixLabel): permite modificar la etiqueta de comienzo de datos eliminados. - additionPrefixLabel: indica cuál es el prefijo a utilizar al generar la página resultado para el contenido nuevo (por defecto, etiqueta HTML de fondo en verde). setAdditionSuffixLabel(additionSuffixLabel): permite modificar la etiqueta de finalización de datos adicionales. - finalCode: cadena de caracteres u objeto página con el contenido de la página destino. setAdditionPrefixLabel (additionPrefixLabel): permite modificar la etiqueta de comienzo de datos adicionales. - Guía del Desarrollador simplifyTags: con el valor a “true”, se ignorarán los atributos de las etiquetas HTML. Con “false”, no se ignorarán. setCaseInsensitive (toLowerCase): con esta función se establece si se tienen en cuenta la diferencia entre mayúsculas y minúsculas en la comparación entre páginas. toLowerCase: “true”, transforma todo el contenido HTML a minúsculas. “false”, mantiene el contenido como está. Desarrollo de Wrappers ITPilot en JavaScript 22 ITPilot 4.0 - setShowRemovedContent(mergedDeletions): indica si se muestra el contenido eliminado en el resultado, o no. - mergedDeletions: “true”, el contenido eliminado será mostrado. Si el valor está a “false”, la configuración de las funciones setDeletionPrefixLabel y setDeletionSuffixLabel no se tendrá en cuenta. addTokenReplacement(replacement): permite añadir una expresión regular a una lista. Estas expresiones regulares se aplicarán sobre los tokens HTML de las páginas origen antes de efectuar la comparación. - Guía del Desarrollador replacement: expresión regular en Perl [PERL]. addIgnoredToken(regexp): permite añadir una expresión regular a una lista. Estas expresiones regulares se aplicarán sobre los tokens HTML. Aquellos que cumplan la expresión regular serán descartados antes de efectuar la comparación. regexp: expresión regular en Perl [PERL]. Desarrollo de Wrappers ITPilot en JavaScript 23 ITPilot 4.0 4.3.9 Guía del Desarrollador Expression • Objeto: Expression • Descripción: permite definir una expresión (a partir de constantes y/o utilización de las funciones provistas por ITPilot) que será evaluada a un valor de salida. • Funciones: - Constructor(expression) - expression: objeto que define la expresión de condición. Este objeto se expresa como una cadena de caracteres (e.g. MyCondition = new CONDITION("($0 <= $1)" indica que de la lista de elementos que se pasan al componente en el método exec, el valor del primero ha de ser menor o igual al valor del segundo). exec(exprInput): método que ejecuta el componente, y devuelve el valor resultado de la expresión indicada en el constructor del componente. exprInput: lista de cero o más valores, cero o más registros o cero o más listas de registros que se utilizan como parte de la expresión. Desarrollo de Wrappers ITPilot en JavaScript 24 ITPilot 4.0 4.3.10 Guía del Desarrollador Extractor • Objeto: Extractor • Descripción: se encarga de extraer información estructurada de una página HTML, generando por tanto un programa DEXTL ([DEXTL]). • Funciones: - Constructor(name, page, specification, structure) name: nombre de la instancia del componente Extractor. page: estructura ITPilot de tipo página de la cuál se quiere extraer información. specification: especificación DEXTL de extracción de datos (ver [DEXTL]). structure: nombre del registro (creado previamente) que será utilizado para devolver los datos extraídos por la especificación. - exec(): método principal del extractor, realiza la ejecución de la especificación indicada en el constructor. Esta función devuelve una lista de registros del tipo definido en el constructor, en el parámetro structure. - setMergePatterns(merge): aplica la técnica de combinación de patrones para una mejor optimización del sistema (ver [GENER] para más información). merge: parámetro booleano, “true” si se desea que se aplique la técnica de combinación de patrones, o “false” si no se desea. Por defecto, está a “true”. Desarrollo de Wrappers ITPilot en JavaScript 25 ITPilot 4.0 4.3.11 Guía del Desarrollador Fetch • Objeto: Fetch • Descripción: obtiene el contenido de la URL o página utilizadas como argumento de entrada, y lo devuelve, ya sea en formato binario o textual. • Funciones: o o Constructor(url, sequenceType, reusableConnection, binary, page) - url: URL donde se puede encontrar el recurso a descargar (OPTIONAL). - sequenceType: tipo de pool a utilizar. Los valores posibles son: • SEQUENCE_IEBROWSER • SEQUENCE_HTTP_BROWSER • SEQUENCE_FTP • SEQUENCE_LOCAL - reusableConnection: indica si la conexión va a reutilizarse (“true”) o no (“false”). Ver [GENER] para más información. - binary: “true”: el objeto es binario; “false”: el objeto a descargar se encuentra en forma textual. - page: opcionalmente, se permite indicar la página a partir de la cuál se lanza la petición http. exec(page). Ejecuta el componente, devolviendo el valor obtenido, de tipo cadena o binario. - page: opcionalmente, se permite indicar la página a partir de la cuál se lanza la petición http. Desarrollo de Wrappers ITPilot en JavaScript 26 ITPilot 4.0 4.3.12 Guía del Desarrollador Filter • Objeto: Filter • Descripción: realiza una operación de filtrado de una lista de registros, devolviendo aquellos que cumplan una condición dada. • Funciones: o o Constructor(expr, auxiliaryRecords) - expr: expresión regular de la operación de filtrado de una lista de registros, los cuáles se describen en la función exec. - auxiliaryRecords: lista de registros que participan en la condición de filtrado, pero que no son los registros a filtrar. exec(inputRecords, auxiliaryRecords): función que recibe una lista de registros, y devuelve el subconjunto que cumpla la expresión de selección indicada en el constructor. - inputRecords: lista de registros de entrada. - auxiliaryRecords: lista de registros que participan en la condición de filtrado, pero que no son los registros a filtrar. NOTA: En caso de que el manejador de error de este componente se encuentre configurado como ON_ERROR_IGNORE, FILTER devolverá la lista de elementos filtrados, excepto aquél que haya producido el error. Desarrollo de Wrappers ITPilot en JavaScript 27 ITPilot 4.0 4.3.13 Guía del Desarrollador Form Iterator • Objeto: Form_Iterator • Descripción: permite generar un bucle de ejecución de un formulario concreto donde en cada ejecución se utilizan valores predeterminados de cada uno de los campos que lo conforman. • Funciones: o Constructor(findForm, submitForm, inputPage, parallelIterator) sequenceType, reusableConnection, baseElements, - findForm: programa NSEQL que permite encontrar el formulario que se desea utilizar como base de la iteración (ver [NSEQL] para más información sobre NSEQL)... - submitForm: programa NSEQL que permite invocar el formulario (ver [NSEQL] para más información sobre NSEQL). - sequenceType: tipo de pool a utilizar. Los valores posibles son: • SEQUENCE_IEBROWSER • SEQUENCE_HTTP_BROWSER • SEQUENCE_FTP • SEQUENCE_LOCAL - reusableConnection: indica si la conexión va a reutilizarse (“true”) o no (“false”). Ver [GENER] para más información. - baseElements: lista opcional de registros que pueden servir como variables a utilizar en las diferentes secuencias de navegación NSEQL utilizadas en este componente. - inputPage: página de entrada desde la cuál invocar iteradamente el formulario seleccionado. - parallelIterator: indicar si se desea que el componente efectúe sus iteraciones en paralelo. “true” indica que sí, “false” que no. Desarrollo de Wrappers ITPilot en JavaScript 28 ITPilot 4.0 o o Guía del Desarrollador selectMultiplePositions(field, position, positionsArray, clickedArray). Indica qué posiciones se seleccionan de un campo de selección múltiple del formulario elegido. - field: nombre del campo de selección múltiple. - position: posición relativa del campo entre aquellos que tengan el mismo nombre, comenzando por la posición 0. - positionsArray: lista que indica, para cada elemento de valuesArray, qué posición ocupa en caso de que haya valores replicados. - clickedArray: lista que indica, para cada elemento de positionsArray, si puede estar marcado, no marcado, o de ambas maneras. Para ello hay unas constantes JavaScript definidas: • CLICKED_ELEMENT: marcar el elemento. • NON_CLICKED_ELEMENT: dejar el elemento como no marcado. • CLICKED_AND_NON_CLICKED_ELEMENT: genera dos combinaciones, una con el elemento marcado, y otra con el elemento no marcado. selectMultipleTexts(field, position, valuesArray, positionsArray, equalsArray, clickedArray). Indica qué valores se seleccionan de un campo de selección múltiple del formulario elegido. - field: nombre del campo de selección múltiple. - position: posición relativa del campo entre aquellos que tengan el mismo nombre, comenzando por la posición 0. - valuesArray: lista de valores que han de seleccionarse en el campo. - positionsArray: lista que indica, para cada elemento de valuesArray, qué posición ocupa en caso de que haya valores replicados. - equalsArray: lista que indica, para cada elemento de valuesArray, si su valor ha de ser idéntico al que aparece en el campo de selección (equals = true) o estar contenido en él (equals = false). - clickedArray: lista que indica, para cada elemento de valuesArray, si puede estar marcado, no marcado, o de ambas maneras. Para ello hay unas constantes JavaScript definidas: • CLICKED_ELEMENT: marcar el elemento. Desarrollo de Wrappers ITPilot en JavaScript 29 ITPilot 4.0 o o o Guía del Desarrollador • NON_CLICKED_ELEMENT: dejar el elemento como no marcado. • CLICKED_AND_NON_CLICKED_ELEMENT: genera dos combinaciones, una con el elemento marcado, y otra con el elemento no marcado. selectPositions(field, position, positions). Indica qué valores se seleccionan de un campo de selección del formulario elegido. - field: nombre del campo HTML de selección. - position: posición que ocupa en caso de que haya más de un elemento del campo con el mismo nombre. - positions: valores de los elementos sobre los cuáles el componente ha de iterar. selectTexts(field, position, values, positions, equal). Indica qué valores hay que utilizar en las diferentes iteraciones sobre un campo de texto. - field: nombre del campo HTML de texto. - position: posición del campo en caso de que haya varios en el formulario con el mismo nombre. - values: lista de valores que han de seleccionarse en el campo. - positions: lista que indica, para cada elemento de values, qué posición ocupa en caso de que haya valores replicados. - equals: valor booleano que indica si los valores de los campos han de coincidir exactamente con los provistos por la función, o si pueden estar contenidos. click(field, value, state). Función que permite seleccionar un elemento y ejecutar un evento “click” sobre él. - field: nombre del campo HTML sobre el que realizar el click. - value: cuando esta función se ejecute sobre Radio Buttons, este parámetro indica qué elementos son seleccionados, como una lista (e.g. [0, 1]). Cuando se ejecuta sobre CheckBoxes, indica el valor del elemento seleccionable. - state: cuando esta función se ejecute sobre Radio Buttons, este parámetro no es utilizado. Cuando se ejecuta sobre CheckBoxes, indica el estado del elemento: Desarrollo de Wrappers ITPilot en JavaScript 30 ITPilot 4.0 o o Guía del Desarrollador • CLICKED_ELEMENT: marcar el elemento. • NON_CLICKED_ELEMENT: dejar el elemento como no marcado. • CLICKED_AND_NON_CLICKED_ELEMENT: genera dos combinaciones, una con el elemento marcado, y otra con el elemento no marcado. input(field, position, values). Función que indica qué valores se añaden en un campo input. - field: nombre del campo HTML de entrada. - position: posición del campo en caso de que haya varios en el formulario con el mismo nombre. - values: lista de valores que han de seleccionarse en el campo. textarea(field, position, values). Indica qué valores se añaden en un área de texto. - field: nombre del campo HTML de entrada. - position: posición del campo en caso de que haya varios en el formulario con el mismo nombre. - values: lista de valores que han de seleccionarse en el campo. o toList(). Devuelve una lista con las secuencias NSEQL utilizadas en cada iteración. o setMaxIterations(count). Define el número máximo de iteraciones que pueden ser ejecutadas. - o setRetries(count). Método de actualización del número de reintentos en caso de que haya fallos. - o count: número de reintentos. setRetryDelay(mseconds). Permite indicar el tiempo de espera entre reintentos. - o count: número que determina el número máximo de iteraciones. mseconds: indica el tiempo de espera entre reintentos, en milisegundos. setParallelIterator(flag). Indica si se desea que el componente lance las iteraciones en paralelo. Desarrollo de Wrappers ITPilot en JavaScript 31 ITPilot 4.0 - o Guía del Desarrollador flag: parámetro que indica si el componente lanza las iteraciones en paralelo (“true”) o no (“false”). next(inputPage). Devuelve la página resultado de ejecutar una iteración del componente. - inputPage: parámetro opcional, permite indicar una nueva página de partida sobre el cuál ejecutar una nueva iteración del componente. o hasNext(). Función que permite determinar si hay más resultados. La función devuelve “true” si hay al menos un resultado más, o “false” si no. o close(). Función que cierra el iterador. o syncWithPost(flag). Este método indica si para recuperar el estado de la página se ha de emitir un mensaje POST a la URL de la página con los parámetros de POST con los que se ha llegado a ella. Este es el método de sincronización por defecto. - o setBackSequence(back). Este método permite indicar opcionalmente una secuencia de navegación explícita a la página de la que proviene a partir de la cuál realizar más operaciones de extracción de información. - o back: programa NSEQL de vuelta atrás. setReusingConnection(reusingConnection): indica si se reutiliza o no la conexión. - o flag: “true” indica que se desea utilizar este método de sincronización. Si está a “false”, ITPilot comprueba si existe o no una secuencia de vuelta atrás, definida con el método setBackSequence; si no existe, se ejecuta un método NSEQL Back(). reusingConnection: si está a “true”, se reutiliza la conexión proveniente de componentes previos; con este parámetro a “false”, se abre un nuevo navegador, importando la información de sesión anterior. setBackPages(pages). Este método determina el número de páginas que ITPilot ha de volver hacia atrás, cuando ha de ejecutar el comando NSEQL Back() al no haberse determinado ninguna secuencia de vuelta atrás, ni haberse configurado la vuelta atrás como una navegación POST. Desarrollo de Wrappers ITPilot en JavaScript 32 ITPilot 4.0 4.3.14 Guía del Desarrollador Get Page • Objeto: Get_Page • Descripción: permite pedir al pool de navegadores un navegador activo a partir de un código de identificación obtenido anteriormente. • Funciones o Constructor(browserUuid): obtiene (u, opcionalmente, crea) el manejador de un navegador activo a partir de su identificador. - o browserUuid: identificador del navegador para obtener su manejador. exec(pageType, lastURL, lastURLMethod, lastURLPostParameters, cookie, proxyUser, proxyPassword, proxyDomain). Ejecuta el componente y devuelve un objeto Página con información sobre el estado del navegador. Es posible ejecutar la función sin parámetros, con lo que después puede realizar la navegación con un objeto Sequence (ver sección 4.3.26). - pageType: tipo de navegador utilizado para albergar la página: • SEQUENCE_IEBROWSER = 1 • SEQUENCE_HTTP_BROWSER = 2 - lastURL: última URL de la que proviene la página actual. - lastURLMethod: método de acceso (GET, POST) de la URL de la que proviene la página actual. - lastURLPostParameters: parámetros del método POST de la URL de la que proviene la página actual. - cookie: “cookies” de almacenamiento de información. - proxyUser: nombre de usuario de acceso al proxy, si es necesario. - proxyPassword: clave de usuario de acceso al proxy, si es necesario. - proxyDomain: dominio del proxy, si es necesario. Desarrollo de Wrappers ITPilot en JavaScript 33 ITPilot 4.0 4.3.15 Guía del Desarrollador Init • Objeto: Init • Descripción: se encarga de extraer información estructurada de una página HTML, generando por tanto un programa DEXTL ([DEXTL]). • Funciones: - - Constructor(input, output) input: registro de entrada del componente. De uso opcional, se utiliza cuando se crean componentes a medida (ver 4.4). En el caso de los procesos estándar, ITP recupera esta información del contexto JavaScript. output: nombre del registro de salida del componente, que representa los parámetros de consulta del “wrapper”. Su uso es opcional: en la función principal de los procesos estándar, si no se especifica se creará en el momento de ejecución del componente (función exec() ). get(name): devuelve el valor de un campo del registro que se está creando como conjunto de parámetros de inicialización. - name: nombre del campo del registro. setText(field, obl, fixedValue). Crea un campo de tipo texto en el registro de inicialización. field: nombre del campo a crear. obl: parámetro que indica la obligatoriedad de consulta sobre el campo a crear. Existen los posibles valores a utilizar: • OPTIONAL (valor por defecto): el parámetro es opcional, no requiere que se le asigne un valor en cada consulta al wrapper. • OBLIGATORY: el parámetro es obligatorio en cualquier consulta que se realice sobre el wrapper. • FIXED: el parámetro tiene un valor constante; este valor se asigna mediante el parámetro fixedValue, comentado a continuación. fixedValue: parámetro opcional que indica un valor constante asignado al campo. Desarrollo de Wrappers ITPilot en JavaScript 34 ITPilot 4.0 - setInt(field, obl, fixedValue). Crea un campo de tipo entero en el registro de inicialización. field: nombre del campo que crear. obl: parámetro que indica la obligatoriedad de consulta sobre el campo a crear. Existen los posibles valores a utilizar: - • OPTIONAL (valor por defecto): el parámetro es opcional, no requiere que se le asigne un valor en cada consulta al wrapper. • OBLIGATORY: el parámetro es obligatorio en cualquier consulta que se realice sobre el wrapper. • FIXED: el parámetro tiene un valor constante; este valor se asigna mediante el parámetro fixedValue, comentado a continuación. fixedValue: parámetro opcional que indica un valor constante asignado al campo. setLong(field, obl, fixedValue). Crea un campo de tipo long en el registro de inicialización. field: nombre del campo que crear. obl: parámetro que indica la obligatoriedad de consulta sobre el campo a crear. Existen los posibles valores a utilizar: - Guía del Desarrollador • OPTIONAL (valor por defecto): el parámetro es opcional, no requiere que se le asigne un valor en cada consulta al wrapper. • OBLIGATORY: el parámetro es obligatorio en cualquier consulta que se realice sobre el wrapper. • FIXED: el parámetro tiene un valor constante; este valor se asigna mediante el parámetro fixedValue, comentado a continuación. fixedValue: parámetro opcional que indica un valor constante asignado al campo. setFloat(field, obl, fixedValue). Crea un campo de tipo flotante en el registro de inicialización. field: nombre del campo que crear. obl: parámetro que indica la obligatoriedad de consulta sobre el campo a crear. Existen los posibles valores a utilizar: Desarrollo de Wrappers ITPilot en JavaScript 35 ITPilot 4.0 - • OPTIONAL (valor por defecto): el parámetro es opcional, no requiere que se le asigne un valor en cada consulta al wrapper. • OBLIGATORY: el parámetro es obligatorio en cualquier consulta que se realice sobre el wrapper. • FIXED: el parámetro tiene un valor constante; este valor se asigna mediante el parámetro fixedValue, comentado a continuación. fixedValue: parámetro opcional que indica un valor constante asignado al campo. setDouble(field, obl, fixedValue). Crea un campo de tipo double en el registro de inicialización. field: nombre del campo que crear. obl: parámetro que indica la obligatoriedad de consulta sobre el campo a crear. Existen los posibles valores a utilizar: - Guía del Desarrollador • OPTIONAL (valor por defecto): el parámetro es opcional, no requiere que se le asigne un valor en cada consulta al wrapper. • OBLIGATORY: el parámetro es obligatorio en cualquier consulta que se realice sobre el wrapper. • FIXED: el parámetro tiene un valor constante; este valor se asigna mediante el parámetro fixedValue, comentado a continuación. fixedValue: parámetro opcional que indica un valor constante asignado al campo. setBlob(field, obl, fixedValue). Crea un campo de tipo BLOB (binary large object) en el registro de inicialización. field: nombre del campo que crear. obl: parámetro que indica la obligatoriedad de consulta sobre el campo a crear. Existen los posibles valores a utilizar: • OPTIONAL (valor por defecto): el parámetro es opcional, no requiere que se le asigne un valor en cada consulta al wrapper. • OBLIGATORY: el parámetro es obligatorio en cualquier consulta que se realice sobre el wrapper. Desarrollo de Wrappers ITPilot en JavaScript 36 ITPilot 4.0 • - fixedValue: parámetro opcional que indica un valor constante asignado al campo. field: nombre del campo que crear. obl: parámetro que indica la obligatoriedad de consulta sobre el campo a crear. Existen los posibles valores a utilizar: • OPTIONAL (valor por defecto): el parámetro es opcional, no requiere que se le asigne un valor en cada consulta al wrapper. • OBLIGATORY: el parámetro es obligatorio en cualquier consulta que se realice sobre el wrapper. • FIXED: el parámetro tiene un valor constante; este valor se asigna mediante el parámetro fixedValue, comentado a continuación. fixedValue: parámetro opcional que indica un valor constante asignado al campo. setLink(field, obl, fixedValue). Crea un campo de tipo URL en el registro de inicialización. field: nombre del campo que crear. obl: parámetro que indica la obligatoriedad de consulta sobre el campo a crear. Existen los posibles valores a utilizar: - FIXED: el parámetro tiene un valor constante; este valor se asigna mediante el parámetro fixedValue, comentado a continuación. setBoolean(field, obl, fixedValue). Crea un campo de tipo boolean en el registro de inicialización. - Guía del Desarrollador • OPTIONAL (valor por defecto): el parámetro es opcional, no requiere que se le asigne un valor en cada consulta al wrapper. • OBLIGATORY: el parámetro es obligatorio en cualquier consulta que se realice sobre el wrapper. • FIXED: el parámetro tiene un valor constante; este valor se asigna mediante el parámetro fixedValue, comentado a continuación. fixedValue: parámetro opcional que indica un valor constante asignado al campo. setDate(field, format, obl, fixedValue). Crea un campo de tipo fecha en el registro de inicialización. Desarrollo de Wrappers ITPilot en JavaScript 37 ITPilot 4.0 field: nombre del campo que crear. format: formato de representación del campo fecha. Este formato es opcional, pero si se rellena es de cumplimiento obligatorio. En caso contrario, el wrapper no podrá ser ejecutado. Este formato de representación se define en [DATEFORMAT]. obl: parámetro que indica la obligatoriedad de consulta sobre el campo a crear. Existen los posibles valores a utilizar: - OPTIONAL (valor por defecto): el parámetro es opcional, no requiere que se le asigne un valor en cada consulta al wrapper. • OBLIGATORY: el parámetro es obligatorio en cualquier consulta que se realice sobre el wrapper. • FIXED: el parámetro tiene un valor constante; este valor se asigna mediante el parámetro fixedValue, comentado a continuación. fixedValue: parámetro opcional que indica un valor constante asignado al campo. name: nuevo nombre del componente. setI18n(i18n). Función de actualización de la internacionalización del proceso. - • setName(name). Función de actualización del nombre del componente. - Guía del Desarrollador i18n: tipo de internacionalización a utilizar. ITPilot provee diferentes tipos de internacionalización, como ES_EURO, US_PST, GB, etc. Ver [GENER] para más información acerca de la internacionalización en ITPilot. exec(). Función principal del componente que permite ejecutarlo, devolviendo un registro que representa los parámetros de inicialización del wrapper. Desarrollo de Wrappers ITPilot en JavaScript 38 ITPilot 4.0 4.3.16 Iterator • Objeto: Iterator • Descripción: componente que itera sobre una lista de registros, de uno en uno. • Funciones: o Constructor(list) • • Guía del Desarrollador list: lista de registros sobre los cuáles iterar. o hasNext(): determina si hay más resultados sobre los que iterar o no. Devuelve “true” si hay al menos un resultado más. o next(): devuelve el siguiente elemento de la iteración. La lista es una secuencia ordenada de registros. La opción “Parallel Execution” existente en la interfaz gráfica de ITPilot se convierte en la siguiente estructura JavaScript, que hace uso del objeto Thread, descrito en el apartado 4.3.28. Tabla 2: Utilización de Threads con el componente Iterator var _thread0 = new Thread(); while(iterator.hasNext()) { recordInstance = iterator.next(); _thread0.execute("_functionIterator_1", structureInstance, recordInstance); Desarrollo de Wrappers ITPilot en JavaScript 39 ITPilot 4.0 4.3.17 Guía del Desarrollador JDBCExtractor • Objeto: JDBCExtractor • Descripción: esta función permite enviar una consulta a cualquier fuente accesible vía JDBC, y devolver una lista de registros con los resultados obtenidos. • Funciones: o o Constructor (uuid, uri, driver, userName, password, structure, baseRecords, maxPoolSize, initialPoolSize, checkQuery, query) - uuid: identificador único del componente. - uri: el URL de conexión a la base de datos. - driver: la clase driver a utilizar para la conexión al origen de datos. - userName: el nombre del usuario a utilizar para el acceso. - password: la clave de acceso para el usuario utilizado. - structure: estructura de los registros de la lista de salida del componente. Se define como un registro de valores. - baseRecords: lista de registros que serán utilizados - maxPoolSize: número máximo de conexiones que puede gestionar el pool de conexiones al mismo tiempo. - initialPoolSize: número de conexiones con las que se desea inicializar el pool. Se establece y crea un número de conexiones en estado “idle” (ocioso), listas para ser usadas. - checkQuery: consulta SQL utilizada por el pool para verificar el estado de las conexiones que se encuentran cacheadas. Es preciso que la consulta sea sencilla y exista la tabla en cuestión - query: consulta SQL que devuelve los resultados requeridos por el componente. exec(query, baseRecords): ejecuta el componente JDBCExtractor. Desarrollo de Wrappers ITPilot en JavaScript 40 ITPilot 4.0 o Guía del Desarrollador - query: consulta SQL que devuelve los resultados requeridos por el componente. - baseRecords: lista de registros que serán utilizados. setPoolConfig(maxPoolSize, initialPoolSize, pingQuery): actualiza la configuración del pool. - maxPoolSize: número máximo de conexiones que puede gestionar el pool de conexiones al mismo tiempo. - initialPoolSize: número de conexiones con las que se desea inicializar el pool. Se establece y crea un número de conexiones en estado “idle” (ocioso), listas para ser usadas. - pingQuery: consulta SQL utilizada por el pool para verificar el estado de las conexiones que se encuentran cacheadas. Es preciso que la consulta sea sencilla y exista la tabla en cuestión o disablePool(): inhabilita el pool de conexiones. o addDriverProperty(propname, propvalue): añade una propiedad del driver JDBC - propname: nombre de la propiedad. - propvalue: valor de la propiedad. Desarrollo de Wrappers ITPilot en JavaScript 41 ITPilot 4.0 4.3.18 • Guía del Desarrollador Loop Descripción: permite realizar bucles en el flujo. El bucle se repetirá mientras se cumpla la condición dada (WHILE… DO). El componente loop se implementa en JavaScript mediante un bucle while, con un objeto Condition utilizado como condición de salida del bucle. El objeto Condition se define en el apartado 4.3.5. Tabla 3: Utilización del Loop var loop = null; loop = new Condition(<condición de salida>); loop.onError(RUNTIME_ERROR, ON_ERROR_RAISE); while(loop.exec([])) { <operaciones dentro del bucle> … } Desarrollo de Wrappers ITPilot en JavaScript 42 ITPilot 4.0 4.3.19 Guía del Desarrollador Next Interval Iterator • Objeto: Next_Interval_Iterator • Descripción: permite iterar por diferentes páginas relacionadas entre sí por una misma o diferentes secuencias de navegación. • Funciones: o o Constructor(sequences, iterations, sequenceType, reuse, inputPage) - sequences: lista de secuencias de navegación a utilizar. Si sólo hay una secuencia, intentará utilizarse en todas las iteraciones. Si hay más de una secuencia, se utilizará una en cada iteración. - iterations: se indica, para cada secuencia, el número de iteraciones a realizar; el tamaño de esta lista ha de ser igual al tamaño de la lista provista en el parámetro sequences. - sequenceType: tipo de acceso al recurso. Se permiten los siguientes valores: • SEQUENCE_IEBROWSER • SEQUENCE_HTTP_BROWSER • SEQUENCE_FTP • SEQUENCE_LOCAL - reuse: valor booleano que indica si se reutiliza el navegador utilizado hasta ese momento, o se lanza un nuevo navegador, manteniendo la información de sesión. - inputPage: indica la página a partir de la cuál se realiza la siguiente secuencia de navegación. next(inputRecords, inputPage). Devuelve el elemento de la siguiente iteración. - inputRecords: lista de registros de entrada que pueden utilizarse como parámetros dentro de las secuencias de navegación al siguiente intervalo. Desarrollo de Wrappers ITPilot en JavaScript 43 ITPilot 4.0 - Guía del Desarrollador inputPage: indica cuál es la página desde la que se va a acceder a las páginas siguientes. o close(). cierra el iterador. o setRetries(count). Configura el número de reintentos en caso de error de acceso a la siguiente página. - o setRetryDelay(count). Configura el intervalo entre reintento y reintento. - o back: programa NSEQL de vuelta atrás. setBackPages(pages). Este método determina el número de páginas que ITPilot ha de volver hacia atrás, cuando ha de ejecutar el comando NSEQL Back() al no haberse determinado ninguna secuencia de vuelta atrás, ni haberse configurado la vuelta atrás como una navegación POST. - o flag: “true” indica que se desea utilizar este método de sincronización. Si está a “false”, ITPilot comprueba si existe o no una secuencia de vuelta atrás, definida con el método setBackSequence; si no existe, se ejecuta un método NSEQL Back(). setBackSequence(back). Este método permite indicar opcionalmente una secuencia de navegación explícita a la página de la que proviene a partir de la cuál realizar más operaciones de extracción de información. - o count: intervalo en milisegundos. syncWithPost(flag). Este método indica si para recuperar el estado de la página se ha de emitir un mensaje POST a la URL de la página con los parámetros de POST con los que se ha llegado a ella. Este es el método de sincronización por defecto. - o count: número de reintentos. pages: número de páginas de vuelta atrás. setReusingConnection(reusingConnection): indica si se reutiliza o no la conexión. - reusingConnection: si está a “true”, se reutiliza la conexión proveniente de componentes previos; con este parámetro a “false”, se abre un nuevo navegador, importando la información de sesión anterior. Desarrollo de Wrappers ITPilot en JavaScript 44 ITPilot 4.0 4.3.20 Guía del Desarrollador Output • Objeto: Output • Descripción: coloca un registro en la salida del wrapper. • Funciones: o Constructor(structure) - o structure: parámetro que indica el registro de entrada del componente, que se desea utilizar como resultado del wrapper. add(record). Permite añadir posteriormente el registro de entrada del componente que se desea utilizar como resultado del wrapper. - record: registro a utilizar. Desarrollo de Wrappers ITPilot en JavaScript 45 ITPilot 4.0 4.3.21 Guía del Desarrollador Record Constructor • Objeto: Record_Constructor • Descripción: permite construir un registro a partir de otros registros generados en el flujo, además de generar nuevos atributos derivados de los ya existentes. • Funciones: o o o Constructor(recordsObj, name) - recordsObj: lista de elementos de entrada; cada elemento de la lista puede ser un registro o una lista de registros. - name: nombre del registro de salida del componente Record Constructor. add(fieldName, expression, errorAction). Método de adición de un nuevo campo al registro en construcción. - fieldname: nombre del campo. - expression: expresión de definición del campo. E.g. “$0.PARAM1” indice que el campo contendrá el campo PARAM1 del primer registro de entrada de la lista recordsObj introducida en el constructor.. - errorAction: acción a ejecutar en caso de que no se pueda evaluar correctamente la expresión. Los valores posibles son: • ON_ERROR_RAISE: parar la ejecución del wrapper, indicando la procedencia del error. • ON_ERROR_IGNORE: ignorar el error, continuando con la ejecución del wrapper. exec(). Ejecuta la instancia del componente Record Constructor, devolviendo un objeto que representa el registro obtenido. NOTA: En caso de que el manejador de error de este componente se encuentre configurado como ON_ERROR_IGNORE, RECORD CONSTRUCTOR devolverá un registro con los campos de salida, excepto aquellos que hayan provocado el error. Desarrollo de Wrappers ITPilot en JavaScript 46 ITPilot 4.0 4.3.22 Guía del Desarrollador Record Sequence • Objeto: Record_Sequence • Descripción: crea una secuencia de navegación creada a partir de los resultados de un registro. Permite crear secuencias de acceso a otras páginas a partir de las páginas procesadas por el componente Extractor. • Funciones: o Constructor(sequences, sequenceDepends, sequenceType, reuse, inputPage) - sequences: lista ordenada y secuencial de las secuencias de navegación NSEQL que serán utilizadas por el componente. - sequenceDepends: lista ordenada y secuencial de las etiquetas DEXTL asociadas a cada una de las secuencias de navegación NSEQL de la lista sequences. - sequenceType: tipo de pool a utilizar. Los valores posibles son: • SEQUENCE_IEBROWSER • SEQUENCE_HTTP_BROWSER • SEQUENCE_FTP • SEQUENCE_LOCAL - reuse: valor booleano que indica si se reutiliza el navegador utilizado hasta ese momento, o se lanza un nuevo navegador, manteniendo la información de sesión. Generalmente este valor estará a “true”, aunque en algunos casos puede no ser buena opción, generalmente si el iterador previo se ejecuta en paralelo. - inputPage: opcional, permite indicar una página de inicio. o exec(): devuelve un objeto página que representa la página objetivo de la/s secuencia/s de navegación. o Todos los métodos ofrecidos por el componente Sequence. Desarrollo de Wrappers ITPilot en JavaScript 47 ITPilot 4.0 4.3.23 Guía del Desarrollador Release Persistent Browser • Objeto: Release_Persistent_Browser • Descripción: toma como entrada un identificador de navegador o una página, y libera el navegador correspondiente. • Funciones: o Constructor(page): - o Constructor(browserUuid): - o page: página cargada en el navegador que se desea liberar. browserUuid: identificador de navegador. exec(): ejecuta el componente Desarrollo de Wrappers ITPilot en JavaScript 48 ITPilot 4.0 4.3.24 • Guía del Desarrollador Repeat Descripción: permite realizar bucles en el flujo. Repite el bucle hasta que se cumpla una condición dada (REPEAT… UNTIL). El componente Repeat se implementa en JavaScript mediante un bucle do… while, con un objeto Condition utilizado como condición de salida del bucle. El objeto Condition se define en el apartado 4.3.5. Tabla 4: Utilización del Repeat var repeat = null; repeat = new Condition(<condición de salida>); repeat.onError(RUNTIME_ERROR, ON_ERROR_RAISE); do { <operaciones dentro del bucle> … } while(repeat.exec([])); Desarrollo de Wrappers ITPilot en JavaScript 49 ITPilot 4.0 4.3.25 • Guía del Desarrollador Script Descripción: el componente permite escribir parte de la lógica de descripción de un wrapper ITPilot en Javascript. Este componente no tiene asociada ninguna función JavaScript concreta. Cuando se utiliza este componente desde la interfaz gráfica de generación, éste se convierte en una función javascript que se invoca desde el lugar que ocupe dentro del flujo del proceso. Desarrollo de Wrappers ITPilot en JavaScript 50 ITPilot 4.0 4.3.26 Guía del Desarrollador Sequence • Objeto: Sequence • Descripción: crea una secuencia de navegación en el lenguaje NSEQL (ver [NSEQL]). • Funciones: - - - Constructor(sequence, sequenceType, reusableConnection, inputPage) sequence: programa NSEQL de navegación (ver [NSEQL]). sequenceType: tipo de pool a utilizar. Los valores posibles son: • SEQUENCE_IEBROWSER • SEQUENCE_HTTP_BROWSER • SEQUENCE_FTP • SEQUENCE_LOCAL reusableConnection: indica si la conexión va a reutilizarse (“true”) o no (“false”). Ver [GENER] para más información. inputPage: parámetro opcional, indica la página de partida. Si no, se ejecuta directamente el programa NSEQL. exec(inputValues, inputPage). Ejecuta el componente Sequence, devolviendo la página final a la que la secuencia de navegación ha llegado. inputValues: lista de valores que pueden utilizarse como parámetros de entrada en la secuencia de navegación. inputPage: parámetro opcional, describe la página a partir de la cuál se ejecuta la secuencia de navegación del componente. setRetries(count). Método de actualización del número de reintentos en caso de que haya fallos. count: número de reintentos. Desarrollo de Wrappers ITPilot en JavaScript 51 ITPilot 4.0 - Guía del Desarrollador setRetryDelay(mseconds). Permite indicar el tiempo de espera entre reintentos. mseconds: indica el tiempo de espera entre reintentos, en milisegundos. - close(). Cierra la conexión con el navegador en marcha. - syncWithPost(flag). Este método indica si para recuperar el estado de la página se ha de emitir un mensaje POST a la URL de la página con los parámetros de POST con los que se ha llegado a ella. Este es el método de sincronización por defecto. - setBackSequence(back). Este método permite indicar opcionalmente una secuencia de navegación explícita a la página de la que proviene a partir de la cuál realizar más operaciones de extracción de información. - reusingConnection: si está a “true”, se reutiliza la conexión proveniente de componentes previos; con este parámetro a “false”, se abre un nuevo navegador, importando la información de sesión anterior. setBackPages(pages). Este método determina el número de páginas que ITPilot ha de volver hacia atrás, cuando ha de ejecutar el comando NSEQL Back() al no haberse determinado ninguna secuencia de vuelta atrás, ni haberse configurado la vuelta atrás como una navegación POST. - back: programa NSEQL de vuelta atrás. setReusingConnection(reusingConnection): indica si se reutiliza o no la conexión. - flag: “true” indica que se desea utilizar este método de sincronización. Si está a “false”, ITPilot comprueba si existe o no una secuencia de vuelta atrás, definida con el método setBackSequence; si no existe, se ejecuta un método NSEQL Back(). pages: número de páginas de vuelta atrás. toString(): devuelve la secuencia NSEQL (ver [NSEQL]) de la secuencia. Desarrollo de Wrappers ITPilot en JavaScript 52 ITPilot 4.0 4.3.27 Guía del Desarrollador Store File • Objeto: StoreFile • Descripción: almacena el contenido introducido como parámetro de entrada en un fichero. • Funciones: o Constructor(content, file) - content: valor de tipo cadena o binario que indica el contenido a almacenar. - file: ruta y nombre del fichero donde se almacenará el contenido. o exec(). Ejecuta el componente. o setRetries(count). Método de actualización del número de reintentos en caso de que haya fallos. - o count: número de reintentos. setRetryDelay(mseconds). Permite indicar el tiempo de espera entre reintentos. - mseconds: indica el tiempo de espera entre reintentos, en milisegundos. Desarrollo de Wrappers ITPilot en JavaScript 53 ITPilot 4.0 4.3.28 Guía del Desarrollador Thread • Objeto: Thread • Descripción: representa un Thread en el wrapper de ITPilot. Se suele utilizar cuando se desea que el procesamiento posterior sobre cada uno los registros obtenidos en una operación de extracción se realice concurrentemente. • Funciones: o wait((): provoca que el thread entre en estado de espera, hasta que terminen todas las ejecuciones invocadas con la función execute. o execute(functionName, <lista de argumentos>): lanza el hilo de ejecución sobre la función descrita. o - functionName: nombre de la función JavaScript a ejecutar. - <lista de argumentos>: lista de argumentos separados por comas, que han de coincidir con los argumentos de la función JavaScript. setMaxConcurrentThreads(int): permite configurar el número máximo de instancias Thread que serán utilizadas en paralelo. Peticiones posteriores serán encoladas a la espera de que terminen las ejecuciones en marcha. - int: número máximo Desarrollo de Wrappers ITPilot en JavaScript 54 ITPilot 4.0 4.4 Guía del Desarrollador COMPONENTES A MEDIDA EN WRAPPERS JAVASCRIPT 4.4.1 Desarrollo de Componentes a Medida Los componentes a medida pueden desarrollarse gráficamente mediante la herramienta de generación de wrappers (ver [GENER]), pero también se pueden desarrollar en JavaScript. Para ello, han de crearse un fichero con sufijo .js, que se habrá de almacenar en el directorio <DENODO_HOME>/metadata/itp-custom-components, con las siguientes funciones: • mycustom_main(mycustom_input) { var mycustom_output = null; … return mycustom_output; } o • mycustom_getInputStructure() { … } o • Esta es la function principal, donde “mycustom” es el nombre del componente a medida. Esta función permite definir el esquema de entrada mycustom_getOutputType() { return <TYPE> } o Esta es la function que define el tipo de salida del componente. Los tipos posibles son: - LIST_TYPE = 1 - PAGE_TYPE = 2 - RECORD_TYPE - SIMPLE_TYPE = 4 - ARRAY_TYPE = 5 - BINARY_TYPE = 6 - BOOLEAN_TYPE = 7 - DATE_TYPE = 8 - DOUBLE_TYPE = 9 - FLOAT_TYPE = 10 Desarrollo de Wrappers ITPilot en JavaScript = 3 55 ITPilot 4.0 • INT_TYPE = 11 - LONG_TYPE = 12 - STRING_TYPE = 13 - URL_TYPE = 14 mycustom_getOutputStructure) { … } o 4.4.2 - Guía del Desarrollador Esta función es la que se encarga de definir qué estructura de salida va a ser devuelta por el componente. Sólo es necesario si el tipo de salida definido por la función myCustom_getOutputType es un registro (RECORD_TYPE) o una lista (LIST_TYPE). Utilización de Componentes a Medida Si se desea utilizar algún componente a medida que haya sido generado mediante la herramienta de generación de ITPilot (ver [GENER] para una explicación detallada acerca de cómo generar componentes a medida), se tienen que realizar los siguientes pasos: 1. Los componentes a medida se almacenan en formato JavaScript (con extensión .js) en el directorio <DENODO_HOME>/metadata/itp-custom-components . Cada componente se representa como un fichero js cuyo nombre coincide con el nombre del componente a medida. 2. La función principal del componente a medida es <componente>_main(elementoDeEntrada), donde <componente> es el nombre del componente a medida, tal y como se ha definido en el apartado anterior. 4.5 DESARROLLO DE WRAPPERS Una vez desarrollado el script, la creación de un wrapper es muy simple, ya que sólo hay que escribir la sentencia VQL (ver [VQL]) de la forma: CREATE WRAPPER ITP <name> [MAINTENANCE FALSE] 'jscode' donde jscode es el código JavaScript recientemente generado. NOTA: La sintaxis VQL utiliza comillas simples para delimitar el código JavaScript, por lo que, si internamente también se utilizasen las comillas, habría que escaparlas con el carácter ‘\’. Desarrollo de Wrappers ITPilot en JavaScript 56 ITPilot 4.0 Guía del Desarrollador BIBLIOGRAFÍA [AXIS] Apache Axis Web Server. http://ws.apache.org/axis/ [DATEFORMAT] Formato Java de representación de formatos de fecha. http://java.sun.com/j2se/1.5.0/docs/api/java/text/SimpleDateFormat.html [DEXTL] Manual de DEXTL. Denodo Technologies, 2007. [DOTNET] Microsoft .NET Framework, http://www.microsoft.com/net/ [DPORT] Guía del Administrador de Virtual DataPort. Denodo Technologies, 2007. [ECMA262] Standard ECMA-262. ECMAScript Language Specification, 3.0. [GENER] Manual del Entorno de Generación de ITPilot. Denodo Technologies, 2007. [NSEQL] Manual de NSEQL (Navigation SEQuence Language). Denodo Technologies, 2007. [PERL] Lenguaje PERL de programación dinámica. http://www.perl.com [USER] Manual de usuario de ITPilot. Denodo Technologies, 2007. [JDOC] Documentación Javadoc del API del Desarrollador. [SOAP] SOAP Version 1.2. W3C Recommendation. http://www.w3.org/TR/soap/ [VQL] Guía Avanzada de VQL de Denodo Virtual DataPort 4.0. Denodo Technologies 2007. [WSDL] Web Services Description Language (WSDL) 1.1. W3C Note, http://www.w3.org/TR/wsdl Bibliografía 57