<?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 configuration SYSTEM "configuration.xml" NDATA XML>
<!ENTITY index SYSTEM "../index.xml" NDATA XML>
]>
<webpage id="configuration_entrepot">
  <head>
   <title>Configuration d'un entrepôt de documents</title>
   <titleabbrev>Entrepôt</titleabbrev>
   <author>
    <firstname>Martin</firstname>
    <surname>Sévigny</surname>
    <affiliation>
      <orgname>AJLSM</orgname>
    </affiliation>
   </author>
   <revhistory>
    <revision>
      <revnumber>1.0</revnumber>
      <date>2002/11/22</date>
    </revision>
   </revhistory>
  </head>
  <para>Les entrepôts de documents sont l'une des composantes des applications
   SDX-2. L'élément <sgmltag>&lt;sdx:repositories&gt;</sgmltag> du fichier
   <filename>application.xconf</filename> contient les informations qui
   définissent les entrepôts d'une application. La documentation n'est pas encore
   écrite&#xA0;; pour savoir comment déclarer les entrepôts, voir les
   <olink targetdocent="configuration">informations générales sur la
    configuration</olink>.</para>
  <para>Les entrepôts peuvent être définis au niveau de l'application, et pour
   cela l'élément <sgmltag>sdx:repositories</sgmltag> doit se situer directement
   sous l'élément <sgmltag>sdx:application</sgmltag>. Dans un tel cas, les
   entrepôts peuvent être utilisés par toutes les bases de documents&#xA0;; deux
   bases de documents peuvent même partager un même entrepôt, ce qui pourrait être
   utile pour, par exemple, permettre d'indexer des documents avec deux moteurs
   différents sans nécessairement les stocker deux fois. Les entrepôts peuvent
   aussi être définis pour une base de documents en particulier, et pour cela il
   faut insérer l'élément <sgmltag>sdx:repositories</sgmltag> directement sous un
   élément <sgmltag>sdx:documentBase</sgmltag>. Un entrepôt ainsi défini ne pourra
   pas être utilisé par d'autres bases de documents.</para>
  <para>Si une base de document désire utiliser un entrepôt défini au niveau de
   l'application, elle doit tout de même y faire référence dans le fichier
   <filename>application.xconf</filename>, comme dans cet exemple&#xA0;:</para>
  <programlisting>
...
&lt;sdx:documentBase ... &gt;
  ...
  &lt;sdx:repositories&gt;
    &lt;sdx:repository ref="repo1"/&gt;
  &lt;/sdx:repositories&gt;
  ...
&lt;/sdx:documentBase&gt;
...
</programlisting>
  <para>Dans cet exemple, il faut qu'un entrepôt avec l'identifiant
   <emphasis role="param">repo1</emphasis> soit défini au niveau de l'application
   pour que cette configuration soit valide.</para>
  <para>La définition d'un entrepôt varie selon le type d'entrepôt dont il
   s'agit. Pour l'instant, SDX 2 prévoit trois types d'entrepôts, qui seront
   présentés plus loin avec tous les détails concernant leur configuration.</para>

  <section>
   <title>Conserver ou référencer des documents&#xA0;?</title>
   <para>Avant de voir en détails les différents types d'entrepôts, il est
    important de bien les catégoriser. En effet, SDX 2 prévoit des entrepôts où il
    s'approprie un document en faisant une copie et en le gérant lui-même&#xA0;;
    ces entrepôts sont de type <emphasis>interne à SDX</emphasis>. Par ailleurs,
    SDX 2 prévoit également des entrepôts où il ne s'approprie pas le document, il
    ne fait que stocker son adresse URL&#xA0;; ces entrepôts sont de type
    <emphasis>externe à SDX</emphasis>.</para>
   <para>Les entrepôts de type externe sont intéressants lorsque les documents
    sont accessibles depuis le serveur et qu'ils sont déjà gérés correctement par
    un système (simple ou complexe), extérieur à SDX. Par exemple, ces documents
    pourraient être sur un site Web distant, où ils pourraient déjà être proprement
    stockés dans un système de fichiers accessible depuis le serveur et il n'y a
    aucune raison de copier ces documents.</para>
   <para>Les entrepôts de type interne lorsqu'on veut que SDX prenne en charge
    le stockage des documents. Cela peut s'avérer nécessaire si, par
    exemple, les documents ne sont pas stockés sur un système de fichiers
    accessible depuis le serveur (c'est le cas s'ils sont chargés par l'utilisateur
    à l'aide d'une interface Web) ou s'ils sont construits dynamiquement, en
    mémoire, suite à la saisie d'informations dans un formulaire HTML. Dans ce
    telles situations, le document n'est pas déjà accessible à SDX, alors il faut
    lui passer et lui demander de le prendre en charge.</para>
   <para>Avant même de choisir une implantation spécifique d'entrepôt pour une
    application SDX, il est bien important de déterminer si on cherche un entrepôt
    interne à SDX ou un entrepôt externe.</para>
  </section>
  <section>
   <title>L'entrepôt de type URL</title>
   <para>L'entrepôt de type URL est le seul entrepôt <emphasis>externe à
    SDX</emphasis> actuellement implanté. Son principe est simple&#xA0;: au lieu de
    prendre une copie des documents, il conserve seulement leur URL. Lorsque SDX a
    besoin des documents (par exemple pour la consultation du document), il le
    retrouve grâce à son URL.</para>
   <para>Pour que ce type d'entrepôt fonctionne, les documents doivent
    nécessairement avoir une URL valide, c'est-à-dire une URL qui peut être
    utilisée par Java. Cela exclut donc les documents résidant en mémoire (un DOM
    par exemple), les documents accessibles via des URL qui utilisent des
    protocoles non standards, etc. Par contre, cela inclut les URL de type
    <filename>file://usr/home/doc.xml</filename>, ce qui signifie qu'un entrepôt URL
    peut être utilisé pour des documents disponibles sur le système de fichiers du
    serveur.</para>
   <para>Ce dernier point est important&#xA0;: il montre que les documents
    gérés dans un entrepôt de type URL n'ont pas besoin d'être sur un serveur
    distant. L'utilisation de ce type d'entrepôt sur des fichiers locaux permet de
    ne pas copier ces derniers, s'ils sont déjà gérés convenablement sur le
    serveur.</para>
   <para>Par ailleurs, lorsqu'un document est référencé par une URL qui pointe
    sur un serveur distant, chaque consultation de ce document se fera en allant le
    chercher à cette URL. Cela implique trois choses importantes&#xA0;:</para>
   <orderedlist><listitem>
      <para>Les performances peuvent diminuer, surtout si le serveur ne
       répond pas rapidement ou si la bande passante est trop
       faible.</para></listitem><listitem>
      <para>Les utilisateurs voient toujours une version à jour du document,
       puisqu'il n'est pas copié localement par SDX.</para></listitem><listitem>
      <para>Il peut y avoir un décalage entre le document consulté et le
       document indexé par SDX, car SDX ne vérifie pas automatiquement qu'un document
       a été mis à jour pour le réindexer.</para></listitem>
   </orderedlist>
   <para>L'utilisation d'un cach local (voir plus loin) modifie quelque peu
    les deux premiers énoncés.</para>
   <para>Pour utiliser un entrepôt URL, la façon la plus simple est de le
    définir ainsi&#xA0;:</para>
   <programlisting>
&lt;sdx:repository id="r1" type="URL"/&gt;
  </programlisting>
   <para>Avec un tel entrepôt, tous les documents seront référencés par leur
    URL absolue et récupérés à chaque fois via cette URL. On peut modifier ce
    comportement avec un cache ou une URL de base.</para>
   <section>
    <title>URL de base</title>
    <para>Imaginons une base de documents qui permet d'indexer des documents
      XML disponibles sur un serveur de documents. Ce serveur retourne des documents
      selon une adresse de type
      <filename>http://foo/bar/path-to-doc/doc.xml</filename>, c'est-à-dire que tous
      les documents se trouvent quelque part sous l'adresse
      <filename>http://foo/bar/</filename>. SDX peut indexer ces documents et les
      placer dans un entrepôt de type URL sans problème. Toutefois, imaginons qu'à un
      certain moment, l'adresse du serveur change, mais la hiérachie des documents
      est conservée sur le nouveau serveur. L'adresse du document donné en exemple
      devient donc <filename>http://foo2/bar2/path-to-doc/doc.xml</filename>.</para>
    <para>Pour faire face à ce changement, il faudrait réindexer les
      documents dans SDX, sinon il ne pourrait plus les rapatrier pour la consultation.
      Toutefois, les entrepôts URL peuvent avoir une <emphasis>URL de base</emphasis>
      qui permet de bien gérer ce cas assez fréquent. En effet, il s'agit de déclarer
      son entrepôt de cette manière&#xA0;:</para>
    <programlisting>
&lt;sdx:repository id="r1" type="URL" base="http://foo/bar/"/&gt;
</programlisting>
    <para>avant le chargement depuis le serveur, et à ce moment SDX ne stockera
      que les adresses <emphasis>relatives à cette URL de base</emphasis>. Par
      exemple, pour un document à l'adresse
      <filename>http://foo2/bar2/path-to-doc/doc.xml</filename>, il ne conserve que
      <filename>path-to-doc/doc.xml</filename>, et lorsqu'on lui demande de retrouver
      le document, il ajoute cette URL relative à l'URL de base spécifiée dans le
      <filename>application.xconf</filename> au moment où on lui demande. Ainsi, si
      le serveur change, il n'y qu'à changer l'URL de base dans le
      <filename>applications.xconf</filename> et le tour est joué. Ce mécanisme
      fonctionne bien sûr avec les URL qui commence par <filename>file://</filename>.
      </para>
    <para>De façon générale, nous conseillons vivement de penser à une URL de
      base lorsque vous voulez indexer des documents et les stocker dans un entrepôt
      de type URL. La plupart du temps, les documents qui feront partie de votre base
      sont regroupés à un certain endroit, ce qui vous permet d'utiliser cette
      fonctionnalité.</para>
    <para>Il est important de noter que même si vous spécifiez une URL de
      base, les documents dont l'URL ne se situe pas sous cette URL de base seront
      correctement gérés par SDX, car il stockera l'URL absolue, comme s'il n'y avait
      pas d'URL de base.</para>
   </section>
   <section>
    <title>Cache</title>
    <para>L'utilisation d'un entrepôt URL peut avoir des effets sur les
      performances et il peut faire en sorte de <emphasis>désynchroniser l'affichage
      et l'indexation</emphasis>. Pour remédier à ce problème, SDX vous permet
      d'associer un <emphasis>cache</emphasis> à un entrepôt URL. Le principe est
      relativement simple&#xA0;: si un cache est spécifié, SDX va y déposer une
      copie des documents qu'il va chercher via des URL. Lorsqu'on lui demande de
      nouveau un document, il vérifie d'abord s'il le possède dans son cache&#xA0;;
      s'il ne l'a pas, il le prend depuis l'URL, s'il l'a, il compare sa date avec
      celui disponible depuis l'URL et si le fichier distant n'est pas plus récent,
      il utilisera celui du cache. Ce mécanisme de vérification des dates peut
      être paramétré pour que les vérifications de date aient lieu seulement lors de
      l'indexation, et non lorsque les documents sont demandés. Cela améliore encore
      plus les performances.</para>
    <para>Pour ajouter un cache à un entrepôt URL, la procédure est très
      simple, puisque n'importe quel entrepôt SDX peut servir de cache à un entrepôt
      de type URL. Bien entendu, il serait complètement inutile d'utiliser un
      entrepôt externe à SDX comme cache, ce qui signifie que les entrepôts
      <emphasis>système de fichiers</emphasis> ou <emphasis>JDBC</emphasis> peuvent
      être utilisés. Voici un exemple d'un entrepôt de type URL ayant un cache
      implémenté à l'aide d'un entrepôt de type système de fichiers&#xA0;:</para>
    <programlisting>
&lt;sdx:repository id="r1" type="URL"&gt;
  &lt;sdx:cache check="onIndex"&gt;
    &lt;sdx:repository type="FS" id="r1cache"/&gt;
  &lt;/sdx:cache&gt;
&lt;/sdx:repository&gt;
</programlisting>
    <para>Dans cet exemple, nous utilisons la valeur <emphasis role="param">onIndex</emphasis> pour l'attribut <sgmltag>check</sgmltag> de
      l'élément <sgmltag>sdx:cache</sgmltag>, ce qui signifie que la vérification des
      documents originaux pour les comparer avec ceux en cache ne s'effectue que lors
      de l'indexation. La valeur <emphasis role="param">onGet</emphasis> est
      également possible, et dans ce cas cette vérification s'effectue à chaque fois
      qu'un document est demandé, par exemple pour affichage.</para>
   </section>
  </section>
  <section>
   <title>L'entrepôt de type Système de fichiers</title>
   <para>Les documents XML peuvent facilement être stockés dans des fichiers,
    et c'est pourquoi il est naturel dans SDX d'offrir un type entrepôt qui
    exploite cette possibilité&#xA0;; c'est le rôle de l'entrepôt de type
    <emphasis>système de fichiers</emphasis>. Cet entrepôt est fort simple&#xA0;:
    il prend une copie des documents indexés et les stocke dans une hiérarchie de
    répertoires sur un disque qui lui est accessible. Toutes les opérations
    subséquentes sur les documents s'effectuent à partir de ces copies gérées par
    SDX. Notamment, lors d'une suppression, le fichier est effectivement
    supprimé.</para>
   <para>Ce type d'entrepôt est utile surtout pour sa simplicité. Nul besoin
    d'installer des outils externes ou de gérer les documents XML de l'extérieur,
    SDX se charge de tout. Par ailleurs, même si les fichiers sont facilement
    accessibles avec d'autres outils, il ne faut pas les déplacer ou les supprimer
    sans l'aide de SDX, sinon l'intégrité de la base de documents ne peut plus être
    assurée.</para>
   <para>Une déclaration complète d'un tel entrepôt se fait de cette
    façon&#xA0;:</para>
   <programlisting>
&lt;sdx:repository type="FS" baseDirectory="documents" depth="2" extent="100"/&gt;
</programlisting>
   <para>L'attribut <sgmltag>type</sgmltag> indique bien qu'il s'agit d'un
    entrepôt de type <emphasis>système de fichiers</emphasis>
    (<emphasis>FileSystem</emphasis>). Ensuite, l'attribut
    <sgmltag>baseDirectory</sgmltag>, obligatoire, permet de spécifier le
    répertoire de base où SDX stockera les documents gérés. Sa valeur doit être une
    URL absolue ou relative, si elle est relative elle est interprétée par rapport
    au fichier <filename>application.xconf</filename>. Ainsi, dans cet exemple, le
    répertoire de base serait le répertoire <filename>documents</filename> dans le
    répertoire <filename>conf</filename> de l'application, car le fichier
    <filename>application.xconf</filename> se situe dans ce répertoire.</para>
   <para>SDX va stocker les documents XML dans des fichiers, mais pas tous
    dans un même répertoire. Il créera une hiérarchie de répertoires pour contenir
    ces fichiers, de manière à éviter de créer un trop grand nombre de fichiers
    dans un même répertoire. Cette organisation dépend de deux paramètres&#xA0;: la
    profondeur de la structure et le nombre moyen de fichiers à mettre par
    répertoire&#xA0;; ce sont les attributs <sgmltag>depth</sgmltag> et
    <sgmltag>extent</sgmltag> qui fournissent ces indications. Ainsi, dans
    l'exemple précédent, SDX va créer deux niveaux de sous-répertoires sous le
    répertoire de base, et il va créer 100 répertoires par sous-répertoire. Il va
    utiliser cette structure et y déposer les documents au hasard. Selon cet
    exemple, au second niveau, il y aura
    100&#xA0;*&#xA0;100&#xA0;=&#xA0;10&#xA0;000 répertoires, s'il y a
    1&#xA0;000&#xA0;000 documents il y en aura donc 100 en moyenne. En spécificant
    des paramètres appropriés pour le nombre de documents envisagés pour une base,
    il est possible d'obtenir une structure facilement gérable. Ces deux attributs
    sont optionnels&#xA0;; s'ils ne sont pas présents, les valeurs
    <emphasis role="bold">3</emphasis> et <emphasis role="bold">100</emphasis> sont
    utilisées par défaut.</para>
   <para>Ce type d'entrepôt est facile à configurer, mais il est conseillé
    seulement pour les applications ayant un faible nombre de documents, car le
    système de fichiers montre des limites pratiques lorsque le nombre de fichiers
    dépasse un certain seuil.</para>
  </section>
  <section>
   <title>L'entrepôt de type JDBC</title>
   <para>Les entrepôts de type JDBC sont des entrepôts où le stockage des
    documents s'effectue à l'aide d'une base de données relationnelles. Il s'agit
    en fait du type d'entrepôts qui était offert par SDX-1. SDX utilise donc le
    gestionnaire de bases de données pour y stocker les documents et leur
    identifiant, permettant ainsi de les retrouver ou de les supprimer si
    nécessaire. La connexion avec la base de données et la création de la structure
    nécessaire sont des opérations prises en charges par SDX-2 et son architecture
    Cocoon sous-jacente&#xA0;; par contre, l'installation du SGBD est la
    responsabilité du développeur de l'application SDX qui désire utiliser un tel
    type d'entrepôt.</para>
   <para>Les entrepôts de type JDBC peuvent utiliser toute base de données
    pour laquelle il existe un pilote JDBC. Toutefois, même si la structure
    utilisée par SDX est fort simple, il peut y avoir des différences d'un SGBD à
    l'autre, différences en général dues à des implantations différentes des
    <emphasis>BLOB</emphasis> dans les SGBD. C'est pourquoi SDX distingue
    différents types d'entrepôts JDBC, chaque type faisant référence à un SGBD
    particulier, ou à un groupe de SGBD ayant des caractéristiques similaires.
    C'est pourquoi il est possible d'utiliser ces différentes valeurs pour
    l'attribut <sgmltag>type</sgmltag>&#xA0;:</para>
   <informaltable>
    <tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2" colwidth="5.43*"/><tbody>
       <row><entry colname="col1">MYSQL</entry><entry colname="col2">Le SGBD

          <ulink url="http://www.mysql.com/">MySQL</ulink></entry>
       </row>
       <row><entry colname="col1">POSTGRESQL</entry><entry colname="col2">Le
          SGBD
          <ulink url="http://www.postgresql.org/">PostgreSQL</ulink></entry>
       </row>
       <row><entry colname="col1">HSQL</entry><entry colname="col2">Le SGBD
          <ulink url="http://hsqldb.sourceforge.net/">HSQL</ulink></entry>
       </row>
       <row><entry colname="col1">ORACLE</entry><entry colname="col2">Le
          SGBD
          <ulink url="http://www.oracle.com/">Oracle</ulink></entry>
       </row>
       <row><entry colname="col1">JDBC</entry><entry colname="col2">N'importe quel type de SGBD, en autant qu'il implante JDBC de
          façon standard.</entry>
       </row></tbody>
    </tgroup>
   </informaltable>
   <para>Cocoon-2 prévoit tout ce qui est nécessaire pour définir des
    <emphasis>sources de données</emphasis> gérées par des SGBD. SDX utilise ces
    définitions plutôt que d'avoir ses propres sources de données. Ainsi, pour
    utiliser un entrepôt de type JDBC avec SDX, <emphasis role="bold">il est
    nécessaire de configurer une source de données appropriées dans
    Cocoon</emphasis>. La
    <ulink url="http://xml.apache.org/cocoon/developing/datasources.html">documentation de
      Cocoon</ulink> indique comment procéder&#xA0;; essentiellement, il s'agit d'une
    part d'ajouter une entrée dans le fichier <filename>WEB-INF/web.xml</filename>
    pour indiquer quelle classe Java utiliser comme pilote JDBC et d'autre part de
    définir une source de données utilisant ce pilote dans le fichier
    <filename>WEB-INF/cocoon.xconf</filename>, cette définition incluant notamment
    le nom de la base de données, le code d'utilisateur et le mot de passe à
    utiliser, et certaines autres pramètres. Cette étape de configuration Cocoon
    est nécessaire pour utiliser un entrepôt de type JDBC dans SDX.</para>
   <para>La définition d'un entrepôt de type JDBC dans SDX est très simple, car un seul attribut est nécessaire&#xA0;:</para><programlisting>
&lt;sdx:repository id="r1" dsi="my-db"/&gt;
</programlisting>
  <para>L'attribut <sgmltag>dsi</sgmltag> contient le nom de la source de données définies dans le fichier <sgmltag>application.xconf</sgmltag>.</para><para>SDX va stocker les documents dans une table de la base de données. Cette table aura pour nom la concaténation du chemin de l'application, du caractère <emphasis role="param">_</emphasis> et de l'identifiant de l'entrepôt. Par exemple, si l'entrepôt défini ci-dessus appartient à une application située dans <filename>sdx/myapp</filename>, la table où SDX stockera les documents est <emphasis role="param">myapp_r1</emphasis>.</para><para>La structure utilisée par SDX variei légèrement d'un SGBD à l'autre, mais seulement sur les types de données précis. Cette définition générale donne une bonne idée de cette structure&#xA0;:</para><programlisting>
CREATE TABLE nom_de_la_table ( id VARCHAR(255) NOT NULL,
     data BINARY, PRIMARY KEY (id));
</programlisting><para>Il y a donc un champ <emphasis role="param">id</emphasis>, clé primaire, qui contient l'identifiant du document dans SDX, et un champ <emphasis role="param">data</emphasis> qui contient le document tel quel, sans aucune modification.</para></section>
  <section>
   <title>Autres entrepôts</title>
   <para>L'architecture SDX-2 permet d'utiliser d'autres types d'entrepôts
    sans toucher au code de SDX. En effet, l'attribut <sgmltag>type</sgmltag> de
    l'élément <sgmltag>&lt;sdx:repository/&gt;</sgmltag> est utilisé afin d'identifier une
    classe Java qui implémente l'interface <emphasis role="paral">fr.gouv.culture.sdx.repository.Repository</emphasis>. Cette
    identification s'effectue de cette façon&#xA0;:</para>
   <orderedlist><listitem>
      <para>SDX vérifie si une classe dont le nom est la concaténation de la
       valeur de l'attribut <sgmltag>type</sgmltag> (mise en majuscules) et de
       "Repository" et qui se situe dans le package <emphasis role="param">fr.gouv.culture.sdx.repository</emphasis>. Par exemple, pour la
       valeur <emphasis role="param">FS</emphasis>, SDX vérifie s'il y a une classe
       <emphasis role="param">fr.gouv.culture.sdx.repository.FSRepository</emphasis>
       disponible&#xA0;; si oui, il l'utilise, sinon il passe à la seconde étape
       d'identification.</para></listitem><listitem>
      <para>SDX vérifie si la valeur de l'attribut <sgmltag>type</sgmltag>
       correspond au nom complet d'une classe Java disponible. Par exemple, si la
       valeur est <emphasis role="param">bar.foo.MYRepo</emphasis>, alors SDX va
       utiliser cette classe comme entrepôt, à condition qu'elle implémente
       l'interface nécessaire.</para></listitem>
   </orderedlist>
   <para>Ce mécanisme est très souple, car il permettra d'ajouter facilement
    d'autres types d'entrepôts dans SDX, mais surtout il permet à tout développeur
    d'application de mettre en place son propre type d'entrepôts sans avoir à
    toucher au code de SDX.</para>
  </section>
</webpage>
