SDX et la moisson OAI

On peut déclarer un moissonneur OAI en utilisant l'élément sdx:oai-harvester ainsi :

  <sdx:documentBase>
    <sdx:oai-harvester adminEmail="quelquun@quelquepart.com unautre@ici.fr">
      ...
    </sdx:oai-harvester>
  </sdx:documentBase>

L'attribut adminEmail permet de préciser l'adresse de courrier électronique des administrateurs de ce moissonneur. Ce n'est pas obligatoire mais fortement recommandé par les bonnes pratiques associées à l'OAI. Plusieurs adresses peuvent être spécifiées si elles sont séparées par une espace.

La seconde étape consiste à spécifier quels sont les entrepôts OAI à moissonner, et de quelle façon. C'est la partie la plus complexe, mais cela reste de la simple configuration. Tout d'abord, voici comment on identifie un entrepôt :

  <sdx:oai-harvester>
    <sdx:oai-data-providers>
      <sdx:oai-repository url="url de base de l'entrepôt OAI à moissonner" granularity="granularité utilisée par l'entrepôt">
        ...
      </sdx:oai-repository>
    </sdx:oai-data-providers>
  </sdx:oai-harvester>

On voit donc qu'un entrepôt est entièrement spécifié par une URL de base, que l'on indique tout simplement dans l'attribut url, et le type de granularité utilisée par l'entrepôt indiquer par l'attribut granularity. Par défaut, SDX emploie la granularité à la seconde (YYYY-MM-DDThh:mm:ssZ). A noter qu'un attribut ref peut également être spécifié, mais il n'est pas documenté pour l'instant, en attente de stabiliser le code à cet égard.

L'étape suivante consiste à renseigner à quel moment ou à quelle fréquence SDX doit démarrer une opération de moisson. C'est l'élément sdx:update qui permet de le faire, et il peut y en avoir un seul. SDX supporte deux types de spécifications de mise à jour, soit le type périodique et le type cron.

Le type périodique permet de simplement spécifier une fréquence de mise à jour qui sera calculée à partir du démarrage de SDX. Par exemple, si on indique une période de 1 heure avec un décalage de 10 minutes, cela signifie que SDX va moissonner toutes les heures, et la première moisson se déroulera 10 minutes après le démarrage. Cette technique peut être utile pour déboguer ou vérifier l'état du moissonneur, mais pour des installations finales le type de mise à jour cron sera préférable. Voici tout de même un exemple de mise à jour périodique :

  <sdx:oai-harvester>
    <sdx:oai-data-providers>
      <sdx:oai-repository url="url de base de l'entrepôt OAI à moissonner" granularity="granularité utilisée par l'entrepôt">
        <sdx:update type="periodic">
          <sdx:offset>600000</sdx:offset>
          <sdx:period>3600000</sdx:period>
        </sdx:update>
      </sdx:oai-repository>
    </sdx:oai-data-providers>
  </sdx:oai-harvester>

Dans cet exemple, on a un décalage de 600 000 millisecondes (10 minutes) et une périodicité de 3 600 000 millisecondes (une heure). L'attribut type avec comme valeur periodic est obligatoire pour indiquer une mise à jour de type périodique. Les sous-éléments sdx:offset et sdx:period sont tous les deux optionnels et ne peuvent pas être répétés. Si le décalage n'est pas mentionné, on suppose qu'il est égal à 0, donc il s'effectuera dès le démarrage de SDX. Si la périodicité n'est pas mentionnée, alors on suppose qu'elle est égale à -1, ce qui signifie aucune périodicité, et la moisson ne s'effectuera qu'une seule fois (utile pour déboguer ou vérifier).

Le second type de mise à jour est donc le cron, qui s'apparente à l'utilitaire du même nom sur les systèmes Linux / UNIX. Il permet avec beaucoup de souplesse d'indiquer à quel moment on veut exécuter une tâche, en précisant les éléments d'information minute, heure, jour, mois, année et jour de la semaine. Tous ces éléments sont facultatifs  lorsqu'ils sont absents cela signifie que ce paramètre n'est pas pris en compte pour calculer la périodicité.

Regardons quelques exemples génériques de configuration de type cron :

On peut constater que les possibiltiés sont nombreuses. Il est à noter que l'information Jour de la semaine est de type booléen ; si c'est vrai, alors l'information Jour doit être comprise comme un jour de la semaine, et donc être un chiffre entre 0 et 6. Si c'est faux, alors c'est une journée dans le mois et cela doit être un chiffre entre 1 et 31 ; la valeur par défaut est faux, donc c'est un jour du mois par défaut. Notons également que le mois est spécifié par un chiffre entre 0 (janvier) et 11 (décembre), et que seul le calendrier Grégorien est supporté.

Il est aisé de transposer ces exemples dans une syntaxe SDX ; nous le faisons ci-dessous pour le dernier exemple, celui qui possède toutes les informations :

  <sdx:oai-harvester>
    <sdx:oai-data-providers>
      <sdx:oai-repository url="url de base de l'entrepôt OAI à moissonner" granularity="granularité utilisée par l'entrepôt">
        <sdx:update type="cron">
          <sdx:minute>10</sdx:minute>
          <sdx:hour>12</sdx:hour>
          <sdx:day week="false">1</sdx:day>
          <sdx:month>11</sdx:month>
          <sdx:year>2003</sdx:year>
        </sdx:update>
      </sdx:oai-repository>
    </sdx:oai-data-providers>
  </sdx:oai-harvester>

On constate par cet exemple que le type de mise à jour doit être spécifié par l'attribut type avec la valeur cron, et que pour 5 des 6 éléments d'information nous avons un élément correspondant. Le jour de la semaine est spécifié par l'attribut week de l'élément sdx:day, qui peut avoir les valeurs true ou false (par défaut). Tous ces éléments peuvent être omis, et dans ce cas leur valeur sera de -1, autrement dit tous les jours, toutes les minutes, etc. selon l'élément en question.

Le dernier élément d'information à renseigner pour un entrepôt OAI à moissonner est le type de moisson à effectuer. On peut le faire en indiquant quels verbes (au sens du protocole OAI) utiliser, chaque verbe étant spécifié par un élément sdx:oai-verb. Les verbes qui peuvent être utilisés pour moissonner sont ListRecords et GetRecord, puisque les autres n'ont pas de sens pour une telle opération.

Le cas le plus utile sera le verbe ListRecords, car il permet de récupérer un ensemble d'enregistrements de métadonnées. Voici une configuration complète pour ce verbe :

  <sdx:oai-verb
      id="identifiant de l'URL de requête"
      name="ListRecords"
      metadataPrefix="un préfixe de métadonnées"
      useLasHarvestDate="true"
      from="2003-11-30T00:00:00"
      until="2003-12-01T00:00:00"
      set="un nom d'ensemble"
  />

Les attributs from et until ne seront en général pas utilisés, car SDX s'occupe lui-même de gérer le moment où il a récupéré les données pour la dernière fois à cet entrepôt OAI pour cette base de documents. Par défaut, il va récupérer toutes les métadonnées modifiées depuis la dernière moisson, donc comme si le until n'était pas spécifié.

L'attribut set est également optionnel et il permet de préciser un sous-ensemble de données à récupérer, sous-ensemble qui doit bien sûr exister dans l'entrepôt. De son côté, l'attribut name doit avoir comme valeur le nom du verbe OAI, donc ListRecords cette fois-ci.

L'attribut metadataPrefix est obligatoire, car le protocole OAI-PMH l'oblige, et il doit indiquer un préfixe de métadonnées disponible dans l'entrepôt OAI moissonné. On peut par exemple utiliser la valeur oai_dc qui doit toujours être disponible.

L'attribut id est obligatoire. Il permet d'identifier clairement une verb dans la configuration d'un moissonneur. Rappelons qu'il est possible de définir plusieurs verbes dans une même configuration.

L'attribut useLastHarvestDate est facultatif. Réglé sur false, il permet de forcer le moissonneur à ne pas tenir compte de la dernière date de moisson. Il permet ainsi de reprendre complètement une moisson. Sa valeur par défaut est true.

On peut également demander un ou des enregistrements précis avec le verbe GetRecord. Dans ce cas, la configuration la plus complète possible sera de cette forme :

  <sdx:oai-verb
      id="identifiant de l'URL de requête"
      name="GetRecords"
      metadataPrefix="un préfixe de métadonnées"
  >
    <sdx:oai-identifier>[un identifiant OAI]</sdx:oai-identifier>
    <sdx:oai-identifier>[un identifiant OAI]</sdx:oai-identifier>
  </sdx:oai-verb>

Ici, seul le verbe et le préfixe de métadonnées doivent être spécifiés, les dates et ensembles ne sont pas prévus par le protocole. Ensuite, on utilise des sous-éléments sdx:oai-identifier pour chaque identifiant à récupérer.

Pour terminer cette section, voici un exemple de configuration d'un moissonneur qui ira chercher tous les enregistrements Dublin Core (modifiés depuis la dernière moisson) tous les jours à 3h00 dans la nuit  :

  <sdx:oai-harvester adminEmail="unautre@ici.fr">
    <sdx:oai-data-providers>
      <sdx:oai-repository url="url de base de l'entrepôt OAI à moissonner" granularity="granularité utilisée par l'entrepôt">
        <sdx:update type="cron">
          <sdx:minute>0</sdx:minute>
          <sdx:hour>3</sdx:hour>
        </sdx:update>
        <sdx:oai-verb id="identifiant de l'URL de requête" name="ListRecords" metadataPrefix="oai_dc"/>
      </sdx:oai-repository>
    </sdx:oai-data-providers>
  </sdx:oai-harvester>

L'intérêt de moissoner des métadonnées par le protocole OAI-PMH avec SDX est d'indexer ces métadonnées dans une base de documents SDX pour les offrir (par exemple) en recherche par la suite. Pour ce faire, on doit donc en plus indiquer comment indexer ces métadonnées, c'est-à-dire spécifier un pipeline d'indexation.

La manière la plus simple de le faire est... de ne rien spécifier du tout ! Dans ce cas, le pipeline d'indexation par défaut de la base de documents sera utilisé. Sinon, on a simplement à ajouter un élément sdx:pipeline défini comme pour tous les pipelines, et c'est celui-ci qui sera utilisé.

Voici un exemple (complet) de moissonneur OAI avec id="identifiant de l'URL de requête"un pipeline d'indexation spécifique :

  <sdx:oai-harvester adminEmail="unautre@ici.fr">
    <sdx:oai-data-providers>
      <sdx:oai-repository url="url de base de l'entrepôt OAI à moissonner" granularity="granularité utilisée par l'entrepôt">
        <sdx:update type="cron">
          <sdx:minute>0</sdx:minute>
          <sdx:hour>3</sdx:hour>
        </sdx:update>
        <sdx:oai-verb id="identifiant de l'URL de requête" name="ListRecords" metadataPrefix="oai_dc"/>
      </sdx:oai-repository>
    </sdx:oai-data-providers>
    <sdx:pipeline>
      <sdx:transformation type="XSLT" src="index-oai.xsl"/>
    </sdx:pipeline>
  </sdx:oai-harvester>

Les métadonnées récupérées par le moissonneur seront passées à la transformation XSLT index-oai.xsl, un enregistrement à la fois, et celle-ci doit produire les données à indexer par SDX, comme à l'habitude.