<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (C) 2000-2010  Ministere de la culture et de la communication (France), AJLSM
See LICENCE file
-->
<!DOCTYPE webpage PUBLIC "-//Norman Walsh//DTD Website V2.1b1//EN"
"../../../dtd/website.dtd" [
<!ENTITY config SYSTEM "configuration.xml" NDATA XML>
<!ENTITY sitemap SYSTEM "sitemap.xml" NDATA XML>
<!ENTITY url SYSTEM "api-url.xml" NDATA XML>
<!ENTITY xsp SYSTEM "api-xsp.xml" NDATA XML>
]>
<webpage id="oai_moissonneur">
  <head>
    <title>SDX et la moisson OAI</title>

    <titleabbrev>Moisson</titleabbrev>

    <author>
      <firstname>Martin</firstname>

      <surname>Sévigny</surname>

      <affiliation>
        <orgname>AJLSM</orgname>
      </affiliation>
    </author>

    <author>
      <firstname>Pichot</firstname>

      <surname>Malo</surname>

      <affiliation>
        <orgname>AJLSM</orgname>
      </affiliation>
    </author>

    <revhistory>
      <revision>
        <revnumber>1.1</revnumber>

        <date>2005-10-06</date>
      </revision>
    </revhistory>
  </head>

  <para>La moisson OAI consiste à interroger des entrepôts OAI pour récupérer
  des métadonnées à propos des enregistrements qu'on y trouve. SDX inclut un
  moissonneur OAI, et ce moissoneur peut êre utilisé pour alimenter une base de
  documents. Donc encore une fois, un moissonneur OAI se situe au même niveau
  qu'une base de documents SDX, et la configuration du moissonneur se fera
  nécessairement à l'intérieur d'un élément <sgmltag
  class="element">sdx:documentBase</sgmltag> dans le fichier
  <filename>application.xconf</filename>.</para>

  <para>Pour avoir un moissonneur OAI, on a besoin de spécifier trois types
  d'information&nbsp;:</para>

  <orderedlist>
    <listitem>
      <para>Des informations générales.</para>
    </listitem>

    <listitem>
      <para>Le ou les entrepôts OAI à moissonner, avec pour chacun les
      caractéristiques de moisson.</para>
    </listitem>

    <listitem>
      <para>Comment indexer les métadonnées récupérées.</para>
    </listitem>
  </orderedlist>

  <section>
    <title>Déclaration et informations générales</title>

    <para>On peut déclarer un moissonneur OAI en utilisant l'élément <sgmltag
    class="element">sdx:oai-harvester</sgmltag> ainsi&nbsp;:</para>

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

    <para>L'attribut <sgmltag class="attribute">adminEmail</sgmltag> 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.</para>
  </section>

  <section>
    <title>Les entrepôts OAI à moissonner</title>

    <para>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&nbsp;:</para>

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

    <para>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 <sgmltag
    class="attribute">url</sgmltag>, et le type de granularité utilisée par l'entrepôt indiquer par l'attribut
		<ulink url="http://www.openarchives.org/OAI/openarchivesprotocol.html#Datestamp"><sgmltag class="attribute">granularity</sgmltag></ulink>.
		Par défaut, SDX emploie la granularité à la seconde (YYYY-MM-DDThh:mm:ssZ).
		A noter qu'un attribut <sgmltag
    class="attribute">ref</sgmltag> peut également être spécifié, mais il n'est
    pas documenté pour l'instant, en attente de stabiliser le code à cet
    égard.</para>

    <para>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
    <sgmltag class="element">sdx:update</sgmltag> 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 <emphasis role="italic">périodique</emphasis> et le type
    <emphasis role="italic">cron</emphasis>.</para>

    <para>Le type <emphasis role="bold">périodique</emphasis> 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
    <emphasis role="italic">cron</emphasis> sera préférable. Voici tout de même
    un exemple de mise à jour périodique&nbsp;:</para>

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

    <para>Dans cet exemple, on a un décalage de 600&nbsp;000 millisecondes (10
    minutes) et une périodicité de 3&nbsp;600&nbsp;000 millisecondes (une
    heure). L'attribut <sgmltag class="attribute">type</sgmltag> avec comme
    valeur <sgmltag class="attvalue">periodic</sgmltag> est <emphasis
    role="bold">obligatoire</emphasis> pour indiquer une mise à jour de type
    périodique. Les sous-éléments <sgmltag class="element">sdx:offset</sgmltag>
    et <sgmltag class="element">sdx:period</sgmltag> sont tous les deux
    <emphasis role="bold">optionnels</emphasis> 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).</para>

    <para>Le second type de mise à jour est donc le <emphasis
    role="bold">cron</emphasis>, 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 <emphasis role="bold">facultatifs</emphasis>&nbsp;
    lorsqu'ils sont absents cela signifie que ce paramètre n'est pas pris en
    compte pour calculer la périodicité.</para>

    <para>Regardons quelques exemples génériques de configuration de type
    cron&nbsp;:</para>

    <table>
      <title>Exemples génériques de configuration de type cron</title>

      <tgroup cols="7">
        <colspec colname="col1" colnum="1" colwidth="1.00*" />

        <colspec colname="col2" colnum="2" colwidth="1.02*" />

        <colspec colname="col3" colnum="3" colwidth="1.04*" />

        <colspec colname="col4" colnum="4" colwidth="1.02*" />

        <colspec colname="col5" colnum="5" colwidth="1.22*" />

        <colspec colname="col6" colnum="6" colwidth="1.78*" />

        <colspec colname="col7" colnum="7" colwidth="7.64*" />

        <thead>
          <row>
            <entry colname="col1">Minute</entry>

            <entry colname="col2">Heure</entry>

            <entry colname="col3">Jour</entry>

            <entry colname="col4">Mois</entry>

            <entry colname="col5">Année</entry>

            <entry colname="col6">Jour semaine</entry>

            <entry colname="col7">Explications</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry colname="col1">10</entry>

            <entry colname="col2"></entry>

            <entry colname="col3"></entry>

            <entry colname="col4"></entry>

            <entry colname="col5"></entry>

            <entry colname="col6"></entry>

            <entry colname="col7">A la dixième minute de chaque heure, chaque
            jour</entry>
          </row>

          <row>
            <entry colname="col1"></entry>

            <entry colname="col2">3</entry>

            <entry colname="col3">0</entry>

            <entry colname="col4"></entry>

            <entry colname="col5"></entry>

            <entry colname="col6">Oui</entry>

            <entry colname="col7">Tous les dimanche à 3h00 (la nuit)</entry>
          </row>

          <row>
            <entry colname="col1"></entry>

            <entry colname="col2">3</entry>

            <entry colname="col3">1</entry>

            <entry colname="col4"></entry>

            <entry colname="col5"></entry>

            <entry colname="col6">Non</entry>

            <entry colname="col7">Le premier jour de chaque moi, à 3h</entry>
          </row>

          <row>
            <entry colname="col1"></entry>

            <entry colname="col2">3</entry>

            <entry colname="col3"></entry>

            <entry colname="col4"></entry>

            <entry colname="col5"></entry>

            <entry colname="col6"></entry>

            <entry colname="col7">Tous les jours à 3h</entry>
          </row>

          <row>
            <entry colname="col1">10</entry>

            <entry colname="col2">12</entry>

            <entry colname="col3">1</entry>

            <entry colname="col4">11</entry>

            <entry colname="col5">2003</entry>

            <entry colname="col6">Non</entry>

            <entry colname="col7">Le premier décembre 2003 à 12h10 (une seule
            fois)</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <para>On peut constater que les possibiltiés sont nombreuses. Il est à noter
    que l'information <emphasis role="italic">Jour de la semaine</emphasis> est
    de type booléen&nbsp;; si c'est vrai, alors l'information <emphasis
    role="italic">Jour</emphasis> 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&nbsp;;
    la valeur par défaut est <emphasis role="italic">faux</emphasis>, 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é.</para>

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

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

    <para>On constate par cet exemple que le type de mise à jour doit être
    spécifié par l'attribut <sgmltag class="attribute">type</sgmltag> avec la
    valeur <sgmltag class="attvalue">cron</sgmltag>, 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 <sgmltag
    class="attribute">week</sgmltag> de l'élément <sgmltag
    class="element">sdx:day</sgmltag>, qui peut avoir les valeurs <sgmltag
    class="attvalue">true</sgmltag> ou <sgmltag class="attvalue">false</sgmltag>
    (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.</para>

    <para>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 <sgmltag class="element">sdx:oai-verb</sgmltag>. Les
    verbes qui peuvent être utilisés pour moissonner sont <emphasis
    role="italic">ListRecords</emphasis> et <emphasis
    role="italic">GetRecord</emphasis>, puisque les autres n'ont pas de sens
    pour une telle opération.</para>

    <para>Le cas le plus utile sera le verbe <emphasis
    role="bold">ListRecords</emphasis>, car il permet de récupérer un ensemble
    d'enregistrements de métadonnées. Voici une configuration complète pour ce
    verbe&nbsp;:</para>

    <programlisting>
  &lt;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"
  /&gt;
</programlisting>

    <para>Les attributs <sgmltag class="attribute">from</sgmltag> et <sgmltag
    class="attribute">until</sgmltag> 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 <emphasis role="italic">until</emphasis> n'était pas
    spécifié.</para>

    <para>L'attribut <sgmltag class="attribute">set</sgmltag> 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 <sgmltag class="attribute">name</sgmltag> doit avoir comme valeur
    le nom du verbe OAI, donc <sgmltag class="attvalue">ListRecords</sgmltag>
    cette fois-ci.</para>

    <para>L'attribut <sgmltag class="attribute">metadataPrefix</sgmltag> est
    <emphasis role="bold">obligatoire</emphasis>, 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 <sgmltag
    class="attvalue">oai_dc</sgmltag> qui doit toujours être disponible.</para>

    <para>L'attribut <sgmltag class="attribute">id</sgmltag> est <emphasis
    role="bold">obligatoire</emphasis>. 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.</para>

    <para>L'attribut <sgmltag class="attribute">useLastHarvestDate</sgmltag> est
    facultatif. Réglé sur <sgmltag class="attvalue">false</sgmltag>, 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 <sgmltag class="attvalue">true</sgmltag>.</para>

    <para>On peut également demander un ou des enregistrements précis avec le
    verbe <emphasis role="bold">GetRecord</emphasis>. Dans ce cas, la
    configuration la plus complète possible sera de cette forme&nbsp;:</para>

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

    <para>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 <sgmltag
    class="element">sdx:oai-identifier</sgmltag> pour chaque identifiant à
    récupérer.</para>

    <para>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&nbsp;&nbsp;:</para>

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

  <section>
    <title>L'indexation des métadonnées récupérées</title>

    <para>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.</para>

    <para>La manière la plus simple de le faire est... de ne rien spécifier du
    tout&nbsp;! 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 <sgmltag
    class="element">sdx:pipeline</sgmltag> défini comme pour tous les pipelines,
    et c'est celui-ci qui sera utilisé.</para>

    <para>Voici un exemple (complet) de moissonneur OAI avec id="identifiant de
    l'URL de requête"un pipeline d'indexation spécifique&nbsp;:</para>

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

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