Download Kosmo Desktop

Manual de desarrollo
Generación de extensiones en Kosmo
Versión 1.0
24/02/08
KOSMO
|
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............................................................................................................................2
1.Introducción........................................................................................................................................3
1.1Extensiones y herramientas..........................................................................................................3
2.Instalación y configuración de Java y Eclipse.......................................................................................4
3.Extensión “¡Hola mundo!”...................................................................................................................5
3.1Generación del proyecto...............................................................................................................5
3.2Creación de las clases asociadas a la extensión.........................................................................11
3.2.1Generando el esqueleto de la clase HelloWorldExtension...................................................11
3.2.2Desarrollando la clase HelloWorldExtension........................................................................15
3.2.3Generando el esqueleto de la clase HelloWorldPlugIn.........................................................18
3.2.4Completando la clase HelloWorldPlugIn..............................................................................20
3.2.5Completando la clase HelloWorldExtension.........................................................................23
3.3Generación de la configuración de inicio.....................................................................................24
3.4Probando la extensión en Eclipse................................................................................................27
3.5Generando el fichero Jar de la extensión.....................................................................................28
3.6Cargando la nueva extensión en Kosmo.....................................................................................33
4.Funcionalidades adicionales para la generación de extensiones........................................................34
4.1Añadir una herramienta como opción de menú principal............................................................34
KOSMO
|
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)
KOSMO
|
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, 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
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
KOSMO
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
KOSMO
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
KOSMO
Imagen 5: Nuevo proyecto Java - Seleccionar
proyecto base
Imagen 6: Nuevo proyecto Java - Añadido proyecto base saig-core
|
9
KOSMO
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.
KOSMO
|
11
3.2 Crea ción de las cla se s aso ci ad a s 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
Imagen 9: Eclipse - Configurar nuevo paquete
|
12
KOSMO
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
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:
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
KOSMO
3.2.2
|
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()
KOSMO
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()
KOSMO
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.
KOSMO
3.2.3
|
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
KOSMO
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
KOSMO
3.2.4
|
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:
KOSMO
|
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:
KOSMO
Imagen 27: HelloWorldPlugIn – Código definitivo
|
22
KOSMO
3.2.5
|
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
KOSMO
|
24
3.3 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:
KOSMO
Imagen 32: Configuración de inicio - Pestaña Main
Imagen 33: Configuración de inicio - Pestaña Arguments
|
25
KOSMO
Imagen 34: Configuración de inicio - Pestaña Enviroment
|
26
KOSMO
|
27
3.4 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!
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... :
Imagen 38: Generar fichero JAR - Iniciar asistente de exportación
Seleccionamos como tipo de exportación el fichero JAR (JAR file):
KOSMO
|
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):
KOSMO
Imagen 40: Generar fichero JAR - Configurar ficheros a añadir
Imagen 41: Generar fichero JAR - Opciones del fichero JAR
|
30
KOSMO
|
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:
KOSMO
Imagen 44: Generar fichero JAR - Regenerar fichero JAR
|
32
KOSMO
|
33
3.6 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!
KOSMO
|
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"
KOSMO
|
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ú
http://www.saig.es
Email: [email protected]
Avenida República Argentina 28. Edificio Domocenter. Oficinas 6 y 7, 2ª planta.
41930, Bormujos – Sevilla – España