Manual de desarrolloManual de desarrollo

Generación de extensiones en Kosmo

Versión 1.024/02/08

KOSMO | 2

0. Control de versiones

VERSIÓN AUTOR FECHA CAMBIO

1.0 SAIG, S.L. 24/02/08 Versión Inicial

Índice de contenido0.Control de versiones............................................................................................................................21.Introducción........................................................................................................................................3

1.1Extensiones y herramientas..........................................................................................................32.Instalación y configuración de Java y Eclipse.......................................................................................43.Extensión “¡Hola mundo!”...................................................................................................................5

3.1Generación del proyecto...............................................................................................................53.2Creación de las clases asociadas a la extensión.........................................................................11

3.2.1Generando el esqueleto de la clase HelloWorldExtension...................................................113.2.2Desarrollando la clase HelloWorldExtension........................................................................153.2.3Generando el esqueleto de la clase HelloWorldPlugIn.........................................................183.2.4Completando la clase HelloWorldPlugIn..............................................................................203.2.5Completando la clase HelloWorldExtension.........................................................................23

3.3Generación de la configuración de inicio.....................................................................................243.4Probando la extensión en Eclipse................................................................................................273.5Generando el fichero Jar de la extensión.....................................................................................283.6Cargando la nueva extensión en Kosmo.....................................................................................33

4.Funcionalidades adicionales para la generación de extensiones........................................................344.1Añadir una herramienta como opción de menú principal............................................................34

KOSMO | 3

1. Introducció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 Extensiones y herramientas

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-in-directory 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)

KOSMO | 4

2. Instalación y configuración de Java y Eclipse

En el documento “Manual para el desarrollador de Kosmo” (disponible para su descarga en la página web de SAIG, http://www.saig.es/descargas/descargas.php, 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.

KOSMO | 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

KOSMO | 6

2. 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

KOSMO | 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

KOSMO | 8

4. 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

KOSMO | 9

Imagen 5: Nuevo proyecto Java - Seleccionar proyecto base

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

KOSMO | 10

5. 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:

6. Por último, debemos copiar el directorio crs desde el proyecto saig-core al nuevo proyecto.

Imagen 7: Nuevo proyecto Java - Proyecto helloWorldExtension creado

KOSMO | 11

3.2 Creación de las clases asociadas a la extensión

3.2.1 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

KOSMO | 12

Imagen 9: Eclipse - Configurar nuevo paquete

KOSMO | 13

2. 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

KOSMO | 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:

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 12: Nueva clase Java - Seleccionar clase padre

Imagen 13: Nueva clase Java - Clase HelloWorldExtension

KOSMO | 15

3.2.2 Desarrollando la clase HelloWorldExtension

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()

KOSMO | 16

2. 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()

KOSMO | 17

3. 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:

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.

Imagen 16: HelloWorldExtension - Método getDescription()

KOSMO | 18

3.2.3 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:

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 17: Nueva clase Java - Crear la clase HelloWorldPlugIn

Imagen 18: Nueva clase Java - Seleccionar la interfaz PlugIn

KOSMO | 19

3. 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

KOSMO | 20

3.2.4 Completando la clase HelloWorldPlugIn

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:

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:

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.).

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:

Imagen 20: HelloWorldPlugIn - Método initialize()

Imagen 21: HelloWorldPlugIn - Método execute()

Imagen 22: HelloWorldPlugIn - Método finish()

KOSMO | 21

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!”:

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):

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:

La clase quedaría definitivamente como sigue:

Imagen 23: HelloWorldPlugIn - Método getCheck()

Imagen 24: HelloWorldPlugIn - Método getName()

Imagen 25: HelloWorldPlugIn - Métodos getIcon() / getDisabledIcon()

Imagen 26: HelloWorldPlugIn - extends AbstractPlugIn

KOSMO | 22

Imagen 27: HelloWorldPlugIn – Código definitivo

KOSMO | 23

3.2.5 Completando la clase HelloWorldExtension

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:

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 28: HelloWorldExtension - Método install()

Imagen 29: HelloWorldExtension - Método uninstall

KOSMO | 24

3.3 Generación de la configuració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:

El fichero debe situarse en la raíz del proyecto helloWorldExtension, junto a las carpetas src y bin:

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:

Imagen 30: Contenido del fichero workbench-properties.xml

Imagen 31: Fichero workbench-properties.xml - Contenido del directorio helloWorldExtension

KOSMO | 25

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

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

KOSMO | 26

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

KOSMO | 27

3.4 Probando la extensión en Eclipse

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:

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:

Si pulsamos el botón aparecerá el diálogo de información que hemos preparado:

Imagen 35: Ejecutar la configuración de inicio del proyecto helloWorldExtension

Imagen 36: Botón de la herramienta "¡Hola mundo!"

Imagen 37: Diálogo de información de la herramienta ¡Hola mundo!

KOSMO | 28

3.5 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... :

Seleccionamos como tipo de exportación el fichero JAR (JAR file):

Imagen 38: Generar fichero JAR - Iniciar asistente de exportación

KOSMO | 29

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):

Imagen 39: Generar fichero JAR - Seleccionar tipo de exportación

KOSMO | 30

Imagen 40: Generar fichero JAR - Configurar ficheros a añadir

Imagen 41: Generar fichero JAR - Opciones del fichero JAR

KOSMO | 31

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:

Para regenerar el fichero, pulsamos sobre el nuevo fichero con el botón derecho y seleccionamos la opción Create JAR:

Imagen 42: Generar fichero JAR - Seleccionar especificación del fichero Manifest

Imagen 43: Generar fichero JAR - Fichero jardesc

KOSMO | 32

Imagen 44: Generar fichero JAR - Regenerar fichero JAR

KOSMO | 33

3.6 Cargando la nueva extensión en Kosmo

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:

Marcamos la nueva extensión y nos aparecerá el nuevo botón en la barra de herramientas:

Imagen 45: Cargar extensión en Kosmo - Abrir el Gestor de extensiones

Imagen 46: Cargar extensión en Kosmo - Activar la extensión ¡Hola mundo!

KOSMO | 34

4. Funcionalidades adicionales para la generación de extensiones

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:

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 48: Menú Mis Extensiones - Herramienta ¡Hola Mundo!

Imagen 47: Añadir herramienta al menú "Mis Extensiones"

Imagen 49: Añadir herramienta al menú "Herramientas"

KOSMO | 35

Si queremos que se incluya en el menú “Herramientas > Otros” el código sería el siguiente:

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 51: Añadir herramienta al menú Herramientas > Otros

Imagen 52: Menú Herramientas > Otras - Herramienta ¡Hola mundo!

Imagen 50: Menú Herramientas - Herramienta ¡Hola mundo!

Imagen 53: Eliminar herramienta del menú

http://www.saig.es

Email: info@saig.es

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