Home > Engine & Repository

Modules

An EBX.Platform Module allows the packaging of an adaptation model with additional resources: default messages file, default formats, XML Schema documents included, etc.

On a J2EE application server, an EBX.Platform Module is integrated into a Web application. This provides Web applications features such as: class-loading isolation, WAR or EAR packaging, static Web resources exposition, hot-redeployment. In addition, if your user application is a Web application, it is possible to merge the EBX.Platform module with your application, in order to simplify deployment.

Structure

An EBX.Platform module contains the following files:

  1. /WEB-INF/ebx/
    This directory contains all description and configuration files for using EBX.Platform.
  2. /WEB-INF/ebx/module.xml
    This file defines the global properties of the module.
  3. /WEB-INF/ebx/dataModel.xsd
    This file defines the adaptation model (XML Schema document) of the module.
  4. /WEB-INF/web.xml
    This file ensures module registration at application server launch (see Registration).
  5. /WEB-INF/ebx/module.properties
    This files defines additional properties.
  6. /www/
    This directory contains all external resources (accessible by URL). This directory is optional, localized and structured by resource type (html, images, jscripts, stylesheet). External resources in this directory can be referenced in adaptation models (parameters of type resource).

Overview of an EBX.Platform module integrated into a Web application:

Declaration
 

module.xml file

A module is declared with the file /WEB-INF/ebx/module.xml. This file declares the main properties of the EBX.Platform module.

Required fields:

<name>

Module name, unique identifier on the platform.
The module name must correspond to the Web application name (name of the directory)

Optional fields:

<installerClassName>

Name of the installation class (Java class, see below).

<publicPath>

Specific path to the Web application that integrates the module: this path is added to the URL of an external resource of the module in the case of absolute URL computing. If this field is not filled, the public name is the module name.

<locales>

List of localizations supported by the module.
If the field is not filled, the module default localization is fr_FR.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns ="urn:ebx-schemas:module_2.1" xmlns:xsi ="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation ="urn:ebx-schemas:module_2.1 http://schema.orchestranetworks.com/module_2.1.xsd">
              <name>ebx-unit0-1.0</name>
              <publicPath>optionalPublicPath</publicPath>
              <installerClassName>com.onwbp.wbp.testorg.unit0.Unit0Installer</installerClassName>
              <locales>
                            <locale isDefault ="true">fr_FR</locale>
                            <locale>en_US</locale>
              </locales>
</module>

The file module.xml is based on the XML Schema urn:ebx-schemas:module_2.1. This schema is available here.

Installation class and additional services

It is possible to combine with the module an installation class and additional services. This is declared in the file: /WEB-INF/ebx/module.xml.

Example in the file "module.xml" :

<installerClassName>com.onwbp.wbp.testorg.unit0.Unit0Installer</installerClassName> 

The class must:

  1. be public;
  2. implement the interface com.onwbp.core.service.ServiceInstaller;
  3. have a public constructor without arguments

module.properties

An EBX.Platform module can redefine, at its level, the properties described in ebx.properties.

This redefinition is done in the optional file /WEB-INF/ebx/module.properties.

It allows to:

  • configure a log file specifically for the module;
  • configure adaptation connectors mode (see ebx.properties);
  • configure the debug mode and page refresh, if the module uses EBX.Platform navigation engine (this concerns EBX.Manager Web Application only)

An example is provided below:

  • the file is read every second;
  • there is no HTML debug;
  • a specific log file is associated with this module
###############################################
## Checks if this file has been updated
## If value <= 0, no more checks will be done
###############################################
thisfile.checks.intervalInSeconds=1
###############################################
## End-User Debug Mode
## If not set, takes global ebx.properties
## Debug information appears on end-user web page.
###############################################
frontEnd.debugMode=false
###############################################
## Back-End Mode
## If not set, takes global ebx.properties
## value is one of: dev, development, inte, integration, prod, production
###############################################
#backend.mode=production
###############################################
## Reload templates when it is updated
## If not set, takes global ebx.properties
###############################################
#templates.checksIfUpdated=true
###############################################
## Log configuration
###############################################
log.threshold.main = INFO
log.threshold.service = INFO
log.threshold.backendRequestSent = INFO
log.threshold.backendResponseParsed = INFO
log.threshold.backendResponseReceived = INFO

In order to avoid a log file creation, comment /WEB-INF/ebx/module.properties lines that describe log categories.

Registration

In order to be identified by EBX.Platform, a module must be registered at runtime.

Registration of a Web Application

For a Web Application (inside an application server), every EBX.Platform module must:

  1. Contain a Servlet that registers the module by calling:
    com.onwbp.base.repository.ModulesRegister.registerWebApp(…).
    See example « com.foo.RegisterServlet » below.
    In addition, the Servlet class must be loaded by the Web Application classLoader, if classes such as adaptation connectors are defined by the Web Application;
  2. Declare this class in WEB-INF/web.xml (replace InitModuleServlet);
  3. Launch this servlet at server startup: <load-on-startup>1</load-on-startup>.

Unregistration of a Web Application

It is also advised to unregister a Web Application when method destroy() is called (see example below).

Once the method ModulesRegister.unregisterWebApp() has been executed by EBX, the schema(s) and the adaptation(s) that depend on it become unavailable (except instances of the class Adaptation which are currently used - they are marked as obsolete).

Hot redeployment

EBX.Platform supports hot-deployment and hot-redeployement operations that are implemented by J2EE application servers: deployment-start, stop-restart, stop-redeployment-restart, stop of a Web Application.

These operations remain sensitive for some application servers (particularly class-loading), consequently server procedure must be followed carefully.

Example of servlet that registers a module:

package com.foo;
import javax.servlet.*;
import javax.servlet.http.*;
import com.onwbp.base.repository.*;
/**
  */
public class RegisterServlet extends HttpServlet
{
              public void init(ServletConfig config) throws ServletException
              {
                            super.init(config);
                            ModulesRegister.registerWebApp(this, config);
              }
              public void destroy()
              {
                            ModulesRegister.unregisterWebApp(this, this.getServletConfig());
              }
}

WEB-INF/web.xml file example:

<web-app>
    <servlet>
       <servlet-name>InitEbxServlet</servlet-name>
       <servlet-class>com.foo.RegisterServlet</servlet-class>
       <load-on-startup>1</load-on-startup>
    </servlet>
</web-app>

Registration outside an application server

package com.foo;
import com.onwbp.base.repository.*;
/**
  */
public class RegisterMyModule
{
              public void register(File pathToModule)
              {
                            try
                            {
                                  ModulesRegister.registerDirectory(pathToModule);
                            } catch (ModuleDefinitionException e)
                            {
                                  // Handle exception
                            }
              }
}

Registration and unregistration logging

Registration and unregistration are logged on EBX.Platform "log.kernel" category.

Modules

Le module EBX.Platform sert à « packager » un modèle d’adaptation avec ses ressources annexes : fichier de messages par défaut, formats par défaut, documents XML Schéma inclus, etc.

Sur un serveur J2EE, le module EBX.Platform s’intègre à une application Web, ce qui lui permet de bénéficier des caractéristiques de ce type d’applications : isolation du class-loading, packaging WAR ou EAR, exposition des ressources Web statiques, redéploiment à chaud. Par ailleurs, si l’application utilisatrice est une application Web, il est tout à fait possible de fusionner le module EBX.Platform et cette application afin d’en simplifier le déploiement.

Structure

Un module contient les fichiers suivants :

  1. /WEB-INF/ebx/
    Ce répertoire contient tous les fichiers de description et de configuration pour utiliser EBX.Platform.
  2. /WEB-INF/ebx/module.xml
    Ce fichier définit les propriétés générales du module EBX.
  3. /WEB-INF/ebx/dataModel.xsd
    Ce fichier définit le modèle d'adaptation par défaut du module EBX.
  4. /WEB-INF/web.xml
    Ce fichier J2EE assure l'enregistrement du module au lancement du serveur d'application (voir Enregistrement).
  5. /WEB-INF/ebx/module.properties
    Ce fichier définit des propriétés complémentaires.
  6. /www/
    Ce répertoire contient toutes les ressources externes (accessibles par URL). Ce répertoire est optionnel, localisé et structuré par type de ressource (html, images, jscripts, stylesheet). Les ressources externes contenues dans ce répertoire sont référençables dans les modèles d'adaptation (pour les paramètres de type ressource).

Vue d’ensemble du module EBX.Platform intégré à une application Web :

Déclaration
 

Fichier module.xml

Un module EBX.Platform est déclaré via le fichier /WEB-INF/ebx/module.xml. Ce fichier déclare les principales caractéristiques du module.

Champs obligatoires

<name>

Nom du module, identifiant unique sur la plate-forme.
Le nom du module doit correspondre au nom de l'application Web (nom du répertoire).

Champs optionnels

<installerClassName>

Nom de la classe d'installation (classe Java, voir ci-dessous).

<publicPath>

Chemin spécifique à l'application Web qui intègre le module : ce chemin est ajouté à l'URL d'une ressource externe du module en cas de calcul absolu de l'URL.
Si ce champ n'est pas renseigné, le nom public est égal au nom du module.

<locales>

Liste des localisations supportées par le module.
Si le champ n'est pas renseigné, le module est localisé par défaut en fr_FR.

Exemple:

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns ="urn:ebx-schemas:module_2.1" xmlns:xsi ="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation ="urn:ebx-schemas:module_2.1 http://schema.orchestranetworks.com/module_2.1.xsd">
              <name>ebx-unit0-1.0</name>
              <publicPath>optionalPublicPath</publicPath>
              <installerClassName>com.onwbp.wbp.testorg.unit0.Unit0Installer</installerClassName>
              <locales>
                            <locale isDefault ="true">fr_FR</locale>
                            <locale>en_US</locale>
              </locales>
</module>

Le fichier module.xml repose sur le schéma XML urn:ebx-schemas:module_2.1. Ce schéma XML est disponible ici.

Classe d’installation et de services additionnels

Il est possible d’associer au module une classe d’installation et de services additionnels. Elle est déclarée dans le fichier /WEB-INF/ebx/module.xml.

Exemple de déclaration dans le fichier "module.xml" :

 

<installerClassName>com.onwbp.wbp.testorg.unit0.Unit0Installer</installerClassName> 

La classe fournie doit :

  1. être publique ;
  2. implémenter l'interface com.onwbp.core.service.ServiceInstaller ;
  3. posséder un constructeur public sans arguments.

Fichier module.properties

Un module EBX.Platform peut redéfinir à son niveau certaines des propriétés globales décrites dans ebx.properties.

Cette redéfinition se fait dans le fichier optionnel /WEB-INF/ebx/module.properties.

Il permet de :

  • configurer un journal d'activité propre au module ;
  • configurer le mode back-end dans le cas où le modèle d'adaptation définit des noeuds dont les valeurs dépendent du mode back-end (cf. ebx.properties) ;
  • configurer le mode debug et le rafraîchissement des pages dans le cas où le module utilise le moteur de navigation EBX.Platform (utilisé par l'application Web EBX.Manager).

Un exemple est donné ci-dessous :

  • le fichier est lu toutes les secondes ;
  • il n'y a pas de debug HTML (valeur forcée quelle que soit la valeur générale) ;
  • un fichier de log spécifique est associé à ce module.
###############################################
## Checks if this file has been updated
## If value <= 0, no more checks will be done
###############################################
thisfile.checks.intervalInSeconds=1
###############################################
## End-User Debug Mode
## If not set, takes global ebx.properties
## Debug information appears on end-user web page.
###############################################
frontEnd.debugMode=false
###############################################
## Back-End Mode
## If not set, takes global ebx.properties
## value is one of: dev, development, inte, integration, prod, production
###############################################
#backend.mode=production
###############################################
## Reload templates when it is updated
## If not set, takes global ebx.properties
###############################################
#templates.checksIfUpdated=true
###############################################
## Log configuration
###############################################
log.threshold.main = INFO
log.threshold.service = INFO
log.threshold.backendRequestSent = INFO
log.threshold.backendResponseParsed = INFO
log.threshold.backendResponseReceived = INFO

Pour que le fichier de log d’un module ne soit pas créé, il suffit de commenter dans /WEB-INF/ebx/module.properties les lignes décrivant les catégories de log.

Enregistrement

Afin que le module soit identifié sur EBX.Platform, il est nécessaire qu'il soit enregistré à l'exécution.

Enregistrement dans le cas d'une application Web

Dans le cas d'une application Web (fonctionnement dans un serveur d'application), tout module doit :

  1. contenir une servlet qui enregistre le module EBX.Platform en appelant :
    com.onwbp.base.repository.ModulesRegister.registerWebApp(...).
    Voir exemple « com.foo.RegisterServlet » ci-dessous.
     
  2. La classe "servlet" doit être effectivement définie par l'application Web (c'est à dire chargée via le classLoader de l'application Web). Ceci est nécessaire pour que EBX.Platform récupère le classLoader de l'application Web, dans les cas où des classes telles que des connecteurs backend sont définis par l'application Web.
     
  3. déclarer cette classe dans WEB-INF/web.xml (à la place de InitModuleServlet).
    Assurer que cette servlet se lance au startup : <load-on-startup>1</load-on-startup>

Désinscription d'une application Web

Il est conseillé de désinscrire une application Web quand la méthode destroy() est appelée (voir exemple ci-dessous). Dès que la méthode ModulesRegister.unregisterWebApp() a été traitée par EBX, le schéma et les adaptations qui en dépendent deviennent indisponibles (sauf les instances de la classe Adaptation qui sont en cours d'utilisation et qui sont marquées comme "obsolètes").

Redéploiement à chaud

EBX.Platform supporte les opérations de déploiement et redéploiement à chaud que proposent les serveurs d'application J2EE : déploiement-démarrage, arrêt-redémarrage, arrêt-redéploiement-redémarrage, arrêt d'une application Web.

Ces opérations restent sensibles pour les serveurs d'application, particulièrement le class-loading, on veillera donc à respecter scrupuleusement les procédures du serveur.

Exemple de servlet qui enregistre un module :

package com.foo;
import javax.servlet.*;
import javax.servlet.http.*;
import com.onwbp.base.repository.*;
/**
  */
public class RegisterServlet extends HttpServlet
{
              public void init(ServletConfig config) throws ServletException
              {
                            super.init(config);
                            ModulesRegister.registerWebApp(this, config);
              }
              public void destroy()
              {
                            ModulesRegister.unregisterWebApp(this, this.getServletConfig());
              }
}

Exemple de fichier WEB-INF/web.xml :

<web-app>
    <servlet>
       <servlet-name>InitEbxServlet</servlet-name>
                     <servlet-class>com.foo.RegisterServlet</servlet-class>
       <load-on-startup>1</load-on-startup>
    </servlet>
</web-app>

Enregistrement hors d'un serveur d'application

package com.foo;
import com.onwbp.base.repository.*;
/**
  */
public class RegisterMyModule
{
              public void register(File pathToModule)
              {
                            try
                            {
                                  ModulesRegister.registerDirectory(pathToModule);
                            } catch (ModuleDefinitionException e)
                            {
                                  // Handle exception
                            }
              }
}

Vérification de l'enregistrement

L'enregistrement et la désinscription sont historisés dans la catégorie de log EBX.Platform nommée "log.kernel".

 

Home > Engine & Repository