Download Kosmo Desktop – Manual de desarrollo

Kosmo Desktop – Manual de desarrollo
Instalación y configuración del código fuente de
Kosmo en Eclipse
Versión 3.0
02/12/2010
Kosmo Desktop – Manual de desarrollo |
2
Kosmo Desktop – Manual de desarrollo |
3
1 Control de versiones
VERSIÓN
AUTOR
FECHA
CAMBIO
1.0
SAIG, S.L.
22/03/2007
Versión Inicial
2.0
SAIG, S.L.
19/02/2008
Actualización del manual
3.0
SAIG, S.L.
02/12/2010
Incluidas nuevas entradas en el apartado de FAQ
Índice de contenido
1Control de versiones............................................................................................................................. 3
2Introducción......................................................................................................................................... 5
3Instalación y configuración de Java y Eclipse........................................................................................ 6
3.1Instalación de Java y JAI................................................................................................................ 6
3.2Instalación de Eclipse................................................................................................................... 6
4Creación del workspace........................................................................................................................ 8
4.1Descarga del código fuente de Kosmo Desktop............................................................................ 8
4.2Creación de la carpeta de trabajo (workspace) en Eclipse............................................................9
4.3Primeros pasos en Eclipse........................................................................................................... 10
5Creación de los proyectos................................................................................................................... 12
5.1Pasos previos.............................................................................................................................. 12
5.2Configuración de las bibliotecas................................................................................................. 13
5.3Configuración del build path....................................................................................................... 18
5.3.1Directorios de fuentes y salida............................................................................................ 18
5.3.2Nivel de compatibilidad con versiones anteriores...............................................................18
5.4Creación del proyecto “saig-core”.............................................................................................. 20
5.5Creación de la configuración de inicio......................................................................................... 27
5.6Iniciar la ejecución...................................................................................................................... 33
5.7Creación de los proyectos correspondientes a las extensiones...................................................34
6FAQ..................................................................................................................................................... 36
Kosmo Desktop – Manual de desarrollo |
4
Índice de imágenes
Imagen 1: Contenido del fichero zip de Eclipse....................................................................................... 7
Imagen 2: Contenido del fichero zip de distribución del código fuente de Kosmo Desktop.....................8
Imagen 3: Eclipse - Selección del directorio de trabajo........................................................................... 9
Imagen 4: Eclipse - Pantalla de bienvenida........................................................................................... 10
Imagen 5: Eclipse - Perspectiva Java..................................................................................................... 10
Imagen 6: Eclipse - Abrir perspectiva.................................................................................................... 11
Imagen 7: Eclipse - Cambiar de perspectiva......................................................................................... 11
Imagen 8: Distribución de directorios en la carpeta de trabajo de Eclipse............................................12
Imagen 9: Eclipse - Configurar bibliotecas de usuario - Windows > Preferences...................................13
Imagen 10: Eclipse - Configurar bibliotecas de usuario - Nueva biblioteca de usuario..........................14
Imagen 11: Eclipse - Configurar bibliotecas de usuario - Configurar nombre de la biblioteca...............14
Imagen 12: Eclipse - Configurar bibliotecas de usuario - Biblioteca de usuario KOSMO_LIBS................15
Imagen 13: Eclipse - Configurar bibliotecas de usuario - Bibliotecas añadidas a la biblioteca de usuario
KOSMO_LIBS......................................................................................................................................... 16
Imagen 14: Eclipse - Configuración de la biblioteca de usuario EXTENSION_LIBS.................................17
Imagen 15: Eclipse - Configuración del Build Path................................................................................ 18
Imagen 16: Eclipse - Preferencias - Nivel de compatibilidad.................................................................19
Imagen 17: Eclipse - Nuevo proyecto Java............................................................................................ 20
Imagen 18: Eclipse - Crear proyecto saig-core...................................................................................... 21
Imagen 19: Eclipse - Configuración del proyecto saig-core - Pestaña src..............................................22
Imagen 20: Eclipse - Configuración del proyecto saig-core - Pestaña Libraries.....................................23
Imagen 21: Eclipse - Configuración del proyecto saig-core - Pestaña Order and Export........................25
Imagen 22: Eclipse - Configuración del proyecto saig-core - Generando clases....................................26
Imagen 23: Eclipse - Configuración del proyecto saig-core - Proyecto saig-core generado...................26
Imagen 24: Eclipse - Creación de la configuración de inicio..................................................................27
Imagen 25: Eclipse - Creación de la configuración de inicio - Nueva aplicación Java.............................28
Imagen 26: Eclipse - Creación de la configuración de inicio - Nueva aplicación Java.............................29
Imagen 27: Eclipse - Creación de la configuración de inicio - Pestaña Arguments................................30
Imagen 28: Eclipse - Creación de la configuración de inicio - Pestaña Environment.............................31
Imagen 29: Eclipse - Creación de la configuración de inicio - Editar variable de entorno......................31
Imagen 30: Eclipse - Creación de la configuración de inicio - Variable PATH.........................................32
Imagen 31: FAQ - Mostrar salida en consola - Archivo log4j.properties.................................................36
Imagen 32: FAQ - Eclipse - Configuración de la memoria de inicio........................................................37
Imagen 33: FAQ - Eclipse - Parámetro Xmx........................................................................................... 37
Imagen 34: FAQ - Eclipse - Aumentar la memoria de inicio de Kosmo Desktop.....................................38
Kosmo Desktop – Manual de desarrollo |
5
2 Introducción
A lo largo de este documento vamos a explicar qué pasos debemos seguir para poder generar
Kosmo Desktop – Sistema Abierto de Información Geográfica a partir de su código fuente.
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 para su configuración.
Los pasos que vamos a mostrar se harán sobre la plataforma Windows: en Linux se deberían
seguir unos pasos similares.
Kosmo Desktop – Manual de desarrollo |
6
3 Instalación y configuración de Java y Eclipse
3.1 Instalación de Java y JAI
Para poder compilar el código fuente de Kosmo es necesario tener instalada una máquina virtual
de Java en el equipo. Debido al uso de determinadas estructuras de Java, es necesario usar al menos
una versión de Java 1.6.X.
Para desarrollar es aconsejable descargar el JDK de la versión que queramos usar, ya que esto
nos permitirá posteriormente acceder a las clases nativas de Java desde Eclipse cuando estemos en
una sesión de depuración.
Podemos descargar la última versión de Java 1.6 en la dirección:
http://java.sun.com/javase/downloads/index.jsp
Además de la máquina virtual, es necesario instalar JAI para que Kosmo pueda iniciarse. Para ello
tenemos que instalar la versión correspondiente a la plataforma y al tipo de distribución de Java que
vayamos a usar (JDK o JRE). En ambos casos, podemos descargar la última versión estable de JAI
desde la página:
https://jai.dev.java.net/binary-builds.html
Debemos instalar la versión de JAI sobre la máquina virtual que después usaremos para
desarrollar.
3.2 Instalación de Eclipse
Como ya hemos comentado anteriormente, vamos a usar Eclipse como entorno de desarrollo en
este manual.
Para descargar Eclipse, podemos acceder a la siguiente dirección:
http://www.eclipse.org/downloads/
De aquí podemos descargar la última versión estable del Eclipse SDK, que actualmente es la
3.6.X, seleccionando qué plataforma queremos.
Para instalar Eclipse, basta descomprimir el archivo zip correspondiente en la ruta deseada. Esto
creará la estructura de directorios necesaria para poder lanzar Eclipse:
Kosmo Desktop – Manual de desarrollo |
Imagen 1: Contenido del fichero zip de Eclipse
Para iniciar Eclipse, basta con hacer doble click sobre el archivo eclipse.exe.
7
Kosmo Desktop – Manual de desarrollo |
8
4 Creación del workspace
A lo largo de este punto vamos a ver cómo tenemos que crear la carpeta de trabajo de Eclipse y
cómo deben crearse los proyectos correspondientes.
4.1 Descarga del código fuente de Kosmo Desktop
Para descargar la última versión de los fuentes de Kosmo Desktop podemos visitar la sección de
Descargas > Código fuente en la dirección de la página del proyecto Kosmo – La Plataforma SIG Libre
Corporativa:
http://www.opengis.es
El código fuente de Kosmo Desktop está distribuido en directorios para facilitar al desarrollador su
incorporación a la carpeta de trabajo. Una vez descomprimido el archivo zip, obtendremos una
estructura de directorios similar a la siguiente:
Imagen 2: Contenido del fichero zip de distribución del código fuente de Kosmo
Desktop
Podemos observar que el directorio contiene once directorios. Los directorios principales son:
•
saig-core
Contiene las clases correspondientes al núcleo de Kosmo Desktop.
•
docs
Contiene el conjunto de manuales sobre el desarrollo en Kosmo Desktop.
•
libs
Kosmo Desktop – Manual de desarrollo |
9
Contiene tanto los ficheros jar de las bibliotecas necesarias para poder compilar Kosmo
Desktop como las dlls/.so necesarias para el acceso a imágenes.
El resto de directorios corresponde cada uno a las extensiones disponibles de Kosmo Desktop.
4.2 Creación de la carpeta de trabajo (workspace) en Eclipse
Cuando iniciamos por primera vez Eclipse, nos preguntará qué directorio queremos usar como
carpeta de trabajo.
Imagen 3: Eclipse - Selección del directorio de trabajo
Seleccionamos la ruta deseada, marcamos la opción “Use this as the default and not ask me
again” (Usar por defecto y no volver a preguntar) y pulsamos el botón Aceptar. De esta forma, cuando
iniciemos de nuevo Eclipse, no nos volverá a preguntar cuál es la carpeta de trabajo.
Kosmo Desktop – Manual de desarrollo |
4.3 Primeros pasos en Eclipse
Una vez creada la carpeta de trabajo, Eclipse nos muestra la ventana de bienvenida:
Imagen 4: Eclipse - Pantalla de bienvenida
Cerramos la ventana y aparecerá la perspectiva Java, que es la que se abre por defecto:
Imagen 5: Eclipse - Perspectiva Java
10
Kosmo Desktop – Manual de desarrollo |
11
Una perspectiva es una distribución particular de las diferentes vistas que nos proporciona
Eclipse. Las perspectivas habituales son tres:
•
•
•
Java -> es la inicial y normalmente será la que se use.
Java Browsing -> muy parecida a la Java, con diferente distribución de las vistas.
Debug -> es la que usaremos habitualmente para realizar sesiones de depuración del código
Para cambiar de una perspectiva a otra usamos la opción del menú Window > Open perspective,
donde aparecerán las perspectivas por defecto (y otras que podemos configurar igualmente):
Imagen 6: Eclipse - Abrir perspectiva
Podemos cambiar de una perspectiva a otra usando la marca existente en la parte superior
derecha de la pantalla:
Imagen 7: Eclipse - Cambiar de perspectiva
Kosmo Desktop – Manual de desarrollo |
12
5 Creación de los proyectos
A lo largo de este apartado vamos a ver cómo crear cada uno de los proyectos en Eclipse a partir
del código fuente de Kosmo Desktop. Vamos a suponer que nuestro entorno de trabajo va a ser
C:\workspace para los ejemplos, pero podemos usar la ruta que queramos para ello.
5.1 Pasos previos
Antes de empezar a crear los proyectos, vamos a trasladar los fuentes de Kosmo Desktop a
nuestra carpeta de trabajo.
Para ello copiamos las carpetas saig-core, libs y cada uno de los directorios correspondientes a
las extensiones de la ubicación donde habíamos descomprimido el archivo de fuentes a la carpeta de
trabajo solicitada. Para nuestro ejemplo el directorio de trabajo quedaría como sigue:
Imagen 8: Distribución de directorios en la carpeta de trabajo de Eclipse
Además de estas carpetas, vamos a crearnos un nuevo directorio extensiones que es donde
vamos a ir añadiendo los jars correspondientes a las extensiones de Kosmo Desktop.
Kosmo Desktop – Manual de desarrollo |
13
5.2 Configuración de las bibliotecas
Antes de empezar a crear los proyectos, vamos a crear una biblioteca de usuario que va a
englobar todas las bibliotecas que necesita Kosmo para su compilación (KOSMO_LIBS) y otra que
englobará el conjunto de bibliotecas de usuario usadas en las extensiones (EXTENSION_LIBS).
Para ello debemos seguir los siguientes pasos:
1.
Seleccionamos el menú Windows > Preferences...
Imagen 9: Eclipse - Configurar bibliotecas de usuario - Windows >
Preferences
Kosmo Desktop – Manual de desarrollo |
2.
14
Seleccionamos la opción Java > Build Path > User Libraries y creamos una nueva
biblioteca de usuario (User Library).
Imagen 10: Eclipse - Configurar bibliotecas de usuario - Nueva biblioteca de usuario
3.
Pulsamos el botón New y creamos una nueva biblioteca con el nombre KOSMO_LIBS.
Pulsamos el botón Ok.
Imagen 11: Eclipse - Configurar bibliotecas de
usuario - Configurar nombre de la biblioteca
Kosmo Desktop – Manual de desarrollo |
15
Imagen 12: Eclipse - Configurar bibliotecas de usuario - Biblioteca de usuario
KOSMO_LIBS
4.
Una vez creada, pulsamos el botón Add Jars y seleccionamos todos los jars existentes en
el directorio libs que viene incluido junto con las fuentes de Kosmo Desktop. Aparecerán
añadidas todas las bibliotecas dentro de la biblioteca de usuario:
Kosmo Desktop – Manual de desarrollo |
16
Imagen 13: Eclipse - Configurar bibliotecas de usuario - Bibliotecas añadidas a la
biblioteca de usuario KOSMO_LIBS
5.
Pulsamos el botón Ok del diálogo de preferencias y ya hemos creado nuestra biblioteca
de usuario KOSMO_LIBS.
6.
De forma similar, creamos la biblioteca EXTENSION_LIBS añadiendo las bibliotecas que
están incluidas en el directorio libs\ext:
Kosmo Desktop – Manual de desarrollo |
Imagen 14: Eclipse - Configuración de la biblioteca de usuario EXTENSION_LIBS
17
Kosmo Desktop – Manual de desarrollo |
18
5.3 Configuración del build path
En este punto vamos a modificar algunos parámetros que vienen por defecto en Eclipse, para
adaptarlos a nuestras necesidades:
5.3.1 Directorios de fuentes y salida
En la opción Windows > Preferences..., marcamos la opción Java > Build path y seleccionamos la
opción Source and output folders > Folders:
Imagen 15: Eclipse - Configuración del Build Path
5.3.2 Nivel de compatibilidad con versiones anteriores
En esta ocasión no se va a mantener compatibilidades con versiones anteriores, por lo que se
dejará la compatibilidad en 6.0.
Kosmo Desktop – Manual de desarrollo |
Imagen 16: Eclipse - Preferencias - Nivel de compatibilidad
19
Kosmo Desktop – Manual de desarrollo |
20
5.4 Creación del proyecto “saig-core”
Vamos a crear en primer lugar el proyecto del núcleo de Kosmo Desktop: el proyecto saig-core.
Los pasos que debemos seguir para crear este proyecto son los siguientes:
1.
Creamos un nuevo proyecto con la opción del menú File > New...> Java Project:
Imagen 17: Eclipse - Nuevo proyecto Java
2.
Establecemos como nombre del proyecto saig-core y marcamos la opción Create project
from existing source. Pulsamos el botón Browse... y seleccionamos el directorio saig-core
en el diálogo que nos aparece:
Kosmo Desktop – Manual de desarrollo |
21
Imagen 18: Eclipse - Crear proyecto saig-core
3.
En la pestaña “Sources” podemos observar que se han añadido automáticamente los
fuentes existentes en la carpeta saig-core. Comprobamos que el directorio de salida es el
directorio \bin y que la opción Allow output folders for source folders está desmarcada:
Kosmo Desktop – Manual de desarrollo |
22
Imagen 19: Eclipse - Configuración del proyecto saig-core - Pestaña src
4.
En la pestaña “Libraries” (Bibliotecas) vamos a añadir la biblioteca de usuario
KOSMO_LIBS que ya habíamos configurado previamente. Para ello pulsamos el botón Add
Library..., seleccionamos la opción User Library y marcamos la biblioteca KOSMO_LIBS:
Kosmo Desktop – Manual de desarrollo |
Imagen 20: Eclipse - Configuración del proyecto saig-core - Pestaña
Libraries
23
Kosmo Desktop – Manual de desarrollo |
24
Kosmo Desktop – Manual de desarrollo |
5.
25
Por último, vamos a configurar la pestaña “Order and Export”. Marcamos la biblioteca
KOSMO_LIBS para que esté disponible para el resto de proyectos:
Imagen 21: Eclipse - Configuración del proyecto saig-core - Pestaña Order
and Export
6.
Una vez configurado el proyecto, pulsamos el botón Finish para que se añada al
workspace. Automáticamente comenzará a compilar el proyecto (lo indica en la parte
inferior derecha de la pantalla, con el mensaje Building workspace...)
Kosmo Desktop – Manual de desarrollo |
Imagen 22: Eclipse - Configuración del proyecto saig-core - Generando clases
Imagen 23: Eclipse - Configuración del proyecto saig-core - Proyecto saig-core
generado
26
Kosmo Desktop – Manual de desarrollo |
27
5.5 Creación de la configuración de inicio
Para poder iniciar Kosmo, tanto en modo normal o en modo depuración, necesitamos crear una
nueva configuración de inicio.
Para ello debemos seguir los pasos que se detallan a continuación:
1.
Abrimos el diálogo Run mediante la opción Run > Open Run Dialog ...
Imagen 24: Eclipse - Creación de la configuración de inicio
2.
Seleccionamos la opción Java Application, pulsamos con el botón derecho del ratón y
seleccionamos la opción New para crear una nueva configuración:
Kosmo Desktop – Manual de desarrollo |
28
Imagen 25: Eclipse - Creación de la configuración de inicio - Nueva aplicación Java
3.
En la pestaña “Main”, pulsamos el botón Search y seleccionamos como clase principal de
la aplicación la clase com.vividsolutions.jump.workbench.JUMPWorkbench:
Kosmo Desktop – Manual de desarrollo |
29
Imagen 26: Eclipse - Creación de la configuración de inicio - Nueva aplicación Java
4.
En la pestaña “Arguments” vamos a configurar tanto los argumentos del programa como
los argumentos que le pasamos a la máquina virtual.
Dentro de los argumentos del programa (Program arguments), le indicamos en qué
directorio puede encontrar las extensiones del mismo. En nuestro ejemplo, tendríamos
que escribir lo siguiente:
-plug-in-directory "C:\workspace\extensiones"
Dentro de los argumentos para la máquina virtual (VM arguments), situaremos el
parámetro
de memoria -Xmx y el directorio donde puede encontrar las bibliotecas
para la carga de ficheros de imagen.
En nuestro caso, vamos a colocar el valor de memoria a 800 Mb y el directorio para las
bibliotecas de imágenes será “C:\workspace\libs\dlls”. En total quedaría como sigue:
-Xmx800M -Djava.library.path="C:\workspace\libs\dlls"
Kosmo Desktop – Manual de desarrollo |
30
Imagen 27: Eclipse - Creación de la configuración de inicio - Pestaña Arguments
5.
En la pestaña Enviroment vamos a configurar la variable PATH para que Kosmo Desktop
sea capaz de encontrar las bibliotecas de imágenes de forma correcta:
Kosmo Desktop – Manual de desarrollo |
Imagen 28: Eclipse - Creación de la configuración de inicio - Pestaña Environment
Imagen 29: Eclipse - Creación de la configuración de inicio Editar variable de entorno
31
Kosmo Desktop – Manual de desarrollo |
Imagen 30: Eclipse - Creación de la configuración de inicio - Variable PATH
Para el caso de Linux, la variable que hay que configurar es LD_LIBRARY_PATH:
32
Kosmo Desktop – Manual de desarrollo |
6.
33
Pulsamos el botón Apply (Aplicar) para guardar los cambios y, si queremos iniciar Kosmo
Desktop, el botón Run. Si queremos guardar sin iniciar la ejecución pulsamos el botón
Close.
5.6 Iniciar la ejecución
Una vez configurado nuestro proyecto, podemos iniciar la ejecución del programa en dos modos:
1.
Modo normal
Nos permite ejecutar el programa ignorando cualquier configuración de depuración
establecida:
2.
Modo depuración
Nos permite ejecutar el programa con puntos de interrupción, para poder depurar el
código del mismo:
Kosmo Desktop – Manual de desarrollo |
34
5.7 Creación de los proyectos correspondientes a las extensiones
El proceso de creación de los proyectos para cada una de las extensiones incluidas en Kosmo
Desktop es similar al que ya hemos visto para el proyecto saig-core. En este caso, es necesario
modificar la pestaña Projects dentro del diálogo New Java Project para añadir el proyecto saig-core:
1.
Pulsamos el botón Add...
2.
Seleccionamos el proyecto saig-core y pulsamos el botón Ok.
Kosmo Desktop – Manual de desarrollo |
35
3.
El proyecto saig-core forma a partir de ahora parte de las clases de nuestro nuevo
proyecto.
4.
Añadimos la biblioteca de usuario EXTENSION_LIBS como biblioteca en la pestaña
Libraries.
Puesto que hemos configurado previamente el proyecto saig-core para que ofreciera las
bibliotecas KOSMO_LIBS a otros proyectos, no es necesario añadirlas de nuevo al proyecto de
cada extensión.
Kosmo Desktop – Manual de desarrollo |
36
6 FAQ
1. Cuando inicio la ejecución de Kosmo Desktop, no me aparece ningún mensaje en la pestaña
“Console”, que es donde deben aparecer los mensajes de información y/o error.
Por defecto, el fichero de configuración de los mensajes de error hace que sólo se escriban en
un fichero kosmo.log dentro del directorio /logs del proyecto saig-core (de ahí que crearamos
dicho directorio en un punto anterior). Si queremos que se muestren los mensajes en
pantalla, en la pestaña “Console”, debemos modificar el fichero log4j.properties de modo que
incluya la categoría stdout:
Imagen 31: FAQ - Mostrar salida en consola - Archivo log4j.properties
2. Cuando inicio la aplicación me aparece el mensaje siguiente:
log4j:ERROR setFile(null,true) call failed
java.io.FileNotFoundException: logs\kosmo.log (El sistema no puede
hallar la ruta especificada)
Este problema se muestra cuando Kosmo Desktop no es capa de encontrar el directorio /log
donde escribir el fichero correspondiente. Asegúrese de que ha creado el directorio /log
dentro del directorio del proyecto saig-core.
Kosmo Desktop – Manual de desarrollo |
37
3. Tengo memoria disponible en el equipo y quiero iniciar Eclipse con más memoria
Para modificar la memoria con la que se inicia Eclipse debemos editar el fichero eclipse.ini
que está situado en el directorio de instalación de Eclipse y modificar el valor del parámetro
Xmx hasta alcanzar la memoria deseada:
Imagen 32: FAQ - Eclipse - Configuración de la memoria de inicio
Imagen 33: FAQ - Eclipse - Parámetro
Xmx
Kosmo Desktop – Manual de desarrollo |
38
4. Tengo memoria disponible en el equipo y quiero iniciar Kosmo Desktop con más memoria
Para iniciar Kosmo con más memoria modificamos el parámetro correspondiente en la
pestaña Arguments de la configuración de inicio:
Imagen 34: FAQ - Eclipse - Aumentar la memoria de inicio de Kosmo Desktop
5. Al iniciar Kosmo me indica que no es capaz de encontrar la clase Crs
Hay que comprobar que el directorio crs existe en el directorio del proyecto que estamos
ejecutando. A su vez la pestaña Environment tiene configurada la variable PATH (o
LD_LIBRARY_PATH para Linux) correctamente y que en la pestaña Arguments, entrada VM
arguments, también está correctamente configurado el directorio.
6. Al generar las clases, Eclipse me da indica que no es capaz de encontrar la clase
javax.media.jai.util.Range
En este caso, la máquina virtual de Java que hemos configurado para generar las clases no
tiene instalado JAI. Revise la configuración de su JRE/JDK de desarrollo y compruebe que ha
instalado en el mismo la versión de JAI correspondiente al tipo de máquina virtual y su
sistema operativo.
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