Kosmo Desktop Manual de desarrollo Instalación y configuración del código fuente de Kosmo en Eclipse

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

2

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

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

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.

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:

Imagen 1: Contenido del fichero zip de Eclipse Para iniciar Eclipse, basta con hacer doble click sobre el archivo eclipse.exe. 7

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

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.

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

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

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.

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

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

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:

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:

Imagen 14: Eclipse - Configuración de la biblioteca de usuario EXTENSION_LIBS 17

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.

Imagen 16: Eclipse - Preferencias - Nivel de compatibilidad 19

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:

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:

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:

Imagen 20: Eclipse - Configuración del proyecto saig-core - Pestaña Libraries 23

24

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

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

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:

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:

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"

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:

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

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

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:

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.

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.

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.

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

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