Guia de Migración de Módulos
Autor: Javier Pérez Villamizar
Compañia: SET SOFTWARE S.A.S.
Email: javier.p.villamizar@setsoftware.net
Nota:el presente articulo es una traducción del articulo original escrito por Redhuan D. Oon
Un Plan de Migración Para Desarrolladores
¿Por qué Migrar?
Es ampliamente conocido por todos aquellos que estan vinculados a la industria del software, que el principal dolor de cabeza es la gestión de actualizaciónes, de corrección de bugs y de versiones del codigo fuente. Entre mas cambios haya realizado el usuario al codigo fuente de la aplicación o al modelo de configuración de la misma, existe una mayor probabilidad de que se presenten conflictos con las actualizaciones o correcciones realizadas por la casa matriz del software o de la comunidad que este soportando la aplicación. Un ERP puede convertirse facilmente en un mostruo de muchas cabezas, debido a su complejidad y creciente tamaño; es por esa razón que es buena idea tener un nucleo común de la aplicación para la mayoria de los usuarios y que aquellos que necesiten realizar cambios o agregar funcionalidad puedan hacerlo a través del desarrollo de nuevos módulos o como es el caso de IDempiere de modulos encapsulados en Plugins.
El desafio es entonces migrar de manera consistente y segura evitando "romper" la funcionalidad existente. La figura 2 ilustra la labor que deben realizar los usuarios que actualmente utilizan un Sistema A (como ADempiere 3.6) y desean utilizar en el futuro el Sistema B (como Idempiere),que incluye grandes mejoras de arquitectura y mayor funcionalidad; sin emabargo la labor mas delicada es migrar al sistema B, todos los cambios y personalizaciones que el usuario a realizado al Sistema A.
¿Que Migrar?
Las siguientes preguntas que se presentan son:
-¿Qué migrar?-
-¿Se trata solo de codigo?-
La respuesta es si y no. En las aplicaciones basadas en Compiere, como los son ADempiere e IDempiere, los cambios pueden ser tanto codigo como datos. Estos datos son "Metadatos" que permiten configurar el Diccionario de la Aplicación, lo que determina el look and feel, y el modelo de configuración, incluyendo este ultimo elementos como Menús, ventanas, Tablas, Pestañas, Procesos y otras caracteristicas que aunque no estan "quemadas" (Hard Coded) en el codigo fuente, si estan almacenas en la base de datos de manera separada en un formato determinado.
Si miramos con detenimiento el diagrama anterior y tenemos presente lo que acabamos de exponer, entonces cobra sentido el hecho de que esten resaltadas con rojo las palabras AD y CODE.
AD es la sigla de Diccionario de Aplicación, que representa los metadatos mencionados antes. Lo que la figura anterior ilustra es entoces que para migrar a IDempiere los metadatos son enviados a traves de 2Pack y el codigo fuente es enviado como un nuevo plugin desarrollado con la herramienta para el desarrollo de plugins (PDE) de Eclipse.
¿Como realizar la Migración?
El siguiente paso es completar la migración de los metadatos y del codigo de manera exitosa. Tal como lo mencionamos anteriormente, la primera parte la realizamos utilizando 2Pack, que exporta en un archivo ZIP (2pack.zip), que contiene toda la descripción de los cambios realizados al AD en formato XML. La segunda parte consiste entonces en formatear los paquetes JAVA de acuerdo a la estructura de Plugin de Eclipse. Mas adelante veremos con mas detalle cada uno de estos pasos, por ahora examinando la Figura 3 podemos ver de manera clara el proceso de migración del AD a traves de las cajas señaladas por la flecha roja. En otras figuras que presentaremos mas adelante examinaremos en detalle el proceso de migración de codigo, por ahora los representamos solo con la caja de contonrno rojo que dice "Eclipse".
En la figura 3 presentamos tambien nuevos terminos, por un lado podemos ver en el Sistema A de la Izquierda que el codigo anterior Java esta envuelto en el antiguo estilo en la Maquina Virtual Java (JVM) que es una especia de contenedor cerrado que no permite ninguna forma de acceso al mismo. Por otro lado vemos en el lado derecho el Sistema B tiene un Contenedor OSGI que permite "Conectar" nueva funcionalidad al mismo a traves de Plugins Eclipse y ademas permite acceder y monitorear los mismos a traves de Comandos 'SS'.
En el nuevo sistema tambien podemos ver una relacion entre Plugins determinada por el archivo MANIFEST, que se encuentra en la carpeta META-INF.En ese archivo MANIFEST tambien esta descrito su propio "Activador" que detecta automaticamente cualquier archivo 2pack.zip en la carpeta y ejecuta el "Pack In" a la base de datos de la aplicación.
De aqui en adelante veremos como realizar el proceso de un modulo personalizado, ademas en los siguientes enlaces podremos ver los videos (en Ingles) del proceso que detallaremos a continuación:
Pack Out del Modulo
Desarrollo del Plugin en Eclipse
Pack In del Modulo como Plugin
Ademas presentamos la figura 4 en la cual introducimos los elementos sobre los cuales seguiremos analizando mas adelante.
1. El módulo del Plugin.
2. El activador del Plugin llamado en el archivo MANIFEST.
3. El archivo MANIFEST.
4. El codigo "quemado" que llama el archivo 2Pack.zip en la carpeta META-INF.
Migración de un Módulo
A continuación analizaremos un ejemplo de un modulo real de ADempiere el cual migraremos a IDempiere como plugin. Para nuestro ejemplo usaremos el modulo de integración de OpenBravo POS y ADempiere ERP que fue un trabajo que desarrollamos y publicamos el año pasado. Para ese módulo creamos un Menú llamado Integración POS, el cual contiene 3 tres sub items que son 2 procesos llamados Exportar Cola e Importar Cola de Ordenes y una ventana llamada Procesar Ordenes Importadas.
Los Items anteriores no hacen parte de la version estandar de ADempiere o IDempiere, aunque existen diferentes formas en las cuales esos cambios se pueden incorporar a IDempiere. Una de esas formas es a traves del Log de Migración que se guardo cuando la customización se realizó. Otra forma de hacerlo es usando la herramienta 2Pack que ha estado disponible por algunos años en ADempiere. De todas formas es necesario tener en cuenta que Low Heng Sin realizó considerables mejoras al 2Pack de IDempiere asi que no es necesariamente igual a su antigua versión por lo que para usar el Pack In de IDempiere es necesario usar el Pack Out de IDempiere. Como estamos utilizando IDempiere v1.0 usaremos los scripts que se encuetran en el siguiente link
https://sourceforge.net/p/red1/small/101/tree/trunk/POSIntegration/migration/
En el enlace anterior encontrará un listado de scripts SQL como lo ilustra la figura anterior. Lo siguiente es el codigo fuente del modulo, se puede obtener los Scripts de migración, el archivo 2pack.zip y el software de OpenBravoPOS que se utilizará, aunque es importante anotar que en el presente documento nos centraremos solo en el codigo de customización que estamos migrando. En el siguiente enlace podrá descargar el producto completo para usar
http://sourceforge.net/projects/red1/files/Software%20Packages/IntegratedPOSplugin.zip/download
Lanzando IDempiere
Si esta usando ambiente Windows puede instalar IDempiere de forma sencilla en un computador o notebook que no tenga instalado JAVA ni POSTGRES utilizando el Instalador, si lo necesita puede ver la guia escrita de como utilizar el instalador en conjunto con el asistente de actualización. Si esta usando un ambiente diferente a Windows puede ver las instruciones de como desplegar IDempiere en http://wiki.idempiere.org.
Una vez que IDempiere este corriendo, estará listo para aplicar los scripts de migracion y hacer el Pack Out para obtener el archivo 2pack.zip del nuevo plugin. Si necesita ayuda adicional con los scripts de migración puede ir nuestra ayuda en linea. Veamos ahora como realizar el proceso de Pack Out. Para realizar este proceso con sus propias customizaciones es importante asegurarse de que tengan un grupo de menú como es el caso de esta integracion con OpenBravo POS.
Haciendo Pack Out
Es necesario loguearse con el usuario System e ir al menú Pack Out subrayado en la siguiente imagen con el número (1). Al abrir la ventana ingrese la información como se detalla en la siguiente imagen en el número (2). En la segunda tabla selecciona Aplicación o Módulo de manera que el menú de selección señalado en (3) aparezca, luego selecciona el menú del modulo a migrar y una vez hecho esto regresa a la pestaña padre y selecciona el boton Exportar Paquete como se ilustra en (4). El proceso tardará unos momentos dependiendo de la complejidad del módulo.
Al terminar el proceso en la parte inferior de la ventana aparecerá el Path en el que el archivo 2pack.zip fue creado, tal y como se puede apreciar en (5), mas adelante usaremos el archivo creado para empaquetarlo junto con el plugin, por ahora le echaremos un vistazo al codigo fuente del módulo que tambien incluiremos dentro del plugin.
Revisando el Codigo Fuente
El codigo fuente debe estar en paquetes de manera similar a como se presenta el ejemplo, aunque la integración de ADempiere con OpenBravo POS no es muy extensa en terminos de nro de clases o lineas de codigo, el presente ejemplo es perfecto para propositos ilustrativos ya que utiliza varios componenetes del Nucleo del ERP. Un ejemplo claro se visualiza al ver el parquete org.adempiere.process que incluyen varias clases que determinan el compartamiento del proceso ImportOrder.java, que a su vez extiende la clase original del mismo paquete de ADempiere.
Para hacer algo como lo anterior en ADempiere sobre escribiamos el archivo customization.jar, pero como IDempiere utiliza la arquitectura OSGI, esto ya no es necesario. Lo unico que debemos hacer ahora es incluir el nuevo codigo en un plugin declarando el mismo paquete (org.adempiere.process) y activarlo durante el tiempo de ejecución, lo que hará que se ejecute nuestra customización en lugar del codigo base de ADempiere.
Este es basicamente el poder de la arquitectura OSGI, que a traves de la modularización, permite que no sea necesario recompilar o reemplazar el archivo customization.jar cada vez que se realice un cambio, si no que solo con agregar nuestro plugin a un contenedor de otros plugins, lo que facilita enormemente el mantenimiento de la aplicación, el debug y el seguimiento de errores en caso de que se presenten, pues bastará solo con desactivar el plugin para a traves de la consola OSGI,incluso en ejecución.
Preparando ambiente con Eclipse
En nuestra wiki puede obtener mas información de como configurar el ambiente de desarrollo Eclipse junto con la funcionalidad de Buckminster y Mercurial. Mercurial es necesario para acceder a nuestro repositorio online de IDempiere alojado en Bitbucket. Una vez hecho estamos listos para nuestro primer Plugin.
Creando un nuevo Proyecto Plugin
Selecciona Nuevo>Otro(1)> Plugin Project(3) e ingresa el nombre del modulo a migrar.
Deselecciona la opcion > Generar Activator (4). Pues usaremos el Activator que ADempiereActivator
En la carpeta META-INF se encuentra el archivo MANIFEST.MF (1) en la tabla Overview. Selecciona la opción Activator y en el botón de busca selecciona la clase AdempiereActivator, no sera posible seleccionarlo hasta que defina las dependencias del plugin, para hacerlo es necesario ir a la pestaña de dependencias (2) y agrega el plugin org.adempiere.plugins que contiene el Activador(3), ademas agregue el plugin org.adempiere.base que es el nucleo para los paquetes org.adempiere.process y org.compiere.process que se sobre escriben en el nuevo plugin. Nota que dentro de los paquetes importados he seleccionado la libreria para que mi Active MQ funcione (4).
Luego vuelve a la pestaña Overview (1) selecciona el boton buscar(2) y ahora si será posible seleccionar el Activador (3).
Revisando el Plugin
Ahora echemosle un vistazo al codigo fuente de nuestra customizacion y aseguremonos que las clases esten dentro de paquetes de manera apropiada(1), ademas las dependencias deben estar resueltas(2). Es importante notar que en la arquitectura OSGI las librerias importadas son resueltas por (a) Plataforma Destino o (B)Otros Plugins declarados en el archivo MANIFEST (3), o tambien pueden ser Jars declarados en el MANIFEST. A continuación se ilustra como se ve un plugin al estar terminado.
Sin embargo eso no es todo, antes de que el nuevo plugin funcione es necesario con el nucleo de ADempiere a traves del plugin org.adempiere.base, pues el classpath incluido en OSGI funciona de manera diferente en el que el plugin del nucleo es una serie de paquetes de clases como por ejemplo org.adempeire.process, para hacer esto debes colocar la linea Eclipse-RegisterBuddy(1) en algun lugar en el archivo MANIFEST. Tambien es posible exportar paquetes en la pestaña de ejecución (2) de manera que sea vivible para otros plugins que lo utilicen, ademas en la pestaña (3) puedes declarar jars internos que se quieran utilizar.
Con estos pasos realizados estamos listos para avanzar.
Activando el Plugin
Con todo en su lugar y sin errores rojos en nuestro ambiente eclipse vamos a ejecutar el plugin desde aqui.(En un futuro tutorial cubriremos en detalle el despliegue de plugins).
Primero, es necesario correr el script ImportIDempiere (1) de forma que la base de datos quede como nueva.
Segundo, en Eclipse dar clic en Run>Run Configurations (2)
Tercero, Seleccionamos Swingclient.product (3)
Cuarto, Seleccionamos la opción de la izquierda de nuestro nuevo plugin y configuramos el arranque por defecto.(4)
Cuando aparezca la opción de logueo del cliente JAVA, no se loguee, pues esto obstruira el proceso de empaquetado que se esta llevando a cabo. En lugar de eso vaya a la pestaña de consola y escriba la sigla 'ss' (1) (Short Status), de esa forma visualizaremos el listado de plugins con su respectivo estado.
A continuación identificamos nuestro plugin en la lista e identificamos su Id, en nuestro ejemplo vemos que es el Id = 2, asi que para activarlo escribimos en la consola: 'start 2' (2), a continuación vera el packin en acción y será necesario esperar hasta que la palabra OSGI aparezca en la ultima linea (3)
Ahora ya podemos ir a la ventana de logueo para ingresar a la aplicación, sin embargo será necesario ejecutar el proceso Role Acces Update, y despues loguearse nuevamente para tener acceso al menú del nuevo modúlo.
Una de las principales caracteristicas de este enfoque es que no es necesario preocuparse por el mantenimiento de la aplicación o los cambios de codigo, pues con tan solo escribir en la consola 'stop 2' IDempiere deja de utilizar el nuevo plugin y retorana al comportamiento anterior sin siquiera tener que parar el servidor. Es asi que nuestro ERP prueba que se ha dejado de ser una cueva cerrada para convertirse en una aplicacion dinamica y modular implementando todos lo beneficios de la arquitectura OSGI.
Conclusiones
Aunque el plugin de ejemplo presentado en el documento es sencillo, es posible desarrollar plugin mas sofisticados con el framework OSGI, empoderando en gran manera el proyecto IDempiere ya que las posibilidades son inmensas. Ademas es posible refactorizar aun mas el plugin base en plugins mas pequeños, de la misma forma que se hizo con los los callouts, los procesos y los componenetes graficos. Esto mismo podriamos hacerlo con los diferentes procesos funcionales como Manofactura, Activos Fijos o incluso facturación, pagos y recaudos. Por ultimo el implementar la plataforma OSGI, permitira a IDempiere adoptar una gran variedad de herramientas del universo OSGI y de esa forma dia tras dia veremos como IDempiere crece rapidamente.
Cualquiera que sea el camino que siga IDempiere no sera un camino lento, pues en mientras estoy escribiendo este documento, Carlos Ruiz via Skype me ha mostrado nuevos cambios que se han integrado como se pueden ver en el siguiente enlace:
http://wiki.idempiere.org/en/Category:New_Features_v0.01. Asi que IDempiere es ahora el ERP rapido y furioso del mundo Opensource.
Esta guia solo intenta ilustrar de manera general las posibilidades que tendran los desarrolladores y disminuir la curva de aprendizaje de estos para sumergirse en el mejor software del mundo. Como saben debido a los tutoriales que he escrito en el pasado, es un placer para mi compartir lo que he aprendido para que otros lo experimenten, este es el legado que quiero dejar en los ultimos años que me queden por vivir de acuerdo a la voluntad de Dios.
Si tienes alguna sugerencia o alqo para decime puedes escribirme a red1@red1.org.
Agradezco que te hayas tomado el tiempo de leer esto y es mi esperanza que estas lineas te ayuden a tomar la decisión de hacer parte de este increible proyecto.
Que la paz y la bendición de Dios este con Ustedes.
Epilogo - Usando Puntos de Extensión
Nuestro Don, Low Heng Sin ha señalado que usar Eclipse Register-Buddy no es la mejor practica y ha aconsejado en cambio que es mejor utilizar los puntos de extension para definir el proceso. Asi que regresemos un poco a Eclipse para "desarecer" esa linea, como se muestra en (1), para continuar el proceso vamos a la pestaña overview (2), daremos clic en el enlace extensiones(3), luego vamos a la pestaña extensiones(4). Despues daremos clic en el boton de agregar y selccionamos la ventana (5) de puntos de extensión eligiendo org.adempiere.process (6)y regresando a la ventana anterior damos clic derecho a la nueva linea y seleccionamos nuevo proceso (7)
Una nueva clase es definida (1), pero no es necesario escribir codigo, basta solo con dar clic en el boton de busqueda(2) y seleccionar la clase existente (3).
Luego es necesario suministrar el ID (5) que se registrará en el classpath, por ultimo puedes ingresar tambien un nombre (6).
En el siguiente enlace puedes ver un video que ilustra lo anterior.
