<?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_entrepot">
  <head>
    <title>SDX et les entrepôts OAI</title>

    <titleabbrev>Entrepôts</titleabbrev>

    <author>
      <firstname>Martin</firstname>

      <surname>Sévigny</surname>

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

    <revhistory>
      <revision>
        <revnumber>1.0</revnumber>

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

  <para>Un entrepôt OAI doit rendre disponibles des métadonnées à propos
  d'objets documentaires. Dans SDX, les objets documentaires sont gérés au
  niveau d'une base de documents, car ce sont les documents XML indexés, ou
  encore les fragments de ces documents XML. Il est donc tout à fait naturel
  d'associer un entrepôt OAI à une base de documents dans SDX.</para>

  <para>SDX permet donc de transformer toute base de documents en entrepôt OAI,
  et ce en intervenant au niveau de la configuration de cette base de documents
  (donc dans le fichier <filename>application.xconf</filename>) et,
  éventuellement, en programmant des <emphasis
  role="italic">pipelines</emphasis>. SDX se chargera des aspects tels que les
  dates de dernière modification, les enregistrements supprimés, etc. La
  reponsabilité du développeur de l'application est donc de&nbsp;:</para>

  <orderedlist>
    <listitem>
      <para>Fournir des informations générales à propos de l'entrepôt.</para>
    </listitem>

    <listitem>
      <para>Définir quelles unités documentaires de la base de documents feront
      partie de l'entrepôt OAI.</para>
    </listitem>

    <listitem>
      <para>Rendre disponibles des formats de métadonnées.</para>
    </listitem>

    <listitem>
      <para>Produire, pour chaque format, les métadonnées à partir des unités
      documentaires.</para>
    </listitem>
  </orderedlist>

  <para>Les trois premiers items sont purement déclaratifs et très simples à
  mettre en place. Le dernier item peut être plus ou moins compliqué, selon la
  complexité de la transformation entre une unité documentaire et un format de
  métadonnées.</para>

  <para>Puisqu'un entrepôt OAI est associé à une base de documents dans SDX, la
  configuration de cet entrepôt OAI se fera à l'intérieur d'un élément <sgmltag
  class="element">sdx:documentBase</sgmltag> dans le fichier
  <filename>application.xconf</filename>. On aura donc une structure qui
  ressemble à celle-ci&nbsp;:</para>

  <programlisting>
  &lt;sdx:documentBase ...&gt;
    &lt;sdx:repositories&gt;...&lt;/sdx:repositories&gt;
    &lt;sdx:fieldList&gt;...&lt;/sdx:fieldList&gt;
    &lt;sdx:index&gt;...&lt;/sdx:index&gt;
    &lt;sdx:oai-repository&gt;...&lt;/sdx:oai-repository&gt;
  &lt;/sdx:documentBase&gt;
</programlisting>

  <para>Dans la suite de cette page, nous allons expliquer la structure de
  l'élément <sgmltag class="element">sdx:oai-repository</sgmltag>.</para>

  <section>
    <title>Informations générales à propos de l'entrepôt OAI</title>

    <para>C'est l'élément <sgmltag class="element">sdx:oai-repository</sgmltag>
    lui-même qui contient les informations générales à propos de cet
    entrepôt&nbsp;elles doivent être renseignées par le développeur de
    l'application. Ces informations sont surtout utiles pour les requêtes OAI
    avec le verbe <emphasis role="italic">Identify</emphasis>.</para>

    <itemizedlist>
      <listitem>
        <para>Le <emphasis role="bold">nom</emphasis> de l'entrepôt OAI est une
        chaîne de caractères destinée à être lue par des personnes et qui permet
        de l'identifier sommairement. L'attribut <sgmltag
        class="attribute">name</sgmltag> permet de renseigner cette
        information&nbsp;; il est <emphasis
        role="bold">obligatoire</emphasis>.</para>
      </listitem>

      <listitem>
        <para>L'<emphasis role="bold">URL de base</emphasis> indique l'URL où se
        trouve l'entrepôt OAI. Eventuellement, SDX pourra peut-être renseigner
        automatiquement cette information, mais pour l'instant, vous devez le
        faire à l'aide de l'attribut <sgmltag
        class="attribute">baseURL</sgmltag>, qui est <emphasis
        role="bold">obligatoire</emphasis>.</para>
      </listitem>

      <listitem>
        <para>Les <emphasis role="bold">adresses des administrateurs</emphasis>
        permettent de rejoindre par courrier électronique une ou des personnes
        en charge de cet entrepôt OAI. L'attribut <sgmltag
        class="attribute">adminEmail</sgmltag> contient ces adresses, qui
        doivent être séparées par une espace s'il y en a plusieurs. Cet attribut
        est <emphasis role="bold">obligatoire</emphasis>.</para>
      </listitem>

      <listitem>
        <para>L'attribut <sgmltag class="attribute">noPerResponse</sgmltag>
        permet de spécifier le nombre de documents renvoyés par page de
        résultats. La valeur par défaut est <sgmltag
        class="attvalue">1000</sgmltag>.</para>
      </listitem>
    </itemizedlist>

    <para>Voici un exemple de configuration de ces informations
    générales&nbsp;:</para>

    <programlisting>
  &lt;sdx:oai-repository
    name="Thèses de doctorat de l'université Lumière Lyon 2 (France)"
    baseURL="http://monserveur.com/sdx/sdx/oai/mon-appli/ma-base"
    adminEmail="quelquun@quelquepart.pays unautre@ailleurs.com"&gt;
</programlisting>

    <para>Les autres informations générales, c'est-à-dire la version du
    protocole supportée (2.0), la date la plus ancienne dans les documents de
    l'entrepôt OAI, le support ou non des enregistrements supprimés et la
    granularité des dates sont automatiquement générées par SDX&nbsp;; elles
    n'ont pas besoin d'être renseignées dans le
    <filename>application.xconf</filename>. A noter que la granularité gérée par
		SDX est du type "à la journée"&nbsp;: "<literal>YYYY-MM-DDThh:mm:ssZ</literal>".</para>

    <para>Par ailleurs, SDX ne supporte pas deux fonctionnalités optionnelles du
    protocole&nbsp;: la possibiltié de fournir une description plus détaillées
    de l'entrepôt OAI de même que la possibilité de compresser les données.
    C'est pourquoi aucune configuration n'est prévue pour ces informations
    générales.</para>
  </section>

  <section>
    <title>Les unités documentaires faisant partie de l'entrepôt OAI</title>

    <para>Dans une base de documents SDX, on retrouve un certain nombre d'unités
    documentaires, soit des ensembles d'information qui peuvent être retournés
    comme résultat de recherche. La plupart du temps, ces unités documentaires
    correspondent à des documents XML indexés, mais parfois ces documents ont
    été fragmentés et dans ce cas il y aura plus d'unités documentaires que de
    documents XML.</para>

    <para>Par ailleurs, le scénario le plus courant consiste à offrir toutes les
    unités documentaires d'une base de documents dans l'entrepôt OAI
    correspondant. Toutefois, il peut arriver que seule une partie des unités
    documentaires doit s'y retrouver. SDX permet de configurer cela aisément
    sous la forme de restrictions.</para>

    <para>Le mécanisme général des restrictions est celui d'inclusion et
    d'exclusion d'unités documentaires, inclusions et exclusions qui doivent
    être exprimées sous la forme d'une requête de recherche. Si aucune mention
    de restriction n'est présente, alors toutes les unités documentaires font
    partie de l'entrepôt OAI. S'il y a au moins une inclusion, seules les unités
    documentaires qui la satisfont seront concernées, sauf si elles sont
    explicitement exclues.</para>

    <para>C'est un élément <sgmltag class="element">sdx:oai-subset</sgmltag> qui
    permet de spécifier les restrictions&nbsp;; il est donc facultatif et s'il
    n'est pas présent toutes les unités documentaires seront ajoutées à
    l'entrepôt. Il peut avoir deux sous-éléments, <sgmltag
    class="element">sdx:include</sgmltag> pour une inclusion et <sgmltag
    class="element">sdx:exclude</sgmltag> pour une exclusion. Ces deux éléments
    peuvent être dans n'importe quel ordre et répétés.</para>

    <para>Voici quelques exemples&nbsp;:</para>

    <programlisting>
  &lt;sdx:oai-repository&gt;
    ...
    &lt;!-- Seulement les unités qui satisfont une requête --&gt;
    &lt;sdx:oai-subset&gt;
      &lt;sdx:include query="sujet:physique"/&gt;
    &lt;/sdx:oai-subset&gt;
  &lt;/sdx:oai-repository&gt;

  &lt;sdx:oai-repository&gt;
    ...
    &lt;!-- Toutes les unités sauf certaines --&gt;
    &lt;sdx:oai-subset&gt;
      &lt;sdx:exclude query="statut:temp"/&gt;
    &lt;/sdx:oai-subset&gt;
  &lt;/sdx:oai-repository&gt;

  &lt;sdx:oai-repository&gt;
    ...
    &lt;!-- Combinaison de requêtes --&gt;
    &lt;sdx:oai-subset&gt;
      &lt;sdx:include query="sujet:physique sujet:chimie"/&gt;
      &lt;sdx:exclude query="statut:temp"/&gt;
    &lt;/sdx:oai-subset&gt;
  &lt;/sdx:oai-repository&gt;

</programlisting>
  </section>

  <section>
    <title>Les formats de métadonnées disponibles</title>

    <para>Tous les entrepôts OAI doivent fournir des métadonnées en format
    Dublin Core. Mais d'autres formats peuvent également être envoyés sur
    demande. On doit donc spécifier quels sont les formats de métadonnées à
    offrir, mais aussi comment obtenir ces métadonnées à partir des unités
    documentaires contenues dans la base.</para>

    <para>Chaque format de métadonnées est spécifié par un élément <sgmltag
    class="element">sdx:oai-format</sgmltag> que l'on retrouve à l'intérieur de
    <sgmltag class="element">sdx:oai-repository</sgmltag>. Les attributs de cet
    élément permettent d'identifier et décrire ce format&nbsp;:</para>

    <itemizedlist>
      <listitem>
        <para>L'attribut <sgmltag class="attribute">name</sgmltag> permet de
        spécifier un nom descriptif pour ce format de métadonnées. Cet attribut
        est <emphasis role="bold">obligatoire</emphasis>.</para>
      </listitem>

      <listitem>
        <para>L'attribut <sgmltag class="attribute">metadataPrefix</sgmltag>
        permet de spécifier le <emphasis role="italic">préfixe</emphasis> de ce
        format de métadonnées. Cette information est importante car toute la
        gestion des formats dans le protocole OAI se fait à l'aide de ce
        préfixe. Cet attribut est <emphasis
        role="bold">obligatiore</emphasis>.</para>
      </listitem>

      <listitem>
        <para>L'attribut <sgmltag class="attribute">namespace</sgmltag> permet
        de spécifier le domaine de noms (au sens XML) associé à ce format de
        métadonnées, ce qui est également une contrainte du protocole OAI.
        L'attribut est <emphasis role="bold">obligatoire</emphasis>.</para>
      </listitem>

      <listitem>
        <para>L'attribut <sgmltag class="attribute">schemaUrl</sgmltag> permet
        de spécifier l'endroit où se trouve le schéma XML que respectent les
        métadonnées. Encore une fois, il s'agit d'une contrainte imposée par le
        protocole OAI&nbsp;: toutes les métadonnées doivent respecter un schéma
        disponible via une URL. Cet attribut est donc bien sûr <emphasis
        role="bold">obligatoire</emphasis>.</para>
      </listitem>

      <listitem>
        <para>L'attribut <sgmltag class="element">rootElement</sgmltag> permet
        de renseigner l'élément racine du format de métadonnées. TODO:
        pourquoi&nbsp;? Il est optionnel.</para>
      </listitem>
    </itemizedlist>

    <para>Ces attributs permettent donc de connaître les informations générales
    à propos du format de métadonnées. Il reste ainsi à savoir comment SDX doit
    obtenir ces métadonnées, et pour cela le développeur d'une application peut
    utiliser deux méthodes&nbsp;: les <emphasis role="italic">correspondances de
    champs</emphasis> et les <emphasis
    role="italic">pipelines</emphasis>.</para>

    <section>
      <title>Méthode par correspondance de champs</title>

      <para>Cette méthode est définitivement la plus simple. En effet, une base
      de documents SDX contient un ou plusieurs champs de recherche propres à
      SDX. Dans certains cas, le format de métadonnées sera très simple et
      pourra être obtenu directement à partir de ces champs.</para>

      <para>Considérons le cas où la base de documents possède les champs
      suivants&nbsp;:</para>

      <programlisting>
  &lt;sdx:fieldList&gt;
    &lt;sdx:field name="auteur" type="field"/&gt;
    &lt;sdx:field name="titre" type="field"/&gt;
    &lt;sdx:field name="sujet" type="field"/&gt;
  &lt;/sdx:fieldList&gt;
</programlisting>

      <para>Les champs <emphasis role="italic">auteur</emphasis> et <emphasis
      role="italic">sujet</emphasis> peuvent être répétés pour une même unité
      documentaire.</para>

      <para>Le protocole OAI nous impose de supporter au moins le format Dublin
      Core non qualifié, et celui-ci n'est qu'une collection <emphasis
      role="italic">plate</emphasis> d'éléments d'information simple, de
      type&nbsp;:</para>

      <programlisting>
  &lt;oai_dc:dc
      xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/"
      xmlns:dc="http://purl.org/dc/elements/1.1/"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/oai_dc/
           http://www.openarchives.org/OAI/2.0/oai_dc.xsd"&gt;

    &lt;dc:identifier&gt;Un identifiant&lt;/dc:identifier&gt;
    &lt;dc:title&gt;Le titre&lt;/dc:title&gt;
    &lt;dc:creator&gt;Un auteur&lt;/dc:creator&gt;
    &lt;dc:creator&gt;Un autre auteur&lt;/dc:creator&gt;
    &lt;dc:subject&gt;Un premier sujet ; Un second sujet&lt;/dc:subject&gt;
  &lt;/oai_dc:dc&gt;
</programlisting>

      <para>Pour une situation semblable à celle-ci, on peut tout simplement
      obtenir le format Dublin Core en faisant correspondre les champs SDX à des
      éléments Dublin Core. La configuration nécessaire pour produire cet
      exemple serait&nbsp;:</para>

      <programlisting>
   &lt;sdx:oai-format
         name="OAI Dublin core"
         metadataPrefix="oai_dc"
         namespace="http://purl.org/dc/elements/1.1/"
         schemaUrl="http://www.openarchives.org/OAI/2.0/oai_dc.xsd"&gt;
     &lt;sdx:oai-fields&gt;
       &lt;sdx:oai-field name="identifier" sdxField="sdxdocid"/&gt;
       &lt;sdx:oai-field name="title" sdxField="titre" repeated="repeated"/&gt;
       &lt;sdx:oai-field name="creator" sdxField="auteur" repeated="repeated"/&gt;
       &lt;sdx:oai-field name="subject" sdxField="sujet" repeated="concatenate" separator=" ; "/&gt;
     &lt;/sdx:oai-fields&gt;
   &lt;/sdx:oai-format&gt;
</programlisting>

      <para>Cet exemple est déjà complet. Les éléments <sgmltag
      class="element">sdx:oai-fields</sgmltag> et <sgmltag
      class="element">sdx:oai-field</sgmltag> permettent respectivement de
      spécifier la liste de correspondances. Ensuite, l'élément <sgmltag
      class="element">sdx:oai-field</sgmltag> peut avoir quatre attributs qui
      ont les significations suivantes&nbsp;:</para>

      <itemizedlist>
        <listitem>
          <para><sgmltag class="attribute">name</sgmltag>&nbsp;: le nom de
          l'élément à générer dans le format de métadonnées. <emphasis
          role="bold">Obligatoire</emphasis>.</para>
        </listitem>

        <listitem>
          <para><sgmltag class="attribute">sdxField</sgmltag>&nbsp;: le nom du
          champ de recherche SDX dans la base de documents. <emphasis
          role="bold">Obligatoire</emphasis>.</para>
        </listitem>

        <listitem>
          <para><sgmltag class="attribute">repeated</sgmltag>&nbsp;: ce que SDX
          doit faire si un champ SDX est répété pour une unité documentaire. Les
          deux valeurs possibles sont&nbsp;: <sgmltag
          class="attvalue">repeated</sgmltag> et dans ce cas SDX va créer autant
          d'éléments dans le format de métadonnées qu'il y d'occurrences de
          champs SDX&nbsp;; <sgmltag class="attvalue">concatenate</sgmltag>, et
          dans ce cas SDX va créer un seul élément dans le format de
          métadonnées, mais il va concaténer toutes les valeurs du champs SDX.
          Cet attribut est <emphasis role="bold">optionnel</emphasis>, la valeur
          par défaut est <sgmltag class="attvalue">repeated</sgmltag>.</para>
        </listitem>

        <listitem>
          <para><sgmltag class="attribute">separator</sgmltag>&nbsp;: le
          séparateur à utiliser entre les occurrences du champ SDX lorsqu'on
          décide de concaténer ces valeurs dans un seul élément de métadonnées.
          L'attribut est <emphasis role="bold">optionnel</emphasis>, sa valeur
          par défaut est <sgmltag class="attvalue"> ; </sgmltag>, et il est bien
          sûr inutile si on décide de répéter les éléments de
          métadonnées.</para>
        </listitem>
      </itemizedlist>

      <para>Produire des métadonnées par correspondance de champs est donc très
      simple et ne fait intervenir que de la configuration. Si vous définissez
      des champs SDX proches de vos métadonnées, et que votre format de
      métadonnées est plat (comme le Dublin Core de l'OAI), cette technique peut
      être tout à fait suffisante.</para>
    </section>

    <section>
      <title>Méthode par pipeline</title>

      <para>Dans bien des cas, la méthode par correspondance de champs ne sera
      pas suffisante. Soit parce que le format de métadonnées n'est pas plat, ou
      encore parce qu'il n'est pas possible de produire les valeurs adéquates à
      partir des champs SDX. Dans ce cas, il faut utiliser la méthode du
      <emphasis role="italic">pipeline</emphasis> SDX.</para>

      <para>Conceptuellement, cette méthode est très simple&nbsp;: à chaque fois
      que SDX doit envoyer des métadonnées à propos d'une unité documentaire, il
      va transformer l'unité documentaire (forcément du XML) à l'aide d'un
      pipeline SDX, semblable à un pipeline utilisé pour indexer par exemple. La
      sortie de ce pipeline doit donc correspondre au format de métadonnées
      souhaité, en particulier respecter le schéma XML spécifié. Il est de la
      responsabilité du développeur de l'application de vérifier que les données
      produites par le pipeline sont correctes.</para>

      <para>On peut spécifier un pipeline de la même manière que pour un
      pipeline d'indexation. Il s'agit donc d'une série de transformations,
      chaque transformation pouvant être une transformation XSLT ou une classe
      Java. Le plus simple est bien sûr d'avoir une XSLT pour faire le
      travail.</para>

      <para>Voici un exemple d'un format de métadonnées produit par un pipeline
      avec deux transformations, la première étant une classe Java et la seconde
      une XSLT&nbsp;:</para>

      <programlisting>
   &lt;sdx:oai-format
         name="Mon format"
         metadataPrefix="mf"
         namespace="http://monserveur.com/mf/"
         schemaUrl="http://monserveur.com/mf.xsd"&gt;
    &lt;sdx:pipeline id="oai-mf"&gt;
      &lt;sdx:transformation id="oai-mf-1" type="com.monserveur.oai.mf"/&gt;
      &lt;sdx:transformation id="oai-mf-2" type="XSLT" src="../oai/mf.xsl"/&gt;
    &lt;/sdx:pipeline&gt;
  &lt;/sdx:oai-format&gt;
</programlisting>

      <para>Comme toujours, la classe <emphasis
      role="italic">com.monserveur.oai.mf</emphasis> doit implémenter
      l'interface <emphasis
      role="italic">fr.gouv.culture.sdx.pipeline.Transformation</emphasis>.</para>

      <para>Soulignons également que les méthodes par correspondance de champs
      et par pipeline sont <emphasis role="bold">exclusives</emphasis>&nbsp;; un
      seul élément <sgmltag class="element">sdx:pipeline</sgmltag> ou <sgmltag
      class="element">sdx:oai-fields</sgmltag> doit être présent dans un élément
      <sgmltag class="element">sdx:oai-format</sgmltag>.</para>
    </section>
  </section>
</webpage>