Home > Engine & Repository

Modules Packaging

An webMethods MDM Module allows the packaging of an adaptation model with additional resources (default message files, default formats, included XML Schemas, etc..)

On a J2EE application server, an webMethods MDM 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 webMethods MDM module with your application, in order to simplify deployment.

Structure

An webMethods MDM module contains the following files:

  1. /WEB-INF/mdm/
    This directory contains all description and configuration files for using webMethods MDM.
  2. /WEB-INF/mdm/module.xml
    This file defines the global properties of the module.
  3. /WEB-INF/mdm/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/mdm/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 webMethods MDM module integrated into a Web application:

Declaration
 

module.xml file

An module is declared with the file /WEB-INF/mdm/module.xml. This file declares the main properties of the webMethods MDM 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:mdm-schemas:module_2.1" xmlns:xsi ="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation ="urn:mdm-schemas:module_2.1 http://schema.softwareag.com/module_2.1.xsd">
              <name>mdm-unit0-1.0</name>
              <publicPath>optionalPublicPath</publicPath>
              <installerClassName>com.softwareag.mdm.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:mdm-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/mdm/module.xml.

Example in the file ‘module.xml’ :

<installerClassName>com.softwareag.mdm.wbp.testorg.unit0.Unit0Installer</installerClassName> 

The class must:

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

module.properties

An webMethods MDM module can redefine at its level the properties described in mdm.properties.

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

It allows to:

  • configure a log file specifically for the module ;
  • configure adaptation connectors mode (see mdm.properties)
  • configure the debug mode and page refresh if the module uses webMethods MDM navigation engine (only concerns webMethods Master Data Manager Web application)

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 mdm.properties
## Debug information appears on end-user web page.
###############################################
frontEnd.debugMode=false
###############################################
## Back-End Mode
## If not set, takes global mdm.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 mdm.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 not create a log file, comment in /WEB-INF/mdm/module.properties the lines that describe log categories.

Registration

In order to be identified by webMethods MDM, an module must be registered at runtime.

Registration of a Web application

For a Web application (inside an application server), every webMethods MDM module must:

  1. Contain a Servlet that registers the module by calling:
    com.softwareag.mdm.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 MDM, the schema(s) and the adaptation(s) that depend on it become unavailable (except the instances of the class Adaptation which are currently used - they are marked as obsolete).

Hot redeployment

webMethods MDM 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's procedure must be followed carefully.

Example

package com.foo;
import javax.servlet.*;
import javax.servlet.http.*;
import com.softwareag.mdm.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>InitMdmServlet</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.softwareag.mdm.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 webMethods MDM "log.kernel" category.

Packaging des Modules

Le module webMethods MDM 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 webMethods MDM 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 webMethods MDM et cette application afin d’en simplifier le déploiement.

Structure

Un module contient les fichiers suivants :

  1. /WEB-INF/mdm/
    Ce répertoire contient tous les fichiers de description et de configuration pour utiliser webMethods MDM.
  2. /WEB-INF/mdm/module.xml
    Ce fichier définit les propriétés générales du module MDM.
  3. /WEB-INF/mdm/dataModel.xsd
    Ce fichier définit le modèle d'adaptation par défaut du module MDM.
  4. /WEB-INF/web.xml
    Ce fichier J2EE assure l'enregistrement du module au lancement du serveur d'application (voir Enregistrement)
  5. /WEB-INF/mdm/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 resource).

Vue d’ensemble du module webMethods MDM intégré à une application Web :

Déclaration
 

Fichier module.xml

Un module webMethods MDM est déclaré via le fichier /WEB-INF/mdm/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:mdm-schemas:module_2.1" xmlns:xsi ="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation ="urn:mdm-schemas:module_2.1 http://schema.softwareag.com/module_2.1.xsd">
              <name>mdm-unit0-1.0</name>
              <publicPath>optionalPublicPath</publicPath>
              <installerClassName>com.softwareag.mdm.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:mdm-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/mdm/module.xml.

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

 

<installerClassName>com.softwareag.mdm.wbp.testorg.unit0.Unit0Installer</installerClassName> 

La classe fournie doit :

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

Fichier module.properties

Un module webMethods MDM peut redéfinir à son niveau certaines des propriétés globales décrites dans mdm.properties.

Cette redéfinition se fait dans le fichier optionnel /WEB-INF/mdm/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 mdm.properties)
  • configurer le mode debug et le rafraîchissement des pages dans le cas o le module utilise le moteur de navigation webMethods MDM (utilisé par l'application Web webMethods Master Data 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 quel 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 mdm.properties
## Debug information appears on end-user web page.
###############################################
frontEnd.debugMode=false
###############################################
## Back-End Mode
## If not set, takes global mdm.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 mdm.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/mdm/module.properties les lignes décrivant les catégories de log.

Enregistrement

Afin que le module soit identifié sur webMethods MDM, 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 webMethods MDM en appelant :
    com.softwareag.mdm.base.repository.ModulesRegister.registerWebApp(...).
    Voir exemple « com.foo.RegisterServlet » ci-dessous.
     
  2. La classe doit être effectivement définie par l'application Web (c'est à dire chargée via la classLoader de l'application Web). Ceci est nécessaire pour que webMethods MDM récupère le classLoader de l'application Web, dans les cas o des classes telles que des conecteurs 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 MDM, 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

webMethods MDM 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

package com.foo;
import javax.servlet.*;
import javax.servlet.http.*;
import com.softwareag.mdm.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>InitMdmServlet</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.softwareag.mdm.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 webMethods MDM nommée "log.kernel".

 

Home > Engine & Repository