Atlassian plugins con eclipse y maven

En el siguiente artículo mostramos una sencilla guía para construir un plugin de JIRA, Confluence o Bamboo usando eclipse y el plugin de maven resolviendo las limitaciones actuales que presenta el SDK de Atlassian.

1. Prepara tu entorno para el SDK de Atlassian.

Atlassian dispone de un SDK para la creación de plugins (y otros artefactos) que simplifica en gran medida los requerimientos de entorno necesarios. Será necesario disponer de un Development Kit de Java (JDK) de la versión 6 que puedes descargar desde este enlace.

El SDK contiene una instalación de Maven tuneada para incorporar plantillas y herramientas que faciliten la construcción inicial de un plugin. Descarga la última versión del SDK desde aquí y descomprime en una ruta sin espacios en blanco. Por último añade el subdirectorio bin del SDK al path.

A continuación instalaremos el IDE, en este caso, la versión Helios de eclipse para desarrolladores de Java. Importante! La última versión de eclipse en el momento de escribir este artículo es Indigo pero esta versión tiene una incompatibilidad con el SDK de Atlassian que te impedirá utilizar el plugin de M2Eclipse. Puedes descargar la versión Helios de eclipse desde este enlace. Al igual que ocurre con el SDK, es conveniente evitar los espacios en blanco en la ruta de instalación de eclipse.

2. Configura eclipse

El plugin de Maven no ejecuta sobre un JRE por lo que será necesario garantizar que eclipse se ejecuta sobre un Development Kit (JDK). Para evitar problemas deberás modificar el fichero eclipse.ini para añadir la ruta al JDK (al principio del fichero). Por ejemplo:

-vmC:/Program Files/Java/jdk1.6.0_29/bin

La versión Helios de eclipse no incluye el plugin M2Eclipse para integrar con Maven por lo que tendremos que añadirlo de forma manual. Esto nos permite recurrir a una versión del plugin compatible con el SDK de Atlassian que encontrará en el siguiente enlace: http://m2eclipse.sonatype.org/installing-m2eclipse.html. Añade el nuevo repositorio y descarga el plugin Maven Integration for Eclipse.

El plugin de Sonatype incluye una instalación empotrada de Maven que habrá que sustituir por la instalación incluida en el SDK. Para ello accederemos a la configuración del plugin en eclipse mediante el menú Window->Preferences->Maven->Installations. En esta pantalla añadimos la ruta de la instalación de Maven en el SDK.

Para concluir la configuración de eclipse estableceremos una variable de entorno con la ubicación del repositorio Maven local en el que se almacenarán los artefactos. Abrimos un terminal para acceder al SDK mediante la línea de comandos y ejecutamos la sentencia:

atlas-mvn eclipse:add-maven-repo "-Declipse.workspace="

En windows es importante emplear dobles comillas para que se resuelva correctamente la ruta del espacio de trabajo de eclipse. La ejecución del comando debería generar la siguiente salida:

La ejecución de este comando crea una variable de tipo Classpath en eclipse con el nombre M2_REPO que apunta al repositorio de artefactos Maven que empleará el plugin.

3. Crea tu primer plugin con el SDK.

Ya estamos listos para empezar a crear plugins. Hay diversas formas de crear plugins en función de la funcionalidad y el producto. Nosotros os presentamos el método más rápido mediante las herramientas del SDK que permiten generar esqueletos de plugins como proyectos de eclipse.

Empleando el terminal de línea de comandos, navega hasta el espacio de trabajo (workspace) de eclipse. Para generar un plugin de JIRA ejecutamos el siguiente comando:

atlas-create-jira-plugin

De igual forma se pueden generar plugins para confluence o bamboo, reemplazando jira por el producto correspondiente!

Durante la ejecución del comando anterior será necesario proporcionar valores para la versión de JIRA, el GroupId, ArtifactId, Versión, etc. A continuación se muestra la salida completa:

 

Una vez creado el proyecto Maven, actualizamos las dependencias del POM.xml. Para ello, desde el terminal de línea de comandos, navegamos hasta el plugin que acabamos de generar y ejecutamos el siguiente comando:

atlas-mvn eclipse:eclipse

Una vez se han descargadas las dependencias y se ha actualizado el repositorio, importamos el plugin como proyecto en eclipse desde el menú File->Import->Maven->Existing Maven Projects seleccionando el proyecto creado en el paso anterior.

E voilà! Ya tenemos el proyecto listo para construir un plugin.

4. Construye, despliega y depura.

El proyecto está configurado para construir automáticamente por lo que no es necesario invocar ningún comando de Maven para validar el código. Para generar el plugin en forma de archivo .jar utilizaremos los comandos de Maven. Seleccionamos el proyecto y ejecutamos desde eclipse Run As->Maven package.

Este comando nos creará el fichero test-plugin-1.0-SNAPSHOT.jar en la carpeta target de nuestro proyecto. Ya estamos listos para desplegar nuestro primer plugin.

Si no has instalado JIRA todavía, hazlo ahora. Descarga el instalable desde este enlace. Si no dispones de una licencia, puedes descargarte una de evaluación o comprar una licencia por solo 10$ (que se destinarán a una ONG). Contacta con Novagenia si necesitas mas detalles…

Para instalar el plugin en JIRA necesitas entrar con un usuario que disponga de permisos de administrador. Acceder a la interfaz de Administración y entra en Plugins. Sobre la solapa de Install pincha en Upload plugin y selecciona la ubicación del archivo jar del plugin.

Si la importación acaba correctamente tu plugin ya está cargado en JIRA. A partir de este momento ya puedes acceder a la funcionalidad del plugin sin reiniciar la herramienta. Modifica el código, amplia la funcionalidad, si quieres, crea diferentes versiones del plugin desde el POM.xml, genera un nuevo archivo e instala repitiendo los mismos pasos. Podrás actualizar el plugin tantas veces como quieras desde la interfaz sin tener que reiniciar (solamente es casos muy concretos es necesario reiniciar el sistema de plugins pero suele bastar con deshabiltar y habilitar el plugin desde la interfaz). Si has introducido nuevos campos personalizados, no te olvides de reindexar.

Para tener mayor control sobre las trazas, añade niveles de traza específicos para el plugin en el fichero log4j.properties de JIRA. Una vez arrancado, podrás modificar el nivel de traza desde la interfaz de Administración de JIRA.

log4j.logger.com.novagenia = DEBUG, fileloglog4j.additivity.com.novagenia = false

5. [Actualizado] Resuelve warnings

Utilizando la configuración estándar que hemos descrito hasta ahora se obtiene un plugin completamente funcional. Sin embargo hay algunos aspectos que conviene pulir para optimizar los recursos y evitar problemas futuros. Nuestro objetivo será eliminar los warnings de Maven.

5.1 Versión de maven-compiler-plugin

En algunos casos, la compilación del proyecto en eclipse a través del plugin de maven retorna el siguiente mensaje:

[WARN] [WARN] Some problems were encountered while building
 the effective model for com.novagenia.jira.plugins:test-plugin:atlassian-plugin:1.0-SNAPSHOT[WARN]
 'build.plugins.plugin.version' for org.apache.maven.plugins:maven-compiler-plugin is missing. 
@ line 55, column 21[WARN] [WARN] It is highly recommended to fix these problems because they 
threaten the stability of your build.[WARN] [WARN] For this reason, future Maven versions might no l
onger support building such malformed projects.[WARN]

Aunque con la versión actual de Maven, se trata solo de un aviso en futuras versiones podría romper la construcción del plugin. Para resolverlo basta con asegurarnos de cual es la versión más reciente del plugin que tenemos instalada en nuestro repositorio y actualizar el fichero POM.xml. En nuestro caso, la versión más reciente en el repositorio del plugin org.apache.maven.plugins.maven-compiler-plugin es la 2.3.2.

5.2 Independencia de plataforma

La codificación por defecto que emplea eclipse es Cp1252 que no es independiente de plataforma. Esto implica que los proyectos de eclipse utilizarán este tipo de codificación al manejar ficheros de texto. Aunque es inocuo para los ficheros de código, xml o propiedades, esto podría representar un problema para archivos que contengan HTML. El mensaje que proporciona maven en este caso es el siguiente:

[WARN] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent!

Para resolverlo utilizaremos la propiedad project.build.sourceEncoding en el POM.xml

5.3 Evita conflictos entre dependencias

Debido a la gran cantidad de dependencias que tiene las librerías que contienen el API de los distintos productos de Atlassian, es fácil encontrar que los artefactos publicados en los repositorios tienen dependencias con distintas versiones de librerías base como xerces o junit. El problema fundamental con estos conflictos es que maven empaqueta las versiones de los artefactos en conflicto en el directorio META-INF/lib del plugin por lo que el tamaño de éste se incrementa de forma considerable. En el ejemplo que estamos utilizando, el tamaño del archivo .jar con los contenidos del plugin es de 4.5 MB!

Además de la presencia de los archivos en el directorio lib del plugin tenemos otras formas de detectar este problema. En la vista de jerarquía de dependencias (Dependency Hierarchy) para el pom.xml veremos como algunas librerías muestran el conflicto de versiones.

En las trazas de Maven podemos ver con más detalle los artefactos afectados.

[INFO] Copying dom4j-1.4.jar to C:\Users\emayor\workspace\test-plugin\target\classes\META-INF\lib\
dom4j-1.4.jar[INFO] Copying jaxen-1.1.1.jar to C:\Users\emayor\workspace\test-plugin\target\
classes\META-INF\lib\jaxen-1.1.1.jar[INFO] Copying jdom-1.0.jar to C:\Users\emayor\workspace\
test-plugin\target\classes\META-INF\lib\jdom-1.0.jar[INFO] Copying xalan-2.7.0.jar to C:\Users\
emayor\workspace\test-plugin\target\classes\META-INF\lib\xalan-2.7.0.jar[INFO] Copying xercesImpl
-2.9.1.jar to C:\Users\emayor\workspace\test-plugin\target\classes\META-INF\lib\xercesImpl-2.9.1.
jar[INFO] Copying xmlParserAPIs-2.6.2.jar to C:\Users\emayor\workspace\test-plugin\target\classes
\META-INF\lib\xmlParserAPIs-2.6.2.jar[INFO] Copying xml-apis-1.3.04.jar to C:\Users\emayor\
workspace\test-plugin\target\classes\META-INF\lib\xml-apis-1.3.04.jar

Existen varias alternativas para configurar la estructura final del archivo dependiendo de la versión y el nivel de conocimiento de Maven. Por simplicidad nosotros utilizaremos el mecanismo de dependencias mediante la interfaz de eclipse. Para ello, en la vista de dependencias del pom.xml añadiremos la última versión compatible con cada uno de los artefactos copiados con ámbito (scope) provided.

Listo. Nuestro plugin ocupa ahora 9 KB y ha desparecido el directorio META-INF/lib.

6. Explora todas las posibilidades

Explora el SDK para saber conocer las posibilidades que te ofrecen las herramientas de Atlassian. Puedes encontrar información detallada en el site dedicado al desarrollo sobre atlassian: http://developer.atlassian.com.

Cuando tu plugin esté listo, compártelo con la comunidad subiéndolo al repositorio oficial de plugins que mantiene Atlassian: http://plugins.atlassian.com.

Esperamos que os haya resultado úitl. Contadnos vuestra opinión..

Saludos1. Get ready for Atlassian SDK.

Atlassian provides an SDK for plugins (and other artifacts as well ) creation that simplifies the setup of a complex environment. Platform requirements: Java Development Kit (JDK) version 6 you can download here.

The Atlassian SDK comes with a Maven instalation with extra tools that helps jumpstarting a plugin. Download the latest SDK from this location and uncompress on a local path without spaces. Finally add the Maven’s bin folder to your path.

Then we will install the IDE, making sure we user eclipse Helios for Java development. Important! The latest eclipse version (when this entry was written) is Indigo which is incompatible with Atlassian SDK Atlassian and you won’t be able to use eclipse pluginj for Maven: M2Eclipse. Eclipse Helios can be downloaded from this link. Again, avoid spaces in eclipse installation path.

Si continuas utilizando este sitio aceptas el uso de cookies. más información

Los ajustes de cookies de esta web están configurados para "permitir cookies" y así ofrecerte la mejor experiencia de navegación posible. Si sigues utilizando esta web sin cambiar tus ajustes de cookies o haces clic en "Aceptar" estarás dando tu consentimiento a esto.

Cerrar