svn-gvsig-desktop / tags / v1_11_0_Build_1305 / docs / Andami developer guide.html @ 44114
History | View | Annotate | Download (16.6 KB)
| 1 |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|---|---|
| 2 |
<html>
|
| 3 |
<head>
|
| 4 |
<meta content="text/html; charset=ISO-8859-1" |
| 5 |
http-equiv="content-type"> |
| 6 |
<title>Andami developer guide</title> |
| 7 |
<link href="style.css" rel="stylesheet" type="text/css"> |
| 8 |
</head>
|
| 9 |
<body>
|
| 10 |
<table width="90%" border="0"> |
| 11 |
<tr>
|
| 12 |
<td class="Nivel2"><a href="#Introduccion"><strong><font color="#FFFFFF">Introducción</font></strong></a></td> |
| 13 |
</tr>
|
| 14 |
<tr>
|
| 15 |
<td class="Nivel2"><a href="#Creacion_de_plugins"><font color="#FFFFFF"><strong>Creación |
| 16 |
de plugins</strong></font></a></td> |
| 17 |
</tr>
|
| 18 |
<tr>
|
| 19 |
<td class="Nivel2"><a href="#Funcionamiento_del_class_loader"><strong><font color="#FFFFFF">Funcionamiento |
| 20 |
del class loader</font></strong></a></td> |
| 21 |
</tr>
|
| 22 |
<tr>
|
| 23 |
<td class="Nivel2"><a href="#Servicios_a_los_plugins"><font color="#FFFFFF"><strong>Servicios |
| 24 |
a los plugins</strong></font></a></td> |
| 25 |
</tr>
|
| 26 |
<tr>
|
| 27 |
<td><strong> <a |
| 28 |
href="#Ejecucion_en_segundo_plano">Ejecución en segundo plano</a></strong></td> |
| 29 |
</tr>
|
| 30 |
<tr>
|
| 31 |
<td><strong> <a href="#Acceso_a_las_extensiones">Acceso |
| 32 |
a las extensiones</a></strong></td> |
| 33 |
</tr>
|
| 34 |
<tr>
|
| 35 |
<td class="urbanismo"><strong> <a href="#Persistencia_de_los_plugins">Persistencia |
| 36 |
de los plugins</a></strong></td> |
| 37 |
</tr>
|
| 38 |
<tr>
|
| 39 |
<td><strong> <a href="#popupmenus">Pop-up menus</a></strong></td> |
| 40 |
</tr>
|
| 41 |
<tr>
|
| 42 |
<td><strong> <a href="#Vistas">Vistas</a></strong></td> |
| 43 |
</tr>
|
| 44 |
<tr>
|
| 45 |
<td> <a href="#SingletonView">SingletonView's</a></td> |
| 46 |
</tr>
|
| 47 |
</table>
|
| 48 |
|
| 49 |
|
| 50 |
|
| 51 |
<p> <strong><font size="+1"><a name="Introduccion"></a>Introducción</font></strong></p> |
| 52 |
<p> Andami es un framework orientado a plugins construido sobre |
| 53 |
swing que permite la construcción de forma rápida y extensible |
| 54 |
de aplicaciones MDI (Multiple Document Interface). Tiene ya implementadas muchas |
| 55 |
de las funcionalidades requeridas para este tipo de aplicaciones tales como |
| 56 |
un menú Ventana, en la que van apareciendo las ventanas que se abren,
|
| 57 |
soporte para el traducciones, configuración personalizada para cada usuario,
|
| 58 |
actualizaciones automáticas, tanto del propio Andami como de los plugins,
|
| 59 |
persistencia del tamaño y posición de la ventana, del idioma, |
| 60 |
distintos tipos de vista, con la finalidad de facilitar la programación
|
| 61 |
de ventanas especiales, ... Todo esto además de tener ya solventados
|
| 62 |
los problemas típicos de la programación de un entorno como éste |
| 63 |
que no son pocos.<br>
|
| 64 |
<br>
|
| 65 |
Además, Andami está diseñada de forma |
| 66 |
que la propia lógica MDI puede ser reemplazada. Si en lugar de una aplicación |
| 67 |
estilo arcView, se quiere que cada vista que se añada, se haga en una
|
| 68 |
ventana de windows nueva (de las que aparecen en la barra de estado) o una vista |
| 69 |
como la de Eclipse, no hay más que desarrollar el plugin adecuado.<br> |
| 70 |
<br>
|
| 71 |
Andami está diseñada para ser amistosa con |
| 72 |
el usuario y para ello incorpora la posibilidad de añadir tooltips y
|
| 73 |
enabletexts a los botones. El tooltip es el texto que aparece cuando el ratón
|
| 74 |
se detiene sobre un botón o menú. El enableText es el texto que |
| 75 |
aparece en el caso anterior cuando el botón está desactivado, |
| 76 |
permitiendo mostrar al usuario qué es lo que debe hacer para que dicho
|
| 77 |
botón se active (o cualquier otro mensaje).<br> |
| 78 |
<br>
|
| 79 |
Por último, Andami tiene una gestión de errores |
| 80 |
que agradará a cualquier programador, ya que en casos de errores graves,
|
| 81 |
el propio framework avisa de dicho fallo y aconseja al usuario salvar los cambios |
| 82 |
y reiniciar el programa, a parte de que toda excepción no capturada por
|
| 83 |
el usuario se redirige a un fichero de log configurable en el que se escribirá
|
| 84 |
su traza.<br>
|
| 85 |
</p>
|
| 86 |
<p> <strong><font size="+1"><a name="Creacion_de_plugins"></a>Creación |
| 87 |
de plugins</font></strong></p> |
| 88 |
<p> Andami gira en torno al concepto de plugin. Andami mantiene |
| 89 |
un directorio como directorio de los plugins, que se puede cambiar en cualquier |
| 90 |
momento. Un plugin viene definido por la existencia de un subdirectorio dentro |
| 91 |
del directorio de los plugins, siendo el nombre del plugin el nombre de dicho |
| 92 |
directorio. Dentro de dicho directorio debe haber un fichero config.xml en el |
| 93 |
que se configuran los puntos de entrada y salida del plugin (menúes,
|
| 94 |
barras de herramientas, etiquetas de la barra de estado, menúes contextuales),
|
| 95 |
las librerías que va a usar, el paquete de traducciones, los plugins
|
| 96 |
de los que depende, etc. El fichero plugin-config.xsd contiene el esquema que |
| 97 |
ha de seguir este fichero y están comentados todos los elementos. En
|
| 98 |
el CorePlugin que viene con Adami se puede ver un ejemplo de config.xml.<br>
|
| 99 |
<br>
|
| 100 |
Las rutas de los directorios son siempre relativas al directorio |
| 101 |
del plugin y los textos de los menúes, tooltips y enabletext's son claves
|
| 102 |
en el fichero de traducciones en caso de que haya y textos literales en caso |
| 103 |
de que no haya traducciones. El fichero de traducciones es un fichero de propiedades |
| 104 |
común: ver ResourceBundle en la API de Java.<br> |
| 105 |
<br>
|
| 106 |
Dentro de los plugins aparece el concepto de extensión. |
| 107 |
Una extensión es instalada por los plugins mediante la implementación |
| 108 |
de la interfaz com.iver.andami.plugins.Extension y la instalación de
|
| 109 |
unos controles geobernados por ésta en el fichero config.xml. Mediante
|
| 110 |
esta implementación se le dice a Andami la condición que se debe |
| 111 |
cumplir para que los controles sean visibles o estén activos. Además |
| 112 |
se implementa la acción a llevar a cabo cuando se selecciona uno de los
|
| 113 |
menúes o botones asociados a la extensión. Cabe resaltar que Andami |
| 114 |
crea una instancia de cada extensión configurada en config.xml, por lo
|
| 115 |
que las clases que implementen la interfaz Extension deben de tener un constructor |
| 116 |
sin argumentos.<br>
|
| 117 |
<br>
|
| 118 |
En los tag 'extension' existe un atributo class-name en el |
| 119 |
que se especifica la clase que gobierna el punto de extensión que se
|
| 120 |
está definiendo. Esta clase deberá implementar la interfaz com.iver.andami.plugins.Extension |
| 121 |
y será mediante ésta que gobernará los menúes y |
| 122 |
botones asociados a este punto de extensión<br> |
| 123 |
<br>
|
| 124 |
Una problema común en este framework es no ver cómo |
| 125 |
se mantiene la información del proyecto concreto que se está desarrollando. |
| 126 |
El lugar adecuado es una de las extensiones instaladas. Por ejemplo en el caso |
| 127 |
de gvSIG está la extensión com.iver.cit.gvsig.ProjectExtension, |
| 128 |
en la cual hay un atributo Project que es la raíz del árbol jerárquico |
| 129 |
del cual penden las vistas, mapas, tablas, ... Además esta extensión |
| 130 |
tiene un método getProject que devuelve la referencia al proyecto, de
|
| 131 |
manera que se puede acceder desde cualquier punto de la aplicación. Para
|
| 132 |
ver el acceso a las instancias de las extensiones ver <a href="#Acceso_a_las_extensiones">acceso |
| 133 |
a las extensiones</a></p> |
| 134 |
<p><br> |
| 135 |
<font size="+1"><strong><a name="Funcionamiento_del_class_loader"></a>Funcionamiento |
| 136 |
del class loader</strong></font></p> |
| 137 |
<p> En Andami, el class loader de cada plugin delega primero en el classloader
|
| 138 |
del sistemaes decir, que si se ejecuta desde eclipse buscará por todos
|
| 139 |
los jars que haya en el classpath del proyecto, y si se ejecuta desde la linea |
| 140 |
de comandos, buscará en la variable de entorno CLASSPATH o en el argumento
|
| 141 |
-classpath que se pase como parámetro a java.<br> |
| 142 |
<br>
|
| 143 |
Si el class loader del sistema no satisface la búsqueda, se buscará |
| 144 |
en los jars del directorio especificado por el config.xml del plugin que intenta |
| 145 |
cargar la clase y si no se encuentra en dichos jars, se buscará en los
|
| 146 |
jars de los plugins de los cuales depende el plugin que intenta cargar la clase.<br>
|
| 147 |
<br>
|
| 148 |
<strong><font size="+1"><a name="Servicios_a_los_plugins"></a>Servicios |
| 149 |
a los plugins</font></strong></p> |
| 150 |
<p><br> |
| 151 |
Andami ofrece a los plugins distintos servicios |
| 152 |
a través de la clase PluginServices en cuyo javadoc se puede obtener
|
| 153 |
información sobre como usarlos. Existen unos servicios genéricos |
| 154 |
que vienen dados por métodos estáticos de dicha clase y luego |
| 155 |
está el método getPluginServices que obtiene una instancia de |
| 156 |
esta clase específica del plugin, mediante la cual puede acceder a servicios
|
| 157 |
concretos de cada plugin, traducciones, persistencia, directorio del plugin, |
| 158 |
...<br>
|
| 159 |
<br> |
| 160 |
<strong><a name="Ejecucion_en_segundo_plano"></a>Ejecución en segundo |
| 161 |
plano</strong><br> |
| 162 |
Es conveniente que la interfaz gráfica esté |
| 163 |
siempre en funcionamiento, nunca bloqueada, aunque sea sólo para mostrar
|
| 164 |
al usuario que el programa está procesando. Para ello hay que realizar
|
| 165 |
las tareas que puedan tomar demasiado tiempo en un thread a parte. La clase |
| 166 |
PluginServices proporciona un método estático backgroundExecution |
| 167 |
al cual se le pasa un objeto Runnable, que es ejecutado en segundo plano, dejando |
| 168 |
el thread de la interfaz libre para responder pero con sus eventos bloqueados |
| 169 |
con el fin de que la interfaz responda y se redibuje, pero se ignoren los eventos |
| 170 |
que produce el usuario mientras se procesa la petición<br> |
| 171 |
<br>
|
| 172 |
<a name="Acceso_a_las_extensiones"></a><strong>Acceso a las extensiones</strong><br> |
| 173 |
Para acceder a la instancia de una extensión |
| 174 |
se puede usar simplemente el método de PluginServices getExtension(Class)
|
| 175 |
a la cual habrá que pasar como parámetro la clase de la extensión |
| 176 |
a la que se quiere acceder. Dicho método retorna un objeto Extensión |
| 177 |
y por tanto habrá que hacer casting a la clase concreta de dicha extensión, |
| 178 |
habiendo obtenido así la referencia a la instancia de la extensión |
| 179 |
deseada.<br>
|
| 180 |
A la hora de desarrollar habrá que tener en el build |
| 181 |
path del entorno de desarrollo que se use, el jar del plugin dentro del cual |
| 182 |
está la extensión que se quiere obtener, para poder pasarle como |
| 183 |
parámetro a getExtension(Class) la clase de la misma.<br> |
| 184 |
<br>
|
| 185 |
<strong><a name="Persistencia_de_los_plugins"></a>Persistencia de |
| 186 |
los plugins</strong><br> |
| 187 |
Uno de los servicios que ofrece Andami a los |
| 188 |
plugins es la facilidad de guardar datos genéricos de los mismos en el
|
| 189 |
directorio del usuario de manera que cada usuario mantiene su propia configuración
|
| 190 |
de los plugins. Para ello, las instancias de PluginServices contienen una propiedad |
| 191 |
persistentXML que puede ser obtenida y asignada y que es de tipo XMLEntity, |
| 192 |
pudiendo añadir información de tipo básico (String, int, |
| 193 |
long, ...) a dicha instancia y siendo esta información persistente entre
|
| 194 |
ejecuciones.<br>
|
| 195 |
<br>
|
| 196 |
<strong><a name="popupmenus"></a>Pop-up menus</strong><br> |
| 197 |
Otro servicio proporcionado por Andami es el de pop-up |
| 198 |
menu's extensibles. Mediante el XML se puede definir un pop-up menu con un nombre |
| 199 |
y unas entradas al igual que cualquier otro menú, con la única |
| 200 |
diferencia que para mostrar el popup menú habrá que registrar |
| 201 |
un listener de la siguiente manera:<br>
|
| 202 |
</p>
|
| 203 |
<div style="text-align: center;"> |
| 204 |
<pre><>public void addPopupMenuListener(String name, Component c, ActionListener listener)</><br></pre> |
| 205 |
</div>
|
| 206 |
Lo cual hará que al pinchar con el |
| 207 |
botón derecho sobre el componente 'c' aparezca el menú |
| 208 |
'name' del fichero de configuración del plugin y al seleccionar
|
| 209 |
cualquier entrada se ejecutará el ActionListener que se pasa
|
| 210 |
como parámetro.<br> |
| 211 |
<br>
|
| 212 |
Estos menúes son extensibles porque cualquier |
| 213 |
otro plugin puede añadir entradas a dicho menú en su |
| 214 |
propio fichero config.xml referenciando el menú al que quiere
|
| 215 |
extender mediante el nombre del plugin más el nombre del
|
| 216 |
menú. Un ejemplo. Tenemos un plugin llamado com.iver.cit.gvsig
|
| 217 |
que instala un menú de la siguiente manera:<br> |
| 218 |
<pre> <popupMenu name="cascada"><br> <entry text="Cascada" <br> tooltip="cascada_tooltip" <br> enableText="cascada_enable" actionCommand="CASCADA"/><br> <entry text="Tile" <br> tooltip="tile_tooltip" <br> enableText="cascada_enable" actionCommand="CASCADA"/><br> </popupMenu><br></pre> |
| 219 |
y tenemos otro plugin que quiere añadir una entrada a dicho
|
| 220 |
menú. Para ello deberá de incluir un fragmento similar a |
| 221 |
este en su fichero config.xml:<br>
|
| 222 |
<pre> <popupMenu name="com.iver.cit.gvsig.cascada"><br> <entry text="Nueva entrada" actionCommand="NUEVA"/><br> </popupMenu><br></pre> |
| 223 |
y además deberá de registrarse como listener de la manera |
| 224 |
que se explicó anteriormente.<br> |
| 225 |
<br>
|
| 226 |
<strong><a name="Vistas"></a>Vistas</strong><br> |
| 227 |
El servicio más importante que |
| 228 |
proporciona Andami es el de añadir vistas al marco principal.
|
| 229 |
Podemos calsificar las vistas por varios criterios:<br>
|
| 230 |
<ul>
|
| 231 |
<li>Por su modalidad</li> |
| 232 |
<ul>
|
| 233 |
<li>Modales</li> |
| 234 |
<li>No modales</li> |
| 235 |
</ul>
|
| 236 |
</ul>
|
| 237 |
<ul>
|
| 238 |
<li>Por su contenido</li> |
| 239 |
<ul>
|
| 240 |
<li>Singleton (Contenido identificable)</li> |
| 241 |
<li>Normales (Contenido no identificable)</li> |
| 242 |
</ul>
|
| 243 |
</ul>
|
| 244 |
Para crear una vista hay que hacer una clase que |
| 245 |
derive de JPanel en la que se pone toda la funcionalidad como si de un |
| 246 |
diálogo normal se tratara. Además esta clase ha de |
| 247 |
implementar la interfaz View la cual proporciona un método
|
| 248 |
getViewInfo que es invocado una vez en la vida de la vista. Este objeto |
| 249 |
contiene las características que tendrá la vista: |
| 250 |
maximizable, resizable, title, ... y puede ser actualizado en cualquier |
| 251 |
momento, reflejándose estos cambios de manera automática |
| 252 |
en la interfaz de usuario. Una vez implementada la vista, hay que |
| 253 |
añadirla al manger MDI, que es el encargado de manejar toda la
|
| 254 |
lógica relacionada con las vistas. Para obtener una referencia
|
| 255 |
al manager MDI la clase PluginServices tiene un método
|
| 256 |
getMDIManager, el cual a su vez tiene un método addView mediante
|
| 257 |
el cual se puede añadir la vista.<br> |
| 258 |
<br>
|
| 259 |
Si durante la ejecución se quiere cambiar |
| 260 |
alguna propiedad de la vista tal como el tamaño, la
|
| 261 |
posición o el
|
| 262 |
título, sólo hay que acceder al objeto ViewInfo de la |
| 263 |
misma y realizar los cambios de la manera deseada. El siguiente trozo |
| 264 |
de código cambia el título de una ventana (se supone que |
| 265 |
es ejecutado desde la clase que implementa View).<br>
|
| 266 |
<pre> PluginServices.getMDIManager().getViewInfo(this).setTitle("Nuevo título");<br></pre> |
| 267 |
Puede ser necesario que algunas vistas realicen |
| 268 |
algún tipo de procesamiento al ser activadas pero esto no se
|
| 269 |
sabe cuando ocurre ya que lo que se entrega al manager MDI es un |
| 270 |
JPanel. Para recibir los eventos sobre las vistas, además de
|
| 271 |
implementar View hay que implementar ViewListener la cual |
| 272 |
proporcionará los métodos que serán invocados |
| 273 |
cuando sucedan los eventos oportunos en las vistas.<br>
|
| 274 |
<br>
|
| 275 |
<big><a name="SingletonView"></a>SingletonView<br> |
| 276 |
</big> Un tipo especial de vistas son las |
| 277 |
SingletonView. Su principal característica es que se les define
|
| 278 |
el contenido de las mismas, de manera que cuando hay una SingletonView |
| 279 |
minimizada en el proyecto y se intenta añadir un JPanel con el
|
| 280 |
mismo contenido, en lugar de aparecer otra ventana en el escritorio, lo |
| 281 |
que sucede es que la ventana que estaba minimizada se restaura a su |
| 282 |
posición anterior. Para esto, el método addView devuelve |
| 283 |
una referencia a la vista que se muestra, sea esta la que se |
| 284 |
está añadiendo o la que ya está añadida. |
| 285 |
Además, al cerrar dicha ventana se guardan las dimensiones y la
|
| 286 |
posición de las mismas, de manera que al volverla a abrir se
|
| 287 |
recuerdan estos datos.<br>
|
| 288 |
</body>
|
| 289 |
</html>
|