Pré-requis

JDK

Le moissonneur ORI-OAI est une application Java fonctionnant avec un JDK 1.5 ou JDK 1.6 (recommandé). La variable d'environnement JAVA_HOME doit exister et pointer sur le répertoire d'installation du JDK.

Toutefois, si cette variable pointe sur un autre JDK, les scripts ant.bat (pour Windows) et ant.sh (pour Linux) sont fournis, dans lesquels vous pouvez définir l'emplacement d'une JDK 1.5 utilisée de façon alternative pour le moissonneur.

ANT

Les tâches de compilation, de déploiement et certaines actions utilisent ANT 1.6. La variable d'environnement ANT_HOME doit exister et pointer sur le répertoire d'installation de ANT.

Tomcat

Une version de Tomcat 6 doit être disponible sur la machine de déploiement, et la variable d'environnement CATALINA_HOME doit être définie pour pointer son emplacement.

Pour assurer l'application de fonctionner avec l'encodage UTF-8, il ajouter cette ligne dans le fichier startup.sh ou catalina.sh (répertoire tomcat-xxx/bin) : export CATALINA_OPTS="-Dfile.encoding=UTF-8 $CATALINA_OPTS"

Stockage et indexation des moissons

A partir de la version 1.4, le module ORI-OAI-harvester intègre une seule forme de stockage SQL, et délaisse l'implémentation XML trop longue à maintneir en parallèle et non utilisée. Pour une migration depuis la base XML, utiliser la version 1.1.3. L'outil de migration se limite toutefois à exporter les définitions de moissons, l'utilisateur devant ensuite lancer chaque moisson une par une afin de reconstituer les récoltes et de les ré-indexer.

Le moissonneur intègre deux formes de traitement des moissons :

Le stockage se fait dans une base relationnelle, configurable dans le fichier ori.properties avec les paramètres de connexion adéquats (voir section plus bas).

Une base doit donc être prélablement crée*. Pour MySQL, on s'assurera qu'elle soit de type InnoDB afin de gérer les transactions. Pour ce faire, le fichier my.cnf doit comporter, selon la version, une des deux lignes suivantes :
Versions récentes de MySQL :

default-storage_engine = innodb

Versions anciennes de MySQL :

default-table-type = innodb

Ligne de création pour MySQL :

create database `ori-harvester` DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci;

* L'indexation des métadonnées dans un index Lucene : une installation préalable du module d'indexation ORI-OAI-INDEXING, doit donc être dispônible en accès HTTP depuis le moissonneur. La documentation technique des modules ORI-OAI est disponible sur le wiki.
Voir la section Configuration du service d'indexation pour plus de détails.

Migration

Pour effectuer une migration depuis une installation antérieure vers la version 1.1, il faut simplement configurer le partie eXist du fichier ori.properties et la partie SQL, et ensuite lancer les target :

ant init

ant upgrade

ant upgrade produit les modifications nécessaires à la base de données entre deux versions : elle marche conjointement avec l'attribut upgrade.fromVersion du fichier init-build.properties, que vous devez renseigner AVANT de lancer cette target.

Dans le cas d'une migration de la version 1.0 à 1.1.0, cette dernière target ANT transfert les définitions de moissons de votre base eXist vers la nouvelle base SQL, initialisée par ant init. Dans les autres cas elle fait les modifications de tables éventuelles de la base SQL nécessaires à la nouvelle version.

Migration 1.5 vers 1.6

La tâche ant upgrade détruit les récoltes moissonnées de la base du harvester mais ne les désindexe pas. Parallèlement, il faut donc également vider l'index qui contient les anciennes moissons (voir la documentation sur la migration en 1.6 ).

Précision sur l'utilisation du fichier common-parameters.properties :

Dans le cadre d'une installation manuelle, il faut renseigner la propriété fromVersion du fichier build.properties avec la valeur 1.5.0 pour que la tâche ant upgrade fonctionne correctement, sans quoi la mise à jour de la base de donnée n'operera pas :

# optional - needed for upgrading from a previously installed version
upgrade.fromVersion=1.5.0

Ceci fait, la commandes ant upgrade délivre les informations dans la console qui doivent ressembler à ce qui suit :

 [input] Warning. You're going to upgrade ORI-OAI-Harvester database from 1.5.0 to 1.6.0. You should backup your database before performing changes.  (y, n)
y
     [java] upgrade
     [echo] upgrade sucessfull

upgrade-db-data:
     [java] fromVersion=1.5.0
     [java] toVersion=1.6.0
     [java] fromVersion=1.5.0
     [java] toVersion=1.6.0
     [java] oriharvester: 0 org.orioai.harvesting.domain.service.MigrationService.migrate15to16(MigrationService.java:120)  - migrating config INP Toulouse Theses to SQL database
     [java]  oriharvester: 84 org.orioai.harvesting.domain.service.MigrationService.migrate15to16(MigrationService.java:129)  - migrate ok for INP Toulouse Theses
     [java]  oriharvester: 84 org.orioai.harvesting.domain.service.MigrationService.migrate15to16(MigrationService.java:120)  - migrating config le serveur des th&#xE8;ses en ligne de l'INSA de Toulouse to SQL database
     [java]  oriharvester: 118 org.orioai.harvesting.domain.service.MigrationService.migrate15to16(MigrationService.java:129)  - migrate ok for le serveur des th&#xE8;ses en ligne de l'INSA de Toulouse
     [java]  oriharvester: 121 org.orioai.harvesting.domain.service.MigrationService.migrate15to16(MigrationService.java:120)  - migrating config oatao to SQL database
     [java]  oriharvester: 299 org.orioai.harvesting.domain.service.MigrationService.migrate15to16(MigrationService.java:129)  - migrate ok for oatao
     [java]  oriharvester: 300 org.orioai.harvesting.domain.service.MigrationService.migrate15to16(MigrationService.java:120)  - migrating config thesesups to SQL database
     [java]  oriharvester: 345 org.orioai.harvesting.domain.service.MigrationService.migrate15to16(MigrationService.java:129)  - migrate ok for thesesups
     [java]  oriharvester: 26147 org.orioai.harvesting.domain.service.MigrationService.migrate(MigrationService.java:110)  - migration achieved from 1.5.0 to 1.6.0
     [java]

Note : en fonction du nombre de fiches que vous avez moissonnées, cette tâche peut durer assez longtemps (jusqu'à plusieurs minutes).

Une fois ces opérations effectuées, il est nécessaire de relancer les moissons (une fois le serveur Tomcat redémarré) afin des les ré-indexer.

Comme dit plus haut, cette moisson devra se faire après l'étape de réinitialisation de l'index de ORI-OAI-indexing décrite sur la documentation générale de la migration en 1.6. Vous trouverez plus d'information sur la gestion de l'index ici.

Configuration et installation manuelle du moissonneur

Une possibilité de configuration centralisée permet de changer automatiquement la valeur de certains paramètres entre crochets et en majuscules, grâce à la configuration du module quick-install. Les fichiers build.properties et ori.properties sont concernés. Ainsi, vous avez le choix entre une installation "par module" où vous devez créer et editer ces fichiers à partir de init-build.properties et conf/properties/ori.example.properties, et une installation "centralisée" où ces fichier seront automatiquement générés lors de la compilation et du déploiement. Les sections suivantes décrivent l'installation "par module", pour l'installation centralisée, se reporter en plus à la documentation du quick-install. Les paramètres ne figurant pas entre crochets peuvent de façon facultative être changés à la main.

L'installation se fait en 4 étapes :

1. configuration du fichier build.properties

Un fichier build.properties doit être crée par recopie de init-build.properties.
Il faut indiquer l'endroit ou l'on veut installer l'application, l'emplacement du Tomcat, ainsi que l'emplacement d'un JDK 1.5+. Les paramètres entre crochet sont à modifier, ou seront modifés par la configuration centrale du quick-install :

#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#
## 2) Installation manuelle du module
# Dans ce cas, il est nécessaire de commenter
# le paramètre commons.parameters.central.file.url
#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#

# Cette partie du fichier doit être mise à jour avant
# la première utilisation de votre application dans votre environnement

#JDK 1.5 directory
java.home=[JAVA_HOME]
#Tomcat directory
tomcat.home=[PATH_TOMCAT_HARVESTER]
#Deployment directory
deploy.home=[PATH_TOMCAT_HARVESTER]/webapps
#Nom de ditribution de l'application - distribution name
app.name.deploy=[CONTEXT_HARVESTER]

#Log Directory (optionnal - default : ${tomcat.home}/logs )
#log.dir=E:/logs
#Log mode : prod or debug
log.mode=prod
# optional - needed for upgrading from a previously installed version
upgrade.fromVersion=[HARVESTER_UPGRADE_PREVIOUS_VERSION]

1. Les chemins utilisant des anti-slashes comme sous Windows, doivent s'écrire soit avec un double anti-slash soit avec un slash, comme sous Linux.
2. si le JAVA_HOME de la machine n'est pas par défaut un JDK 1.5, il faut indiquer le chemin d'un jdk 1.5+ dans le fichier ant.bat (pour Windows) ou ant.sh (pour Linux).
Mise à jour de la base de données : indiquer la version depuis la quelle vous faites la mise à jour. La tâche ant upgrade fera les modifications en fonction de cette valeur

2. Adapter les fichiers du répertoire properties

Les fichiers de propriétés sont situés dans le répertoire conf/properties à la racine du projet :

Configuration rapide

Le fichier définissant les traces de l'application (log4j.properties) est produit automatiquement lors du déploiement de l'application.
Un fichier ori.properties*doit être créé* à partir de l'exemple ori.example.properties, dans lequel les valeurs entre crochet doivent être adaptées à la main si le quick-install n'est pas utilisé :

# propertie file for ORI Harvester

############### Database Section ################
hibernate.connection.driver_class=[HARVESTER_SQL_DRIVER_CLASS]
hibernate.connection.url=[HARVESTER_SQL_CONNECTION_URL]
hibernate.connection.username=[HARVESTER_SQL_USERNAME]
hibernate.connection.password=[HARVESTER_SQL_PASSWORD]
hibernate.properties.dialect=[HARVESTER_SQL_DIALECT]


#harvester global options

# set to true each time you want to update database with XML config file
harvester.reloadconfig=false
# optional - if reloadConfig = true
harvester.initconfig=[PATH_TOMCAT_HARVESTER]/[CONTEXT_HARVESTER]/WEB-INF/config/harversterConfig.xml

#indexing
indexing.ws.wsdlDocumentUrl=http://[HOST_INDEXING]:[PORT_INDEXING]/[CONTEXT_INDEXING]/xfire/IndexingService?WSDL
indexing.ws.lookupServiceOnStartup=false

#enable filtering local records (must match ORIRecordFactory.repositoryIdentifier property of your repository)
local.repositoryIdentifier=[REPOSITORY_IDENTIFIER]

# set to true ONLY if you want to harvest in spite of unreachable indexing Web Service
indexing.ignore.error=false

# if true, persist deleted OAI records in database
storage.persistDeleted=true

# Define proxy parameters here (for external  WS access to indexer or stores) or leave blank if no proxy
# example :
#	proxy.host=proxy-rech.my-univ.fr
#	proxy.port=3128
proxy.host=[PROXY_HOST]
proxy.port=[PROXY_PORT]

# ensure that this directory has correct rights (read/write) set for tomcat process owner
index.directory=[INDEXES_DATA_DIR]/index-harvester

La signification de ces valeurs :
harvester.reloadconfig : si vous choisissez de définir des moissons par le biais d'un fichier XML, il faut positionner cette valeur à TRUE au premier lancement, et à FALSE ensuite. Si il est à FALSE , le fichier défini par le paramètre harvester.initconfig ne sera pas lu.
harvester.initconfig : emplacment du fichier de pré-configuration de moissons.
indexing.ws.url : URL du Web Service du moteur d'indexation
local.repositoryIdentifier : identifiant du repository local (doit correspondre au paramètre ORIRecordFactory.repositoryIdentifier du fichier ori-oaicat.properties)
*exist.url * : url de la base eXist servant au stockage des fiches (jusqu'à version 1.0)
exist.login et exist.password : login et mot de passe d'un utilisateur autorisé à se connecter sur la base définie par le paramètre exist.collection
exist.collection : nom de la collection racine utilisée par le moissonneur dans la base XML.
storage.persistDeleted : à TRUE, les enregistrements supprimés seront conservés dans la base XML, à FALSE, effacés
proxy.host et proxy.port : paramètres du proxy le cas échéant pour l'accès aux services extérieurs.
index.directory : répertoire où sera créé l'index temporaire lors des moissons multi-sets (doit être accessible en lecture/écriture depuis le processus Tomcat)

Configuration avancée

Les fichiers de configuration Spring et JSF (dont la liste suit) permettent de configurer l'application d'une façon plus poussée et plus personnalisée, si le besoin s'en fait sentir.

faces-config.xml permet de modifier les régles de navigation et de déclarer des composant JSF personnalisés (avancé)
harvester-dao.xml définit la couche d'accès aux données (ici base XML eXist)
harvester-domain.xml contient les objets des services métiers
harvester-quartz.xml régle la partie "tâche programmée" de l'application (avec le fichier quartz.propeties qu'il référencie)
harvester-ws.xml gère les accès aux Web Services
servlet-applicationContext.xml est le fichier principal Spring
tiles-def.xml sont les templates de pages TILES utilisés dans l'IHM.
faces-config.xml permet de modifier les régles de navigation et de déclarer des composant JSF personnalisés (avancé)

Enfin, le fichier de log peut être personnalisé en modifiant le fichier log4j.prod.properties en mode production ou log4j.debug.properties en mode développement/ déboggage.

3. Configurations avancées (optionnel)

Définir un fichier de pré-configuration pour les moissons. Cette étape est optionnelle, les moissons pouvant plus confortablement être définies par l'IHM une fois l'application lancée.
Se reporter à la cette page.

4. Déploiement

Lancer les target *ant * suivantes :

ant init

ant all

Vous pouvez alors accéder à l'interface Web avec le contexte ori-harvester, par exemple : http://localhost:8080/ori-oai-harvester

Harvester - Installation avancée