Objectifs, Rôle et contrats

Ce document présente le rôle du module moissonneur au sein du système ORI, ses interactions avec les autres modules, et un ensemble de documents de modélisation comportant les cas d'utilisations, une description des solutions techniques envisagés, un modèle de donnée, les diagrammes de classes et de séquences principaux.

L'objectif du système ORI-OAI dévolu à ce module est de constituer un corpus unique, cohérent et exploitable de fiches, à partir de différentes sources éparses, fiches concernant la description d'un document ou constituant ce document en tant que tel.

Le choix technique pour réaliser cet objectif est l'utilisation du protocole OAI-PMH, qui permet à diverses sources dépositaires d'un ensemble de documents, de disséminer sous forme de fiches au format contrôlé les méta-données descriptives de chaque document discret. Chaque format contrôlé détermine un type de ressource particulier, et chaque ensemble d'un même type peut faire l'objet d'un traitement particulier.

Le rôle de ce module est de moissonner des fiches OAI dans les multiples formats utilisés dans l'enseignement supérieur (LOM,TEF, CDM, Dublin Core...) via le protocole OAI, à partir d'un ensemble d'entrepôts OAI paramétrable.

A partir d'un entrepôt OAI, qui peut exposer plusieurs formats et comporter plusieurs ensembles OAI, la granularité d'une moisson telle que définie par ce module doit s'entendre comme une sélection de fiches, basée sur un ensemble de paramètres : format, ensembles, dates.

Le module permet donc de gérer un *ensemble de
moissons*, en offrant la possibilité d'en programmer l'exécution de manière répétée, et d'adopter une stratégie de mise à jour entre chaque occurrence d'une même moisson, visant à maintenir l'intégrité de l'ensemble de fiches issues de la moisson (fiches détruites, modifiées).

L' unité d'opération principale de ce module sera définie comme la moisson. Les autres objets pertinents du module sont l'enregistrement et la fiche.

Schéma global ORI-OAI

La moisson

La moisson désigne en même temps l'unité d'opération principale du module, et par extension, l'ensemble de fiches résultant de cette unité d'opération.

Caractéristiques

La moisson, au niveau le plus fin de sa granularité, est caractérisée par un ensemble d'attributs sélectifs, qui déterminent comme résultat un corpus de fiches : * l'entrepôt moissonné

• le format - sélection minimale obligatoire.
• le ou les ensembles - optionnel
• la ou les dates, définissant soit une limite inférieure, supérieure, ou un intervalle - utilisées pour les mises à jour.
  Le module maintient de façon persistente la relation entre toute fiche moissonnée et ses caractéristiques de moisson.

  Contrats

L'exécution de la moisson se décompose en deux phases, qui remplissent deux contrats : * Le stockage de fiches dans une base de données
-> un point d'accès à ces fiches au module d'indexation ORI-OAI-indexing remplit le contrat "stockage des fiches".

• l'indexation d'un ensemble paramétrable de champ pour chaque type de fiche par le module d'indexation
  -> assure le contrat "référencement d'une fiche moissonnée au sein du système par indexation".

Les modalités d'éxécution de ces contrats comprennent deux aspects : * la programmation de l'exécution répétée à intervalles paramétrables de la moisson

• la relation entre deux répétitions d'une même moisson, à savoir un mode de mise à jour, dépendant des caractéristiques de l'entrepôt moissonné.
  La mise à jour consiste à répercuter les changements possible dans l'ensemble de fiches représenté par la moisson : création, modification, suppression.
  Ce dernier type de changement, la suppression, est tributaire du mode de gestion des fiches supprimées de l'entrepôt moissonné, parmis les trois qui sont définies par le protocole OAI-PMH à travers l'attribut "deletedRecord"..
  Il en découle deux modes de mise à jour possibles :
  • gestion persitente (deletedRecord="persistent") :une *mise à jour
    incrémentale* peut être exécutée pour tous les types de changement, où le module traite chaque enregistrement dont la date est postérieure à la date de mise à jour précédente : remplacement des enregistrements marqués comme "deleted" dans la base de donnée et supression de leur entrée dans l'index, et insertion des autres enregistrements.
    • La suppression s'entend du retrait de la fiche de la base de donnée,(et de son remplacement par un enregistrement "deleted"), et du retrait de l'entrée correspondante dans l'index.
    • L'insertion s'entend comme l'ajout de la fiche dans la base de donnée et son indexation par le module ORI-OAI-indexing.
  • pas de gestion (deletedRecord="no" ou "transient") : une mise à jour mixte, incrémentale pour les fiches créées et modifiées, et une mise à jour comparative pour les enregistrements supprimés.
    Cette dernière est réalisée par comparaison entre l'ensemble des fiches stockées issues de la moisson précédente et l'ensemble des fiches d'une nouvelle moisson limitée à la date de la moisson précédente. Le delta de ces ensembles permet de définir une liste de fiches à supprimer.
    Note : Si le mode est "transient", on recoupe cette liste avec les éventuels enregistrements marqués "deleted" d'une moisson incrémentale, en gardant priorité à ces derniers pour conserver l'information de la date de suppression. En absence d'enregistrement "deleted" d'une moisson incrémentale, la mise à jour comparative aura à charge de créer cet enregistrement pour chaque enregistrement supprimé, avec la date de la moisson.

L'enregistrement

On appellera "enregistrement" l'ensemble de la structure XML "record" définit par le protocole OAI, auquel le module applique son traitement, ou encore la structure XML "ori-record" qui encapsule cette dernière.

La fiche

Lorsque l'on parle de "fiche", cela désigne plus précisément la section "metadata" de la structure "record", qui est récupérée isolément de l'enregistrement par les autres modules.

Note : Le module, pour chaque fiche, stocke l'ensemble de l'enregistrement OAI, donc la fiche ne se distingue pas en tant qu'élément autonome. Au sein du module, la fiche est une partie de l'enregistrement.

Cas d'utilisation

Cette section décrit les cas d'utilisation concrets qui impliquent ce module. Ces cas d'utilisation concernent aussi bien l'interaction de l'utilisateur avec le système, que les interactions entre les différentes parties du système, issues de la programmation faite par l'utilisateur.

Définition et paramètrage d'une moisson

L'utilisateur peut définir et paramétrer le sous-système "moissonneur" pour effectuer un ensemble de moissons, telles que définies précédemment. Une fois ce paramétrage injecté dans le module, ce dernier gère les différents moments de son exécution.

Stockage des caractéristiques de la moisson

Les caractéristiques de chaque moisson définie par l'utilisateur sont stockées dans une collection de la base de données, en correlation avec un identifiant de moisson généré par le système.

Stockage des enregistrements OAI

Dans un premier temps, le moissonneur accède aux entrepôts selon les caractéristiques définies pour la moisson, et récupère un ensemble d'enregistrements, qui sont stockées dans une base de données. Le stockage inclut une relation constante entre les fiches et les caractéristiques de la moisson, à fins de gestion des mises à jour et d'exposition sélectives des fiches moissonnées.

Le module modifie , soit au niveau stockage, soit au niveau accès, le nom (setSpec) des ensembles natifs associés aux enregistrements OAI, en leur ajoutant un préfixe "ori-import:[", ceci afin de distinguer ces ensembles natifs des ensembles gérés par le module ORI-OAI-Repository, lors de la ré-exposition des métadonnées.

Elements de l'enregistrement stockés

Cas nominal : l'enregistrements moissonné complet est stocké (header, metadata et about)

Cas dégradé : quand il s'agit d'un enregistrement supprimé, seul le header est stocké.

Identifiant unique de l'enregistrement

L'identifiant utilisé est l'identifiant de l'enregistrement OAI moissonné :

•  associé au namespace du format de la fiche lors de l'indexation.
• associé au préfixe du format de la fiche lors du stockage dans la base du moissonneur.

L'identifiant seul est partagé par les différents formats, ce qui permet la notion abstraite de format englobant.

Relation de l'enregistrement à une moisson caractérisée

Chaque fiche est associée à l'identifiant de la moisson dont elle est issue, par l'affectation de cet identifiant à un attribut stocké en même temps que l'enregistrement.

Emplacement du stockage de la fiche

Cas nominal : par défaut, l'enregistrement est stocké dans la collection nommé avec le préfix OAI de son format, sous la racine de la collection des moissons.

Cas dégradé : un emplacement peut être spécifié par l'utilisateur dans le paramétrage de la moisson.

Programmation d'une moisson

L'utilisateur peut définir une programmation pour chaque moisson ou pour un ensemble de moisson.

Moisson ponctuelle

L'utilisateur peut choisir de définir une moisson comme ponctuelle, dont l'exécution est immédiate et unique.

Moisson avec mise à jour périodique

L'utilisateur peut définir, pour une moisson ou un ensemble de moisson, une exécution répétée, définie par les paramètres suivants :

• Date de première exécution
• Fréquence de répetition

Exécution d'une moisson

Moisson initiale

Le moissonneur, à la première moisson, traite l'ensemble des fiches resultant de ses caractéristiques. Ce traitement comporte le stockage dans une base de données et l'indexation.

Stockage dans la base de donnée

Le stockage de chaque fiche se déroule selon le paramétrage de l'utilisateur décrit dans la section précédente.

Indexation des fiches

L'indexation d'une fiche comporte, outre les métadonnées de son format, son identifiant, le préfixe de son format, et le nom de son entrepôt d'origine. Le moissonneur transmet ces informations au module ORI-OAI-indexing.

Mise à jour des enregistrements OAI

Aprés la moisson initiale, toute réitération se comporte comme une mise à jour. Cette mise à jour consiste à traiter la création, modification et suppression de fiches depuis la moisson précédente.

Création de fiches

Chaque nouvelle fiche est stockée et indexée comme lors d'une moisson initiale.

Modification de fiches

Chaque fiche modifiée est remplacée dans la base de donnée en utilisant l'identifiant de l'enregistrement et le préfixe de son format, et ré-indexée.

Suppression de fiches

• Cas nominal : l'entrepôt OAI à un mode de gestion des fiches supprimées persistant.
  Chaque fiche indiquée comme "deleted" remplace la fiche du même identifiant et du même format dans la base. L'entrée dans l'index est supprimée.

• Cas dégradé : l'entrepot OAI n'a pas de mode de gestion des fiches supprimées persistant.
  Par comparaison des fiches stockées et des fiches fraichement moissonnées, une liste des fiches à supprimer est constituée, et pour chaque fiche concernée, le système remplace la fiche dans la base de donnée par une fiche "deleted" du même identifiant et du même format. L'entrée dans l'index est supprimée.

Supression d'une moisson

L'utilisateur peut supprimer une moisson selon plusieurs acceptions :

Suppression des fiches d'une moisson

L'utilisateur peut supprimer l'ensemble des fiches issues d'une moisson, sans supprimer ses caractéristiques du système.

Suppression des caractéristiques d'une moisson

L'utilisateur peut supprimer la définition d'une moisson injectée dans le système.

Suppression d'une programmation

L'utilisateur peut supprimer la programmation affectée à une moisson ou à un ensemble de moisson. Le module cessera les mises à jour définies par cette programmation.

Recherche d'enregistrements par un utilisateur via ORI-OAI-search

et ORI-OAI-indexing
L'utilisateur interagit avec le système pour rechercher un ensemble d'enregistrement correpondant à sa requête. Le sous-système intervient pour délivrer chaque fiche concernée par le résultat.

Récupération des fiches concernés par une recherche par leur

identifiant
Le module d'indexation demande à ce module une fiche ou un ensemble de fiches en lui transmettant le ou les identifiants de celles-ci, ainsi que le préfixe du format requis.

Moissonnage des fiches moissonnées

Un utilisateur moissonne les fiches moissonnées par le système ORI, via une requête OAI. Le sous-système intervient pour délivrer l'ensemble des fiches correspondant aux critères OAI retransmis par ORI-OAI-repository.

Gestion des resultats de moisson

Les resultats de moisson utilisent une strucutre mettant en relief les différents niveaux (ensemble de listes, liste, enregistrement) et les différentes caractéristiques permettant de définir l'état de chaque niveau.

Dans le diagramme suivant :

• ListResult représente l'état global des operations sur une liste de fiche
• ActionResult représente l'état d'une action au niveau d'une fiche
• IndexResult et StorageResult représentent les sous-états de la fiche pour chaque type d'opération

Interactions avec les autres modules

Des interactions avec les autres modules se définissent d'aprés les cas d'utilisations précédents : * Exposer les fiches moissonnées au protocole OAI-PMH
Il est assuré par le module ORI-OAI-repository, lequel accède aux fiches stockées via un service fourni par le module : *** un service getRecord(recordID, metadataPrefix)

• Exposer des ensembles de fiches selon les caractéristiques de moisson(dates, format, entrepôt, ensembles).
  La constitution d'ensembles OAI (set) est à la charge du module ORI-OAI-repository. Cependant, le moissonneur doit prévoir de garder la trace des ensembles utilisés pour la moisson, que l'on nommera "ensemble natifs", ainsi que de l'entrepôt d'origine de la fiche. Ces informations pourront être exploitables via un service fournis par le module : *** un service GetRecordsID(from, until, SetSpec, metadataPrefix, storageID)

• Retrouver une fiche associée à un résultat de recherche
  Il est assuré par le module ORI-OAI-indexing, lequel accède aux fiches stockées via un service fourni par le module : *** un service getMetadata(recordID, metadataPrefix)

• Indexer une fiche OAI
  Il est assuré à l'initiative du moisonneur par appel d'un service requis du module ORI-OAI-indexing : *** un service indexRecord

Les sections suivantes recensent l'ensemble des services que le module ORI-OAI-harvester doit fournir aux autres modules dans le cadres de ces interactions, suivi de l'ensemble des services que ce module requiert des autres modules.

Services requis par le module

Services requis du module ORI-OAI-indexing

Service indexRecord

• cas d'utilisation : moisson d'un entrepôt OAI
• rôle : indexer une fiche de métadonnée
• utilisateurs : ORI-OAI-harvester
• paramètres :
  • metadata: section XML contenant les métadonnées d'un enregistrement. *Obligatoire*
  • prefix : préfixe du format de la fiche
  • recordID : identifiant de l'enregistrement contenant les métadonnées indexées.
  • storageID : identifiant de l'entrepôt moissonné duquel est issue la fiche.
• retour : un code déterminant le résultat de l'indexation

Remarque : toutes ces données sont transmises à l'indexation en tant qu'élements à indexer, à des fins d'utilisation concréte par le module de recherche. Seul le recordID, qui est la clé qui relie les deux modules, est utilisé pour retrouver la fiche.

Service deleteRecord

• cas d'utilisation : moisson d'un entrepôt OAI (mise à jour)
• rôle : supprimer l'entrée dans l'index correspondant à une fiche "deleted"
• utilisateurs : ORI-OAI-harvester
• paramètres : ** recordID : identifiant de l'enregistrement contenant les métadonnées indexées.

Modèle de donnée

Un modèle de donnée s'appuyant sur une base relationnelle repose sur un modèle entité-relation, qui se concrétise par des tables avec des clés primaires et secondaires, ou encore des tables d'association. Pour une base XML, les entités sont concrétisées par des structures XML(documents ou noeuds), et les relations entre ces entités seront définies à travers des attributs servant de clés. Dans ce contexte, les requêtes XQuery remplacent les requêtes SQL.

• La relation entre entrepôt et fiche est assurée par l'attribut ori-record/@repositoryName de la fiche et l'attribut oaistore/@repositoryName de la définition de la moisson.

• La relation entre moisson et fiche est assurée par l'attribut ori-record/@rharvestID de la fiche et l'attribut harvest/@id de la définition de la moisson.

Structures XML

Entités de configuration

Suit la description des entités servant à la configuration. Chaque description est de la forme : Nom - Description. * HarvestConfig - Définition d'une moisson

<harvest id="harvest1" onLaunch="false" metadataPrefix="lom" collection="lom" from="2006-11-08">
   <oaistore url="http://cas.enseeiht.fr/injac-oai/OAIHandler"/>
   <schedule cron="0 30 23 * * ?"/>
</harvest>

Entités d'information

Les entités d'information sont générées au cours des différentes actions. Chaque description est de la forme : Nom - Description - Action(s) impliquées. * OAIStoreInfos (FormatInfos*, SetInfos*) - Informations sur l'entrepôt OAI - Création ou enregistrement d'une définition :

• HarvestReport (CollectReport*) - Rapport de moisson - Moisson
• CollectInfos (CollectStoreInfos*) - Etat des récoltes - Administration

Entités de production

Ce sont les entités produites par le module. Chaque description est de la forme : Nom - Description - Action(s) productrice(s).

• ORIRecord - fiche ORI-OAI représentant un enrobage de la fiche OAI - Moisson :

  <ori:ori-record xmlns:ori="http://ori-oai.org/ORI/1.0/" repositoryName="INP ENSEEIHT" harvestID="harvest1" ORI_id="xxx">
     <oai:record/>
  </ori:ori-record>
  

Requêtes XQuery

Voci quelques modèles de requêtes XQuery utilisées par le module, qui définissent les relations entre les entités :

• liste des identiants ORI-OAI pour un entrepôt et un préfixe donné :

  declare namespace oai="http://www.openarchives.org/OAI/2.0/";
  declare namespace ori="http://ori-oai.org/ORI/1.0/";
  
  
  for $item in //ori:ori-record[@repositoryName ='INP ENSEEIHT' and contains(name(./oai:record/oai:metadata/*[1]),'lom')] return
  <identifier>
  {$item/@ori_ID}
  </identifier>
  

• liste des identiants ORI-OAI pour une moisson et un entrepôt donnés : relation entre moisson et fiche

  for $item in //ori:ori-record[@repositoryName ='INP ENSEEIHT' and @harvestID='harvest1']
  

L'identifiant ORI_id premet de retrouver une fiche d'un format précis pour un document donné. Il sert également de nom de ressource à l'intérieur de la base XML. Cependant, ce nom de resources interdit l'usage de certains caractères, aussi une conversion à lieu pour faire l'aggrégation préfixe + OAI id (classe org.ori.harvesting.IDConverter).

Algorythme de mise à jour

persistent :

• on distingue les fiches modifiées et crées des fiches supprimées par l'élément status=deleted (from)
• pour chaque ensemble on applique les traitement d'ajout mise à jour ou de suppression

transient :

• on distingue les fiches modifiées et crées des fiches supprimées par l'élément status=deleted (from=last)
• on ajoute/met à jour les fiches du premier ensemble, et on supprimes celles qui sont indiquées comme telles
• on compare les fiches until=last de l'entrepôt avec les fiches until=last précédemment moissonnèes, et on supprime les fiches appartenant au delta

no

• on ajoute/met à jour les fiches de l'ensemble from=last sans distinction
• on compare les fiches until=from de l'entrepôt avec les fiches until=from précédemment moissonnèes, et on supprime les fiches appartenant au delta

Scenarii de test

Tests unitaires

Moisson initiale

Une première moisson est lancée, pour laquelle il faut vérifier ques les fiches moissonnées ont bien été stockées.

Mise à jour de moisson d'un entrepôt non-persistent

Le test nécessite les phases suivantes :

• Une moisson initiale est réalisée avec n document
• Une mise à jour est opérée a n documents
• Une mise à jour est opérée a n+x documents
• Une mise à jour est opérée a n-x documents

Diagramme de package

Ce diagramme présente les différents packages du module, et leurs interactions :

Diagramme de classe

• Diagramme général :
  Dans ce diagramme, les trois classes de services qui sont au centre assurent tous les services du module :
  • ProviderService expose des Web Services utiles aux autres modules
  • HarvestService présente des services internes, masquant la logique métier au contrôleur.
  • SchedulerService présente des services internes pour l'exécution des tâches programmées.

• Réalisations d'interfaces :
  
• Ce diagramme présente les implémentations fournies pour les interfaces utilisées :
  • IRecordStorage et IConfigStorage sont les interfaces de la DAO. Les impléme,ntations fournies concernent une base XML et utilisent Spring XML DB.
  • ISchedulerService est une interface pour gérer les tâches programmées. L'implémentation fournie utilise Quartz.
  • IIndexerInvoker est une interface pour l'indexation des fiches. L'implémentation fournie utilise Codehaus XFire.

• Vues et controleurs
  Trois types de vues sont prévues pour l'IHM du moissonneur, correspondant à trois controleurs :
  • les vues concernant les *définitions* des moissons utiliseront le controleur HarvestController
  • les vues concernant les récoltes produites par les moissons utiliseront le controleur CollectController
  • les vues concernant les rapports des moissons utiliseront le controleur ReportController.

Diagrammes de séquences

Voici les diagrammes de séquences principaux du module :

• Création du HarvesterManager :
  

• Moisson OnLaunch :

  !Moisson_OnLaunch_SD.jpg|width=32,height=32!* Moisson programmée :

Idées d'évolutions futures

• Intégrité/validation
  • tester si la tâche programmée est compatible avec la granularité de l'entrepôt. (1 tache par jour max pour les granularité YYYY-MM-DD)

• rapports
  • Exportation des rapports, diagrammes