Home > Engine & Repository

Repository Administration

This section specifies EBX.Platform repositories administration, including their installation and migration.

Technical Architecture

This section describes installation and deployment constraints.

Single repository per Java Virtual Machine (JVM)

A JVM that runs EBX.Platform is limited to a single EBX.Platform repository.

Single JVM per repository

A repository cannot be shared by several JVMs. If such a situation occurs, it may lead to unpredictable behaviors.

In this version, EBX.Platform does not ensure itself a locking that would guarantee the above constraint. Hence, it is the responsibility of the administrator to verify it.

Exception: several JVMs may share a single repository if all these JVMs do not perform updates on the repository.

Multiple repositories per relational database

EBX.Platform supports multiple repositories on a single relational database instance. This is possible by the specification of distinct tables prefixes (property ebx.persistence.table.prefix).

New repository installation

If the specified EBX.Platform connection has, on the relational database, the rights to create tables and indexes then the repository installation is done automatically. Otherwise, the administrator has to execute SQL scripts located in ebx.jar file at the following paths:

  • com/onwbp/adaptation/rep/rdb/oracle/ddl.sql for Oracle.
  • com/onwbp/adaptation/rep/rdb/db2/ddl.sql for DB2. Note that on DB2 Z/OS, the datatype BIGINT is defined from "version 9.1" and more. For the previous versions, we can use the datatype DECIMAL(19,0) instead of the datatype BIGINT. If we work with those Z/OS versions, we have to replace BIGINT by DECIMAL(19,0) in the above "ddl.sql" file.
  • com/onwbp/adaptation/rep/rdb/hsql/ddl.sql for HsqlDB.

If the property ebx.persistence.table.prefix has a specific value, the administrator should prefix the names of all the tables and indexes with this value.

Note that in the actual version of EBX.Platform, installation requires also an automatic migration (see below).

Automatic migration of the FileSystem

If the target database is empty and the source repository is correctly located, EBX.Platform performs an automatic migration of the source repository. It is launched when server is started up (more precisely when a first request triggers EBX.Platform cache initialization).

The process is the following:

  1. Install a new EBX.Platform environment. Its ebx.properties file must refer to a specific repository through properties ebx.persistence.factory, ebx.persistence.url and optionally ebx.persistence.table.prefix.
  2. Provide a source repository. The folder ebxRepository/Adaptation/ must contain a fileSystem_3.5 repository as the installation source.
  3. Optionally edit the file ebxRepository/Adaptation/.ebx-private. The value of property repositoryId must be changed so as to be unique in the enterprise (it must have 12 hexadecimal digits).
  4. Startup the new EBX.Platform environment and launch a Manager.

The migration will complete only if all schemas used by adaptations in the repository to migrate are correct (no validation errors).

This process allows to install several repositories on a single relational database instance (by means of the specification of distinct prefixes on property ebx.persistence.table.prefix).

Repository backup

Repository backup is delegated to the underlying RDBMS (Relational DataBase and Management System). The database administrator must use the standard backup procedures of the underlying database.

Repository attributes

A repository has the following attributes:

  • repositoryId. It identifies uniquely a repository (at least in the scope of the enterprise): it is 48 bits (6 bytes), and it is usually represented as 12 hexadecimal digits. This information is used for generating UUID (Universally Unique Identifier) of entities created in the repository and also of transactions logged in the audit trail (it plays the role of the «UUID node» part, as specified by RFC 4122).
  • repository label. It Provides a label for the user so that he knows the purpose and context of the repository (for example, «production environment»).
  • store format. It identifies the underlying persistence system, including the current version of its structure.

Datasource Configuration

The persistence datasource of the repository has to be configured by the administrator in the persistence part of ebx.properties file. He can configure the datasource either manually or by specifying a JNDI (Java Naming and Directory Interface) on his J2EE server that will define the connection to this datasource (for instance, see Oracle datasource configuration on WebSphere Application Server 6).

Archives directory

Archives are stored in a sub-directory named archives into ebx.repository.directory (see configuration). This directory is automatically created during the first export.

When creating manually this directory, be careful of the access rights: EBX.Platform process must have read and write access to it.

Nota bene: The file transfer between two EBX.Platform environments must be done outside the product. Tools such as FTP or simple files copies through network sharings (Windows, Samba, NFS, ...) are efficient.

Furthermore, cleaning the directory is not done by EBX.Platform and is the responsability of the administrator.

The following drawing illustrates this procedure:

o3

Monitoring

EBX.Platform is monitored through the monitoring of the J2EE application server.

The persistence datasource of the repository must be monitored through RDBMS monitoring.

Concerning file system, in order to guarantee the correct operation of the software, the disk usage and disk availability of the following directories must be supervised:

It is important to note that:

  • The cleaning of the directories above is not ensured by EBX.Platform. It is the administrator's responsibility.
  • For audit trail, if large transactions are executed with full updates detail activated (the default), the disk space needed can be quite large. For more information, see Audit Trail section.

See also configuration / tuning section.

Administration du référentiel

Cette section décrit l'administration des référentiels EBX.Platform, leur installation et leur migration.

Architecture technique

Cette section décrit les contraintes d'installation et de déploiement du référentiel.

Un référentiel unique par Machine Virtuelle Java (JVM)

Une JVM qui exécute EBX.Platform est limitée à un référentiel unique.

Une JVM par référentiel

Un référentiel ne peut pas être partagé par plusieurs JVMs. Si une telle situation se produit, cela peut conduire à des comportements imprévisibles.

Dans cette version, EBX.Platform n'assure pas de verrouillage qui garantirait la contrainte ci-dessus. Ainsi, il est de la responsabilité de l'administrateur de veiller au respect de cette contrainte.

Exception: plusieurs JVMs pourraient partager un référentiel unique si elles n'effectuent pas des mises à jour sur ce référentiel.

Plusieurs référentiels par base de données relationnelle

EBX.Platform supporte plusieurs référentiels sur une même instance de base de données relationnelle. Ceci est possible par spécification de préfixes de tables différents (propriété ebx.persistence.table.prefix).

Installation d'un nouveau référentiel

Si la connexion spécifiée par EBX.Platform dispose, sur la base de données relationnelle, des droits de création de tables et d'index alors l'installation du référentiel sur la base de données est exécutée automatiquement. Dans le cas contraire, l'administrateur devra exécuter les scripts SQL qui se trouvent dans le fichier ebx.jar aux emplacements suivants :

  • com/onwbp/adaptation/rep/rdb/oracle/ddl.sql pour Oracle.
  • com/onwbp/adaptation/rep/rdb/db2/ddl.sql pour DB2. Notons que sur DB2 Z/OS, le type BIGINT n'est supporté qu'à partir de la "version 9.1". Pour les versions inférieures, il est possible d'utiliser le format DECIMAL(19,0) en lieu et place du type BIGINT. Il faut donc remplacer le type BIGINT du fichier "ddl.sql" par le type DECIMAL(19,0), si on travaille avec des versions de Z/OS inférieures à la "version 9.1".
  • com/onwbp/adaptation/rep/rdb/hsql/ddl.sql pour HsqlDB.

Si la propriété ebx.persistence.table.prefix possède une valeur spécifique, l'administrateur devra au préalable préfixer les noms de toutes les tables et index avec cette valeur.

Notons que dans la version actuelle de EBX.Platform, l'installation nécessite également une migration automatique (voir ci-dessous).

Migration automatique du système de fichiers

Si la base de données cible est vide et le référentiel source est correctement situé, EBX.Platform effectue une migration automatique du référentiel source. Ceci est effectué au démarrage du serveur (plus précisément lorsqu'une première requête sollicite le cache d'initialisation de EBX.Platform).

Le processus est le suivant :

  1. Installer un nouvel environnement EBX.Pltaform. Le fichier ebx.properties doit faire référence à un référentiel spécifique à travers les propriétés ebx.persistence.factory, ebx.persistence.url et optionnellement ebx.persistence.table.prefix.
  2. Fournir un référentiel source. Le dossier ebxRepository/Adaptation/ doit contenir un référentiel fileSystem_3.5 comme source de l'installation.
  3. Optionnellement, éditer le fichier ebxRepository/Adaptation/.ebx-private. La valeur de la propriété repositoryId doit être changée afin d'être unique dans l'entreprise (elle doit avoir 12 chiffres hexadécimaux).
  4. Démarrer le nouvel environnement EBX.Platform et lancer EBX.Manager.

La migration se terminera seulement si tous les schémas utilisés par l'adaptation, dans le référentiel à migrer, sont corrects (pas d'erreurs de validation).

Ce processus permet d'installer plusieurs référentiels sur une instance de base de données relationnelle unique (par spécification de préfixes distincts sur la propriété ebx.persistence.table.prefix).

Sauvegarde du référentiel

La sauvegarde du référentiel doit être assurée par le SGBDR (Système de Gestion de Base de Données Relationnelles) sous-jacent. L'administrateur de la base de données doit utiliser les procédures standards de sauvegarde de cette base de données.

Attributs du référentiel

Un référentiel a les attributs suivants :

  • repositoryId. Il identifit de façon unique un référentiel (au moins au niveau d'une entreprise) : Il est codé sur 48 bits (6 bytes) et il est généralement représenté avec 12 chiffres hexadécimaux. Cette information est utilisée pour générer l'UUID (Universally Unique Identifier) des entités créées dans le référentiel et également des transactions enregistrées par la piste d'audit (cela joue le rôle de la partie « noeud UUID », comme spécifiée par le RFC 4122).
  • repository label. Il fournit un label pour l'utilisateur afin qu'il sache l'objectif et le contexte du référentiel (par exemple, « environnement de production »).
  • store format. Il définit le système de persistence sous-jacent, la version courante et sa structure.

Configuration d'une source de données

La source de données de persistance ou de sauvegarde du référentiel doit être configurée par l'administrateur dans la partie persistance du fichier ebx.properties. Il peut effectuer cette configuration de façon totalement manuelle, ou alors spécifier une JNDI (Java Naming and Directory Interface) sur son serveur J2EE qui va ainsi définir la connexion à cette source de données (à titre d'exemple, voir la configuration d'une source de données Oracle sur le Serveur d'Application WebSphere 6).

Répertoire de stockage des archives

Les archives sont stockées dans un sous-répertoire archives de ebx.repository.directory (voir configuration). Ce répertoire est créé automatiquement lors du premier export.

Il est néanmoins possible de le créer manuellement, auquel cas une attention particulière doit être apportée aux droits d'accès. Le processus qui exécute EBX.Platform doit pouvoir y lire et écrire.

Nota bene : Le transfert entre plusieurs référentiels EBX.Platform doit se faire indépendamment du produit. Pour ce transfert, des outils comme FTP, CFT, ou encore de simples recopies via des partages Windows, Samba ou NFS remplissent parfaitement ce rôle.

De même, le nettoyage de ce répertoire n'est pas assuré par EBX.Platform et est de la responsabilité de l'administrateur.

Le schéma ci-après décrit cette procédure :

o3

Supervision

La supervision de EBX.Platform s'effectue au travers de la supervision du serveur d'application.

La supervision du référentiel de la source de données s'effectue au travers de la supervision du système de SGBD retenu.

En ce qui concerne le système de fichiers, afin de garantir un fonctionnement correct du logiciel, l'utilisation et la disponibilité des disques doivent être surveillées pour les répertoires suivants :

Il est important de noter que :

  • Le nettoyage des répertoires sus-mentionnés n'est pas assuré par EBX.Platform. Il est de la responsabilité de l'administrateur.
  • Pour la piste d'audit, si des transactions volumineuses sont exécutées avec le détail activé des mises à jour effectuées (cas par défaut), l'espace disque utilisé peut augmenter rapidement. Pour plus d'informations, consulter la section Piste d'audit.

Voir aussi la section configuration / tuning.

 

Home > Engine & Repository