Manual de desarrollo

Transcripción

1 Manual de desarrollo Generación de extensiones en Kosmo Versión /02/08

2 2 0. Control de versione s VERSIÓN AUTOR FECHA CAMBIO 1.0 SAIG, S.L. 24/02/08 Versión Inicial Índice de contenido 0.Control de versiones Introducción Extensiones y herramientas Instalación y configuración de Java y Eclipse Extensión Hola mundo! Generación del proyecto Creación de las clases asociadas a la extensión Generando el esqueleto de la clase HelloWorldExtension Desarrollando la clase HelloWorldExtension Generando el esqueleto de la clase HelloWorldPlugIn Completando la clase HelloWorldPlugIn Completando la clase HelloWorldExtension Generación de la configuración de inicio Probando la extensión en Eclipse Generando el fichero Jar de la extensión Cargando la nueva extensión en Kosmo Funcionalidades adicionales para la generación de extensiones Añadir una herramienta como opción de menú principal...34

3 3 1. Introduc ción A lo largo de este documento vamos a explicar qué pasos debemos seguir para crear nuevas extensiones para Kosmo Cliente de escritorio. Como entorno de desarrollo recomendamos el uso de Eclipse. Será este el entorno que usaremos a lo largo de este manual, pero existen otros entornos de desarrollo que pueden usarse y que habría que seguir unos pasos parecidos. Los pasos que vamos a mostrar se harán en la plataforma Windows. En Linux se deberían seguir unos pasos similares. 1.1 Extensione s y herramienta s Una extensión es una colección de clases y recursos asociados que permite añadir a Kosmo nuevas funcionalidades. Las extensiones se distribuyen empaquetadas en ficheros JAR. Desde la perspectiva del usuario, extender Kosmo es tan fácil como copiar el fichero JAR de la nueva extensión al directorio de extensiones de Kosmo (que viene indicado como parámetro -plug-indirectory en la invocación de la aplicación). Al iniciarse Kosmo buscará dentro de los ficheros JAR incluidos en dicho directorio aquellas clases que hereden de Extension y ejecutará de forma automática el método install de cada una de ellas. Normalmente una extensión añadirá a Kosmo tanto plugins (herramientas que se activan como elementos de menús y botones de la barra de herramientas y que ejecutan una acción) como cursor tools (herramientas que activan un cursor con una funcionalidad asociada). También es posible añadir desde una extensión otros elementos tales como orígenes de datos (ver como ejemplo la extensión Origen de datos CSV incluida en la distribución de Kosmo) o barras de herramientas flotantes (ver como ejemplo la extensión Herramientas CAD incluida en la distribución de Kosmo)

4 4 2. Instala ción y configuración de Java y Eclip se En el documento Manual para el desarrollador de Kosmo (disponible para su descarga en la página web de SAIG, así como en la distribución del código fuente) están descritos los pasos necesarios para configurar el entorno de desarrollo Eclipse y la máquina virtual de Java, necesarios para poder seguir este manual para el desarrollo de extensiones. En este documento vamos a suponer que ambos se encuentran correctamente instalados y configurados, y que el proyecto saig-core ya ha sido creado y configurado.

5 5 3. Extensión Hola mundo! Vamos a comenzar creando una extensión sencilla: va a consistir en un una extensión que va a añadir un botón a la barra de herramientas principal que al pulsarlo muestre al usuario un diálogo con el mensaje Hola mundo! : 3.1 Generación del proyecto El primer paso que debemos realizar es la creación del proyecto donde vamos a incluir las clases correspondientes a la extensión que queremos generar. Para ello debemos seguir los pasos que se detallan a continuación: 1. Creamos un nuevo proyecto Java con la opción File > New > Java Project Imagen 1: Nuevo proyecto Java - Crear nuevo proyecto Java

6 2. 6 Como nombre del proyecto escribimos helloworldextension. Dejamos las opciones por defecto marcadas (Create new project in the workspace, Use default JRE y Create separate folders for sources and class files) y pulsamos el botón Next > (Siguiente): Imagen 2: Nuevo proyecto Java - Configuración de las propiedades del proyecto

7 3. En la pestaña Sources podemos observar que se ha creado una nueva carpeta src: Imagen 3: Nuevo proyecto Java - Pestaña Sources 7

8 4. 8 En la pestaña Projects vamos a indicar qué proyectos va a usar este nuevo proyecto para su generación. En nuestro caso, vamos a añadir el proyecto saig-core como base: Imagen 4: Nuevo proyecto Java - Pestaña Projects

9 Imagen 5: Nuevo proyecto Java - Seleccionar proyecto base Imagen 6: Nuevo proyecto Java - Añadido proyecto base saig-core 9

10 5. 10 Para terminar de crear el nuevo proyecto, pulsamos el botón Finish. El nuevo proyecto aparecerá añadido en la lista de proyectos de Eclipse: Imagen 7: Nuevo proyecto Java - Proyecto helloworldextension creado 6. Por último, debemos copiar el directorio crs desde el proyecto saig-core al nuevo proyecto.

11 Crea ción de las cla se s aso ci ad a s a la extensión Generando el esqueleto de la clase HelloWorldExtension El siguiente paso a la hora de crear nuestra extensión es generar la clase que va a usar Kosmo para cargar nuestra herramienta. Esta clase deberá heredar de la clase Extension y tendrá que implementar los métodos correspondientes que indican qué herramienta/s deben cargarse y cómo (método install) y cómo eliminar dichas herramientas de la aplicación (método uninstall). Veamos paso a paso como crear el esqueleto de esta clase: 1. Creamos un nuevo paquete org.saig.jump.plugin.helloworld dentro del proyecto helloworldextension que será donde incluiremos las clases que vayamos generando: Imagen 8: Eclipse - Crear nuevo paquete

12 Imagen 9: Eclipse - Configurar nuevo paquete 12

13 2. 13 Creamos una nueva clase dentro de dicho paquete que heredará de la clase Extension. Se denominará HelloWorldExtension : Imagen 10: Eclipse - Crear nueva clase Imagen 11: Nueva clase Java - Crear clase HelloWorldExtension

14 14 Para configurar de qué clase hereda nuestra nueva clase, pulsamos el botón Browse... que está junto a la entrada Superclass y seleccionamos la clase Extension correspondiente al paquete com.vividsolutions.jump.workbench.plugin: Imagen 12: Nueva clase Java - Seleccionar clase padre 3. Pulsamos el botón Finish y se creará la nueva clase dentro del paquete correspondiente. Se abrirá también una nueva pestaña de edición con el contenido de la clase. Por defecto aparecerán los métodos install y uninstall implementados, pero sin ningún código: Imagen 13: Nueva clase Java - Clase HelloWorldExtension

15 Desarrollando la clase HelloWorldE xten sion A partir del esqueleto que hemos generado en el punto anterior, vamos a completar un poco más la clase HelloWorldExtension, incluyendo la información asociada a la misma: nombre, versión y descripción. 1. Nombre de la extensión Por defecto, el nombre que se muestra en el Gestor de extensiones es Hello World. Vamos a sobreescribir el método getname() para que devuelva un nombre más adecuado: Imagen 14: HelloWorldExtension - Método getname()

16 2. 16 Versión de la extensión La versión de la extensión se muestra a continuación del nombre de la misma. Vamos a sobreescribir el método getversion() para que devuelva una identificación para la versión de la extensión: Imagen 15: HelloWorldExtension - Método getversion()

17 3. 17 Descripción de la extensión En el diálogo correspondiente al Gestor de extensiones se muestra una descripción al usuario detallada sobre la extensión. Vamos a sobreescribir el método getdescription() para que muestre algo más de información a nuestro usuario: Imagen 16: HelloWorldExtension - Método getdescription() De este modo la clase HelloWorldExtension nos queda completa a falta de los métodos install y uninstall. Los veremos justo después de crear el plugin que va a mostrar el diálogo.

18 Generando el esqueleto de la clase HelloWorldPlugIn Nuestro siguiente paso va a consistir en generar el esqueleto para la clase HelloWorldPlugIn, nuestra herramienta. Vamos a crear una nueva clase dentro del paquete org.saig.jump.plugin.helloworld denominada HelloWorldPlugIn que va a implementar la interfaz PlugIn: 1. Creamos la nueva clase HelloWorldPlugIn con el asistente para generar una nueva clase: Imagen 17: Nueva clase Java - Crear la clase HelloWorldPlugIn 2. Para que implemente la interfaz PlugIn, pulsamos el botón Add... situado junto al cuadro Interfaces y seleccionamos la clase PlugIn correspondiente al paquete com.vividsolutions.jump.workbench.plugin: Imagen 18: Nueva clase Java - Seleccionar la interfaz PlugIn

19 3. 19 Pulsamos el botón Finish y obtenemos la nueva clase con los métodos de la interfaz implementados, pero sin completar: Imagen 19: Nueva clase Java - Esqueleto de la clase HelloWorldPlugIn

20 Completando la clase HelloWorldPlugI n En este apartado vamos a completar los métodos de la clase HelloWorldPlugIn. Son los siguientes: 1. public void initialize ( PlugInContext context) throws Exception Este método es el que se llama al inicializar la herramienta. Es el encargado de realizar las tareas de inicialización previas a cualquier ejecución de la herramienta. En nuestra extensión vamos a hacer que al inicializarse la herramienta se añada de forma automática a la barra de herramientas principal como un nuevo botón: Imagen 20: HelloWorldPlugIn - Método initialize() 2. public boolean execute (PlugInContext context) throws Exception Este método se llama al pulsar sobre el botón de la barra de herramientas. En nuestra extensión vamos a hacer que al ejecutarse la herramienta se muestre el mensaje Hola mundo! como un diálogo de información en pantalla cuyo título será Diálogo de información. Para ello vamos a usar la clase DialogFactory, que ofrece una serie de métodos para la generación de ventanas: Imagen 21: HelloWorldPlugIn - Método execute() 3. public void finish (PlugInContext context) Este método se llama cuando se desea desintalar la herramienta. Es el encargado de realizar las tareas de finalización de la herramienta (liberación de recursos, eliminación de los botones de la interfaz, etc.). Imagen 22: HelloWorldPlugIn - Método finish() 4. public EnableCheck getcheck() Este método devuelve el conjunto de comprobaciones (checks) que deben cumplirse para que la herramienta (en este caso, su botón) esté activa. Para nuestro ejemplo vamos a hacer que la herramienta esté sólo activa si existe una ventana de tareas activa:

21 21 Imagen 23: HelloWorldPlugIn - Método getcheck() 5. public String getname() Este método devuelve el nombre asociado al botón de la herramienta. Este nombre se mostrará al usuario al posicionar el cursor sobre el botón. Para nuestro ejemplo vamos a devolver la cadena Hola mundo! : Imagen 24: HelloWorldPlugIn - Método getname() 6. public Icon geticon() / public Icon getdisabledicon() Estos dos métodos devuelven el icono que se muestra en el botón de la herramienta cuando está activa / inactiva, respectivamente. Para nuestro ejemplo vamos a usar el icono Attribute.gif existente en el directorio de imágenes e iconos de Kosmo (paquete com.vividsolutions.jump.workbench.ui.images): Imagen 25: HelloWorldPlugIn - Métodos geticon() / getdisabledicon() Por último, vamos a cambiar la cabecera de la clase para que en vez de implementar directamente la interfaz PlugIn extienda la clase AbstractPlugIn (que a su vez implementa PlugIn), ya que esta nos proporciona una serie de métodos adicionales de interés: Imagen 26: HelloWorldPlugIn - extends AbstractPlugIn La clase quedaría definitivamente como sigue:

22 Imagen 27: HelloWorldPlugIn Código definitivo 22

23 Completando la clase HelloWorldE xten sion Una vez ya tenemos terminada la clase HelloWorldPlugIn correspondiente a nuestra herramienta, ya podemos completar a su vez la clase correspondiente a la extensión. Para terminar la clase nos faltaba completar los métodos install y uninstall: 1. Método install El método install es el encargado de instanciar nuestra herramienta e invocar a su método initialize(). El método se invoca de manera automática al marcar como activa la extensión en el Gestor de extensiones. El método para nuestra extensión sería el siguiente: Imagen 28: HelloWorldExtension - Método install() 2. Método uninstall El método uninstall es el encargado de eliminar las herramientas de la interfaz de Kosmo. Para ello invocará el método finish() de nuestra herramienta. El método uninstall se invoca automáticamente al desmarcar la extensión en el Gestor de extensiones. El método para nuestra extensión sería el siguiente: Imagen 29: HelloWorldExtension - Método uninstall

24 Generación de la configura ción de inicio Para poder probar nuestra nueva extensión tenemos varias posibilidades: 1. Generar un fichero JAR que contenga las dos clases que hemos creado (HelloWorldExtension y HelloWorldPlugIn) y copiar este JAR al directorio de extensiones configurado en la configuración de inicio para el proyecto saig-core. 2. Generar un fichero workbench-properties.xml en el directorio del proyecto helloworldextension y modificar la configuración de inicio para que haga uso del mismo. Vamos a usar la segunda opción para desarrollar, ya que es la más cómoda a la hora de poder depurar el código de la misma. En un punto posterior veremos como generar el fichero JAR definitivo usando el asistente de Eclipse correspondiente para ello. El contenido del fichero workbench-properties.xml sería el siguiente: Imagen 30: Contenido del fichero workbench-properties.xml El fichero debe situarse en la raíz del proyecto helloworldextension, junto a las carpetas src y bin: Imagen 31: Fichero workbench-properties.xml - Contenido del directorio helloworldextension La generación de la configuración de inicio para un proyecto de Kosmo ya está comentada en un punto dentro del documento Manual para el desarrollador de Kosmo y no vamos a volver a explicarlo en detalle en este documento. Destacamos a continuación las pestañas que deben modificarse:

25 Imagen 32: Configuración de inicio - Pestaña Main Imagen 33: Configuración de inicio - Pestaña Arguments 25

26 Imagen 34: Configuración de inicio - Pestaña Enviroment 26

27 Probando la extensión en Eclip se Si hemos seguido todos los pasos descritos hasta el momento, ya tenemos todo listo para probar la extensión que hemos creado. Para lanzar el programa ejecutamos la configuración de inicio que hemos preparado: Imagen 35: Ejecutar la configuración de inicio del proyecto helloworldextension Una vez iniciado el programa, creamos un proyecto con una vista vacía y seleccionamos el sistema de referencia espacial de la nueva vista. Podemos observar en la parte derecha de la barra de herramientas principal el botón correspondiente a la nueva herramienta: Imagen 36: Botón de la herramienta " Hola mundo!" Si pulsamos el botón aparecerá el diálogo de información que hemos preparado: Imagen 37: Diálogo de información de la herramienta Hola mundo!

28 Generando el fichero Jar de la extensión Eclipse nos ofrece un asistente para exportar el proyecto como un fichero JAR. Para iniciar el asistente pulsamos con el botón derecho sobre el proyecto helloworldextension y seleccionamos la opción Export... : Imagen 38: Generar fichero JAR - Iniciar asistente de exportación Seleccionamos como tipo de exportación el fichero JAR (JAR file):

29 29 Imagen 39: Generar fichero JAR - Seleccionar tipo de exportación Seleccionamos únicamente las dos clases HelloWorldExtension y HelloWorldPlugIn del proyecto y configuramos que se debe escribir la extensión en el directorio de extensiones (en esta ocasión, D:\extensiones):

30 Imagen 40: Generar fichero JAR - Configurar ficheros a añadir Imagen 41: Generar fichero JAR - Opciones del fichero JAR 30

31 31 Imagen 42: Generar fichero JAR - Seleccionar especificación del fichero Manifest Una vez hayamos creado el fichero JAR, aparecerá un nuevo fichero de extensión jardesc en el proyecto que nos permitirá regenerar el fichero JAR con dos clicks de ratón: Imagen 43: Generar fichero JAR - Fichero jardesc Para regenerar el fichero, pulsamos sobre el nuevo fichero con el botón derecho y seleccionamos la opción Create JAR:

32 Imagen 44: Generar fichero JAR - Regenerar fichero JAR 32

33 Cargando la nueva extensión en Ko s m o Para cargar la nueva extensión en Kosmo, copiamos el fichero JAR que hemos generado al directorio de extensiones de Kosmo, iniciamos el programa y abrimos el Gestor de extensiones: Imagen 45: Cargar extensión en Kosmo - Abrir el Gestor de extensiones Marcamos la nueva extensión y nos aparecerá el nuevo botón en la barra de herramientas: Imagen 46: Cargar extensión en Kosmo - Activar la extensión Hola mundo!

34 34 4. Funcionalidade s adicionale s para la generación de extensione s En este apartado vamos a destacar alguna de las funcionalidades que nos ofrece la API de Kosmo a la hora de generar nuestras propias extensiones que no hemos visto ya en puntos anteriores. 4.1 Añadir una herramienta como opción de menú principal Si queremos añadir nuestra herramienta como una opción de los menús de la parte superior de la aplicación debemos modificar el método initialize() del mismo. Por ejemplo, si queremos añadir la herramienta a un nuevo menú denominado Mis Extensiones debemos modificar el método initialize() para que quede de la siguiente forma: Imagen 47: Añadir herramienta al menú "Mis Extensiones" Imagen 48: Menú Mis Extensiones - Herramienta Hola Mundo! La clase com.vividsolutions.jump.workbench.ui.mainmenunames nos ofrece como constantes los nombres de los menús que vienen por defecto ya creados en Kosmo. Por ejemplo, si queremos añadir nuestra herramienta al menú Herramientas, debemos modificar el código anterior para que quede de la siguiente manera: Imagen 49: Añadir herramienta al menú "Herramientas"

35 35 Imagen 50: Menú Herramientas - Herramienta Hola mundo! Si queremos que se incluya en el menú Herramientas > Otros el código sería el siguiente: Imagen 51: Añadir herramienta al menú Herramientas > Otros Imagen 52: Menú Herramientas > Otras - Herramienta Hola mundo! Para cualquiera de los tres casos que hemos visto es necesario también cambiar el método finish de la clase HelloWorldPlugIn para que se elimine de la interfaz correctamente: Imagen 53: Eliminar herramienta del menú

36 Avenida República Argentina 28. Edificio Domocenter. Oficinas 6 y 7, 2ª planta , Bormujos Sevilla España