Métodos para el despliegue de extensiones de Alfresco

RECU-0049 (Recurso Manual)

Área: Extensión de Alfresco
Carácter del recurso: Recomendado

Descripción

Extensión básica de Alfresco

Existen varias maneras para realizar un despliegue de una extensión para Alfresco, el método concreto depende de la complejidad del desarrollo y del servidor de aplicaciones que utilicemos. Así, por ejemplo, si la personalización consiste solamente en cambios en fichero de configuración o propiedades bastaría con colocarlos en el classpath del servidor de aplicaciones.

Extensión de Alfresco usando librerías JAR

Las clases java que implementan las nuevas funcionalidades que se desarrollan para Alfresco se deben empaquetar en librerías JAR que se deben poner en el classpath de servidor de aplicaciones. Estas librerías se situarán en el directorio WEB_INF/lib de la aplicación web.

La recomendación es que todo lo que se modifique y/o cree en Alfresco debe empaquetarse en librerías. Los ficheros de configuración que van a sobrescribir los ya existentes en Alfresco se empaquetarán en el directorio META-INF del propio JAR, incluso los que añadan funcionalidades o cualquier cosa al Alfresco original.

En versiones anteriores esto era un problema ya que si se tenían en distintas librerías JAR ficheros con el mismo nombre empaquetados en la misma ruta el Classloader solo era capaz de cargar el primero que encontraba lo que provocaba comportamientos impredecibles. Sin embargo a partir de la versión de Alfresco 2.0 este problema se ha solucionado y el sistema es capaz de cargar todas las extensiones que introduzcamos en los paquetes JAR.

Las modificaciones del tipo nuevas acciones, diálogos, wizards, idiomas que se definen originalmente en web-client-config.xml también se podrían definir en el fichero web-client-config-custom.xml bajo la ruta alfresco/extension empaquetado en el JAR. Así lo podemos ver en el fichero de configuración alfresco/web-client-applicattion-context.xml.

<bean id="webClientConfigSource" class="org.alfresco.config.source.UrlConfigSource">
   <constructor-arg>
      <list>
         <value>classpath:alfresco/web-client-config.xml</value>        
         <value>classpath:alfresco/web-client-config-dialogs.xml</value>
         <value>classpath:alfresco/web-client-config-wizards.xml</value>
         <value>classpath:alfresco/web-client-config-properties.xml</value>
         <value>classpath:alfresco/web-client-config-navigation.xml</value>
         <value>classpath:alfresco/web-client-config-wcm.xml</value>
         <value>classpath:alfresco/web-client-config-actions.xml</value>
         <value>classpath:alfresco/web-client-config-forum-actions.xml</value>
         <value>classpath:alfresco/web-client-config-wcm-actions.xml</value>
         <value>classpath:alfresco/web-client-config-workflow-actions.xml</value>
         <value>classpath:alfresco/extension/web-client-config-custom.xml</value>
         <value>jar:*!/META-INF/web-client-config-custom.xml</value>
      </list>
   </constructor-arg>

Si necesitamos definir algún bean de Spring nuevo para inyectar nuestra funcionalidad, no habrá más que crear un fichero xxx-context.xml y definir ahí los beans necesarios, este fichero XML debe ir empaquetado bajo la ruta alfresco/extension, que es accesible por el sistema tal y como se indica en el bean definido en application-context.xml:

<beans>
   <import resource="classpath:alfresco/cache-context.xml" />
   .
   .
   .
   <import resource="classpath*:alfresco/extension/*-context.xml"/>
   <import resource="classpath*:alfresco/extension/dev-context.xml" />
</beans>

Extensiones del Cliente Web

La implantación de las modificaciones que se hagan en el cliente web, modificaciones sobre las interfaces de usuario, depende de lo que se quiera personalizar. La implementación de JSF procesa cualquier fichero de configuración disponible siguiendo las siguientes reglas:

Primero busca todos los recursos llamados META_INF/faces_config.xml. (ej: Ficheros empaquetados en las librerías JAR).
Después comprueba todos los ficheros especificados por el parámetro javax.faces.CONFIG_FILES definido en el web.xml de la aplicación web.
Por último procesará, si existe, el fichero de configuración /WEB_INF/faces_config.xml.

Para la reescritura de reglas de navegación JSF se sigue la política de quedarse con la primera definición que encuentre sin embargo para la reescritura de beans de respaldo se usará la última definición encontrada.

Si lo que se quiere es sobrescribir una regla de navegación tendremos que crear un fichero de definición faces_config.xml y empaquetarlo en un paquete .jar. Si por el contrario se quiere sobrescribir un bean el procedimiento es crear un fichero faces_config_custom.xml y copiarlo al directorio WEB_INF de la aplicación web de Alfresco, ya que si leemos el web.xml de Alfresco nos encontramos que:

<web-app>
  ...
  <context-param>
    <param-name>javax.faces.CONFIG_FILES</param-name> 
    <param-value>/WEB-INF/faces-config-app.xml,
      [?]/WEB-INF/faces-config-custom.xml,[?]
      /WEB-INF/faces-config-enterprise.xml
    </param-value> 
  </context-param>
  ...
</web-app>

En la siguiente tabla vemos una pequeña guía de la configuración JSF:

Extensión	Fichero y Localización
Sobrescribir reglas de navegación	faces-config.xml en META-INF
Sobrescribir beans de respaldo	faces-config-custom.xml en WEB-INF
Nuevas reglas de navegación	Cualquiera de los dos
Nuevos beans de respaldo	Cualquiera de los dos

Extensiones fuera de librerías JAR

Muchas extensiones también implicarán el desarrollo de ficheros JSP personalizados. Estos ficheros no se pueden colocar dentro de ficheros JAR. Del mismo modo otro tipo de contenidos web como imágenes, ficheros JavaScript u hojas de estilo que, aunque pueden ser extraídos de un JAR usando weblets2, se quiere tener en el sistema de ficheros.

Los JSP personalizados deben colocarse en el directorio jsp/extension de la aplicación web, las imágenes en el directorio images/extension, hojas de estilo en jsp/extension y ficheros JavaScript en scripts/extension.

La forma más sencilla de empaquetar una extensión es construir la estructura de directorios que necesitamos colocar los distintos ficheros donde necesitemos y comprimirlo todo en un fichero ZIP. El fichero tendría una estructura parecida a esta:

css
   > extension
      > estilos-personalizados.css
> images
   > extension
      > incono-usuario1.jpg
> jsp
   > extension
      > login-personalizado.jsp
> WEB_INF
   > lib
      > login-personalizado.jar
         >alfresco
            > extension
               > web-client-config-custom.xml
         > META_INF
            > faces-config.xml
            > MANIFEST.MF
         > es
            > intecna 
               > ejemplos
                  > LoginBeanPersonlizado.class
> scripts

Para hacer el despliegue bastaría con parar el servidor descomprimir el fichero en el raíz de la aplicación Alfresco e iniciar de nuevo el servidor. Este método de despliegue solo es recomendable durante la fase de desarrollo o con extensiones muy pequeñas. Si la implantación se ha hecho por este sistema se vuelve a desplegar el Alfresco WAR en el servidor de aplicaciones web la extensión se borrará.

Por eso para implantaciones en sistemas de producción se recomienda hacer el despliegue mediante ficheros de extensión AMP.

Extensión con Módulos AMP

Siempre es recomendable el uso de módulos de extensión AMP (Alfresco Module Package) para las nuevas funcionalidades. Los módulos de extensión AMP son ficheros que contienen una colección de código, XML, imágenes, CSS, etc… que extienden la funcionalidad proporcionada por el repositorio de Alfresco.

Estos contenidos están distribuidos dentro de una estructura como la siguiente:

/
  |
  |- /config
  |
  |- /lib
  |
  |- /licenses
  |
  |- /web
    |
    |- /jsp
    |
    |- /css
    |
    |- /images
    |
    |- /scripts
  |
  |- module.properties
  |
  |- file-mapping.properties

Esta no es una estructura obligatoria, puede faltar cualquier directorio o estar vacío. Cada uno de ellos será mapeado dentro de un Alfresco WAR usando la Herramienta de Manejo de Módulos (MMT):

/config: El contenido será mapeado dentro del directorio /WEB-INF/classes en el fichero WAR. En este directorio se situarán los ficheros que definirán la configuración Spring y la del Interfaz de Usuario. En este directorio debe estar también el fichero module-contex.xml con la configuración Spring del modulo.
/lib: El contenido será mapeado en el directorio en /WEB-INF/lib. Deberá contener los ficheros JAR de nuestro modulo.
/licenses: Si el modulo usa algún librería que necesite de una licencia, estas deberán estar situadas en este directorio.
/web/jsp: El contenido será mapeado con el directorio /jsp del fichero WAR. El directorio debe contener todos los JSP nuevos o modificados del módulo.
/web/css: El contenido será mapeado con el directorio /css del fichero WAR. El directorio debe contener las hojas de estilo de nuestro módulo.
/web/images: El contenido será mapeado en el directorio /images del WAR. Contendrá las imágenes que use nuestro módulo.
/web/scripts: Los contenidos serán mapeados en el directorio /scripts del WAR. Los ficheros con código JavaScript que use el módulo deberán ser puestos aquí.

Si no se indica lo contrario se creará una copia del WAR antes de procesar el fichero AMP. Cualquier estructura de carpetas que se encuentre en estos directorios será mapeada de manera idéntica dentro de los directorios del WAR. Si alguno de los ficheros que estamos mapeando se encuentran ya en el WAR será sobrescrito.

El fichero module.properties debe estar obligatoriamente en el AMP. Contiene los meta-datos del módulo, lo más importante son el id y versión del módulo que estamos empaquetando.

El fichero file-mapping.properties no es obligatorio, nos servirá para cambiar el mapeo por defecto y usar uno personalizado. Para ello daremos una serie de pares llave valor con los nombres de los directorios del AMP y su destino en el WAR.

Herramienta de Gestion de Modulos (MMT)

La Herramiente de gestión de modulos (MMT) ayuda ha manejar los modulos AMP instalados en un fichero Alfresco WAR estandar. La herramienta de gestión de modulos soporta: instalación de modulos AMP incluyendo actualizaciones a versiones mas recientes, habilitación y deshabilitación de modulos instalados, desinstalación de modulos instalados y listado de modulos actualmente instalados.

Los Modulos AMP son empaquetados e instalados como ficheros AMP. Un Fichero AMP hace referencia a un modulo y versión especifica. Durante el proceso de instalación, estos datos son tomados en consideración.

Ejecución

Desde la v2.1 de Alfresco el mmt se distribuye separadamente como un jar ejecutable. Se puede descargar desde el área de descargas de Alfresco (alfresco-mmt-2.1.jar). Es compatible con ficheros war de versión 2.0 o superior. La sintaxis de ejecución es:

java -jar alfresco-mmt-2.1.jar [args]

Comandos MMT

Para acceder a las diferentes funcionalidades que ofrece em mmt deberemos usar en la llamda uno de los siguientes comandos.

install: Para la instalación de módulos usaremos el siguiente comando:

uso: install <LocalizaciondelAMP> <LocalizaciondelWAR> [options]
opciones validas:
   -verbose   : habilitar la salida
   -directory : indica que la localizacion del fichero amp especificado es un 
                directorio. Todos los ficheros amp encontrados en el directorio 
                y sus subdirectorios serán instalados.
   -force     : fuerza la instalación del AMP independientemente de la versión 
                que ya este instalada
   -preview   : vista preliminar de la instalación del AMP sin modificar el WAR 
   -nobackup : indica que no se debe hacer backup del WAR

Este comando instala los ficheros encontrados en el fichero AMP dentro del Alfresco WAR, actualizándolo si una versión antigua ya está instalada. Al realizar esta actualización los ficheros instalados por la versión antigua serán borrados del war y reemplazados por los de la nueva.Si la versión del modulo es igual o menor que la versión que ya está instalada la instalación se cancelará, a menos que se especifique la opción -force. Antes de que un Modulo AMP sea instalado en un WAR se realiza una copia del original y se guarda en el mismo directorio. Especificando la opción -nobackup se evita esta copia.

Así la sintaxis completa para la instalación de un modulo será:

java -jar alfresco-mmt-2.1.jar install <FicAMP> <FicWAR> -force

list:

uso: list <FicWAR>

Lista los detalles sobre todos los modulos actualmente instalados en el fichero WAR especificado.

disable: (Este comando no esta disponible en el realease 2.1)

uso: disable <moduleId> <FicWAR>

enable: (Este comando no esta disponible en el realease 2.1)

usage: enable <moduleId> <FicWAR>

uninstall: (Este comando no esta disponible en el realease 2.1)

uso: uninstall<moduleId> <FicWAR>