<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//UR1//DTD docbookAllegeEsup//FR"
"http://www.esup-portail.org/consortium/espace/docbook/xxe/dtd/docbook_allege_esup.dtd">
<article lang="FR">
  <title>Interface inJAC-OAI</title>

  <subtitle>Installation</subtitle>

  <section>
    <title>Pré-requis</title>

    <para>Ce module d'inJac nécessite l'accès à un serveur Webdav doté d'un
    espace racine inJac.</para>

    <para>Sur la machine de déploiement doivent être installés un
    environnement Java (JRE ou JDK), version 1.4.2 ou supérieur, ainsi qu'un
    moteur de servlet/jsp (TOMCAT 5.0.28 ou supérieur).</para>

    <para>Pour lire ce document, il n'est pas inutile d'avoir une connaissance
    préalable minimale du protocole <ulink
    url="http://www.openarchives.org/OAI/openarchivesprotocol.html">OAI-PMH</ulink>
    , ou des principes de fonctionnement généraux de sa <ulink
    url="http://www.culture.gouv.fr/culture/dll/OAI-PMH.htm">mise en
    oeuvre</ulink>.</para>
  </section>

  <section>
    <title>Installation</title>

    <section>
      <title>Déploiement</title>

      <para>Pour déployer l'interface inJAC-OAI, il suffit de décompresser
      l'archive dans un moteur de servlet. Pour Tomcat, l'application peut
      être déployée dans le répertoire <emphasis
      role="bold">/webapps.</emphasis></para>
    </section>

    <section>
      <title>Configuration générale</title>

      <para>Cette application est basée sur le projet <ulink
      url="http://www.oclc.org/research/software/oai/cat.htm">OAICAT</ulink>,
      d'OCLC Online Computer Library Center, dont la documentation contient
      une <ulink
      url="http://pubserv.oclc.org/oaicat/jars/docs/properties.html">description
      du fichier original de configuration</ulink>.</para>

      <para>Pour la configuration d'inJac-OAI, tout se passe dans le fichier
      [<filename>$OAICAT_HOME]/WEB-INF/injac-oaicat.properties</filename> :
      (où <emphasis role="bold">[$OAICAT_HOME]</emphasis> représente le chemin
      d'installation de l'application, ex. :
      E:/Tests/jakarta-tomcat-5.0.28/webapps/injac-oaicat) </para>

      <para>Voici les paramètres à renseigner qui sont propres à inJac (les
      autres étant décris dans la documentation dont le lien est indiqué plus
      haut) :</para>

      <para><itemizedlist>
          <listitem>
            <para><emphasis
            role="bold">OAIHandler.styleSheet</emphasis>=/injac-oaicat/xsl/injac-oaicat.xsl
            --&gt; Commenter ou décommenter (insert une balise
            &lt;?doctype?&gt; en entête de la réponse xml)</para>
          </listitem>

          <listitem>
            <para><emphasis
            role="bold">WebdavOAICatalog.maxListSize</emphasis>=1000 --&gt;
            longueur de liste max renvoyée par requête (ListSets, ListRecords,
            ListIdentifiers)</para>
          </listitem>

          <listitem>
            <para><emphasis
            role="bold">WebdavOAICatalog.url</emphasis>=http://saroumane.enseeiht.fr:8083/slide/files/injacRoot/Racine
            --&gt; url de l'espace webdav</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">WebdavOAICatalog.login</emphasis>=user
            --&gt; login et mot de passe d'accès webdav <emphasis
            role="bold">WebdavOAICatalog.password</emphasis>=trusted</para>
          </listitem>

          <listitem>
            <para><emphasis
            role="bold">WebdavOAICatalog.baseDir</emphasis>=[$OAICAT_HOME]</para>
          </listitem>

          <listitem>
            <para><emphasis
            role="bold">WebdavRecordFactory.repositoryIdentifier</emphasis>=oaicat.injac.org
            --&gt; identifiant du dépôt(doit être unique)</para>
          </listitem>

          <listitem>
            <para><emphasis
            role="bold">Injac.Crosswalk.mapFiles</emphasis>=dcmapping.xml,etdmsmapping.xml,lom_fr_mapping.xml
            --&gt; fichiers de mapping des formats exposés</para>
          </listitem>

          <listitem>
            <para><emphasis
            role="bold">Injac.Crosswalk.mapDir</emphasis>=[$OAICAT_HOME]/WEB-INF/formats</para>
          </listitem>
        </itemizedlist></para>
    </section>

    <section>
      <title>Définition des formats exposés par fichier de mapping</title>

      <section>
        <title>Mapping simple</title>

        <para>Le répertoire dont l'emplacement est défini par la propriété
        <emphasis role="bold">injac.Crosswalk.mapDir</emphasis> contient les
        fichiers définissant la <emphasis role="bold">conversion des
        métadonnées</emphasis> du serveur Webdav dans un format exposé par
        l'entrepôt OAI. Trois fichiers sont fournis dans le package :</para>

        <para><itemizedlist>
            <listitem>
              <para>dcmapping.xsl définit un mapping pour le format <emphasis
              role="bold">Dublin Core</emphasis></para>
            </listitem>

            <listitem>
              <para>etdmsmapping.xsl pour le format <emphasis
              role="bold">ETDMS </emphasis><emphasis role="bold">(Electronic
              Thesis and Dissertations Metadata Set)</emphasis></para>
            </listitem>

            <listitem>
              <para>lom_fr_mapping.xml pour un format <emphasis
              role="bold">LOM (Learning Object Model) </emphasis>francisé et
              simplifié.</para>
            </listitem>
          </itemizedlist>Dans le sous-répertoire
        <filename>channel_profils</filename> se trouve un fichier de
        configuration pour la saisie des métadonnées dans le <emphasis
        role="bold">Canal de stockage</emphasis> au format LOM FR simplifié :
        <filename>lomfr_simple.xml</filename> (voir la documentation du Canal,
        section inJac).</para>

        <para>La structure de ces fichiers de mapping se présente comme suit
        :</para>

        <para><programlisting>&lt;mapping 
  metadata-prefix="oai_dc"
  root-tag="dc"
  metadata-namespace="http://www.openarchives.org/OAI/2.0/oai_dc/"
  schema="http://www.openarchives.org/OAI/2.0/oai_dc/ http://www.openarchives.org/OAI/2.0/oai_dc.xsd"&gt;
  &lt;namespaces&gt;
    &lt;namespace prefix="dc" uri="http://purl.org/dc/elements/1.1/"/&gt;
  &lt;/namespaces&gt;
  &lt;nativeItem&gt;
    &lt;mapping-attr
      source="webdavurl"
      dest="dc:source"/&gt;
  &lt;/nativeItem&gt;
  &lt;webdav-metadata&gt;
    &lt;mapping-attr 
      source="injac:title" 
      dest="dc:title"/&gt;
    &lt;mapping-attr 
      source="injac:author" 
      dest="dc:creator"/&gt;</programlisting></para>

        <para>Dans ce cas précis, il s'agit d'un mapping simple, où
        typiquement une métadonnée inJac (attribut <emphasis
        role="bold">source</emphasis>) correspond à un élément simple du
        format exposé (attribut <emphasis role="bold">dest</emphasis>).</para>

        <para>Le formalisme de ce fichier est le suivant :</para>

        <itemizedlist>
          <listitem>
            <para><emphasis role="bold">&lt;mapping&gt;</emphasis> l'élément
            racine englobant<itemizedlist>
                <listitem>
                  <para>attribut <emphasis
                  role="bold">metadata-prefix</emphasis> : préfixe utilisé
                  comme paramètre OAI pour le paramètre metadataPrefix.</para>
                </listitem>

                <listitem>
                  <para>attribut <emphasis role="bold">root-tag</emphasis> :
                  élément racine placé sous l'élément &lt;metadatas&gt; de la
                  réponse OAI.</para>
                </listitem>

                <listitem>
                  <para>attribut <emphasis
                  role="bold">metadata-namespace</emphasis> : nom d'espace
                  pour ce format exposé.</para>
                </listitem>

                <listitem>
                  <para>attribut <emphasis role="bold">schema</emphasis> : URL
                  du schéma XML pour ce format exposé (pour validation)</para>
                </listitem>

                <listitem>
                  <para><emphasis role="bold">&lt;namespaces&gt;</emphasis> :
                  élément englobant <emphasis role="bold">optionnel</emphasis>
                  qui définit des noms d'espaces secondaires à intégrer à
                  l'entête de la réponse OAI.<itemizedlist>
                      <listitem>
                        <para>&lt;namespace&gt; définit un nom
                        d'espace(attribut uri) et son préfixe(attribut
                        prefix)</para>
                      </listitem>
                    </itemizedlist></para>
                </listitem>

                <listitem>
                  <para><emphasis role="bold">&lt;nativeItem&gt;</emphasis> :
                  (optionnel) définit un mapping entre un élément interne de
                  la représentation du document et un élément du format
                  exposé. Les valeurs disponibles sont
                  local-identifier(identifiant local de l'enregistrement OAI)
                  et webdavurl(l'URL Webdav du document).</para>
                </listitem>

                <listitem>
                  <para><emphasis
                  role="bold">&lt;webdav-metadata&gt;</emphasis> : élément
                  englobant obligatoire listant l'ensemble des correspondances
                  entre les métadonnés inJac et les éléments du format
                  exposé.<itemizedlist>
                      <listitem>
                        <para><emphasis
                        role="bold">&lt;mapping-attr&gt;</emphasis> : le
                        mapping proprement dit. L'attribut <emphasis
                        role="bold">source</emphasis> est le nom de la
                        métadonnées inJac, l'attribut <emphasis
                        role="bold">dest</emphasis> est l'élément du format
                        exposé. Trois autres attributs permettent de faire du
                        mapping plus évolué(voir section Mapping
                        avancé).</para>
                      </listitem>
                    </itemizedlist></para>
                </listitem>
              </itemizedlist></para>
          </listitem>
        </itemizedlist>
      </section>

      <section>
        <title>Mapping avancé</title>

        <para>Des fonctionnalités de mapping supplémentaires sont accessibles
        à travers trois attributs de l'élément <emphasis
        role="bold">&lt;mapping-attr&gt;</emphasis> :</para>

        <itemizedlist>
          <listitem>
            <para><emphasis role="bold">multiparse</emphasis> définit un
            séparateur permettant de générer plusieurs fois la même balise en
            parsant la valeur de la métadonnées.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">required</emphasis>="yes" stipule que
            cette métadonnées est requise faute de quoi le document associé ne
            sera pas disséminé sous ce format.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">attributes</emphasis> permet de parser
            la valeur de la métadonnées pour y chercher la ou les valeur(s)
            d'un ou plusieurs attributs à ajouter à l'élément du format
            exposé(entre crochet).</para>
          </listitem>
        </itemizedlist>

        <para>Voici pour illustrer un exemple de mapping avancé :</para>

        <mediaobject>
          <imageobject>
            <imagedata fileref="media/advanced_mapping.jpg"></imagedata>
          </imageobject>
        </mediaobject>
      </section>
    </section>

    <section>
      <title>Constitution de classification par ensembles (set)</title>

      <para>Le fichier <filename>WEB-INF/setspecs.xml</filename> définit une
      classification par ensembles hiérarchisés à partir des métadonnées inJac
      associées aux documents. Par exemple, si on souhaite qu'un document
      possédant la métadonnée keyword=math soit classé comme appartenant à un
      ensemble "Mathématiques", il faut définir ainsi un élément &lt;set&gt;
      dans le fichier <filename>setspecs.xml</filename> :</para>

      <para><programlisting>&lt;ListSets&gt;
 &lt;set&gt;
  &lt;setSpec&gt;math&lt;/setSpec&gt;
  &lt;setName&gt;Mathematiques&lt;/setName&gt;
  &lt;setDescription&gt;Ensemble de ressources de mathematiques enseignees dans l'etablissement.&lt;/setDescription&gt;
  &lt;metadata-matching match="any-of"&gt;
   &lt;webdav-attr name="<emphasis role="bold">injac:keywords</emphasis>" multivalue="true" delimiter=","&gt;
    &lt;match-regexp&gt;<emphasis role="bold">math</emphasis>&lt;/match-regexp&gt;
   &lt;/webdav-attr&gt;
  &lt;/metadata-matching&gt;
 &lt;/set&gt;
 ...</programlisting></para>

      <para>Pour chaque ensemble que l'on souhaite définir, il faut crée un
      élément &lt;set&gt; à l'intérieur de la balise englobante
      &lt;ListSets&gt;.</para>

      <para>Chaque &lt;set&gt; contient à son tour trois éléments <emphasis
      role="bold">obligatoires et uniques</emphasis> :</para>

      <para><itemizedlist>
          <listitem>
            <para>&lt;setSpec&gt; est le nom identifiant l'ensemble
            conformément au protocole OAI. Pour définir une hiérarchie les
            deux points servent de séparateur entre élements père et éléments
            fils, en lisant de gauche à droite, par exemple :</para>

            <para><itemizedlist>
                <listitem>
                  <para>&lt;setSpec&gt;<emphasis
                  role="bold">info</emphasis>&lt;/setSpec&gt; ensemble de
                  niveau 1</para>
                </listitem>

                <listitem>
                  <para>&lt;setSpec&gt;<emphasis
                  role="bold">info:protocole</emphasis>&lt;/setSpec&gt;
                  ensemble de niveau 2 fils de l'ensemble "info"</para>
                </listitem>
              </itemizedlist></para>
          </listitem>

          <listitem>
            <para>&lt;setName&gt; est le nom lisible utilisé pour être
            affiché.</para>
          </listitem>

          <listitem>
            <para>&lt;setDescription&gt; est la description de
            l'ensemble.</para>
          </listitem>
        </itemizedlist>Aprés ces éléments, il faut définir un élément
      <emphasis role="bold">&lt;metadata-matching&gt;</emphasis>, lui-même
      composé d'un ou plusieurs éléments &lt;webdav-attr&gt;.</para>

      <para><itemizedlist>
          <listitem>
            <para><emphasis role="bold">&lt;metadata-matching&gt;</emphasis>
            contient une liste d'un ou plusieurs éléments <emphasis
            role="bold">&lt;webdav-attr&gt;</emphasis>, lesquels définissent
            les conditions d'appartenance à un ensemble.</para>

            <para>L'attribut <emphasis role="bold">match</emphasis> avec la
            valeur "any-of" stipule que le document appartient à l'ensemble
            dés qu'une des conditions définies dans les balises
            &lt;webdav-attr&gt; est remplie. Tout autre valeur de cet attribut
            est comprise comme "all", c'est-à-dire requiert la satisfaction de
            l'ensemble des conditions réunies pour que le document
            appartiennent à l'ensemble.</para>
          </listitem>

          <listitem>
            <para>&lt;webdav-attr&gt; définit une condition d'appartenance
            d'un document à un ensemble :</para>

            <para><itemizedlist>
                <listitem>
                  <para>l'attribut <emphasis role="bold">name</emphasis>
                  définit la métadonnée inJac dont la valeur est
                  testée.</para>
                </listitem>

                <listitem>
                  <para>l'élément <emphasis
                  role="bold">&lt;match-regexp&gt;</emphasis> est l'expression
                  régulière servant à tester la valeur de la métadonnée</para>
                </listitem>

                <listitem>
                  <para>l'attribut optionnel <emphasis
                  role="bold">multivalue="true"</emphasis> indique qu'il faut
                  "parser" les valeurs multiples de la métadonnée à l'aide de
                  l'attribut <emphasis role="bold">delimiter</emphasis>. Si
                  ces attributs sont définis définis, chacune de ces valeurs
                  est testée séparémment avec l'expression régulière.</para>
                </listitem>
              </itemizedlist></para>
          </listitem>
        </itemizedlist></para>

      <para><emphasis role="bold">Note </emphasis>: les expressions régulières
      suivent le format utilisé par le package <ulink
      url="http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/package-summary.html">java.util.regex</ulink>
      (voir <ulink
      url="http://java.sun.com/docs/books/tutorial/extra/regex/">tutorial de
      Sun</ulink>)</para>
    </section>

    <section>
      <title>Paramètres de l'IHM</title>

      <section>
        <title>Fichiers de configuration de l'IHM</title>

        <para>L'IHM d'inJac-OAI permet de visualiser le contenu exposé par
        l'entrepôt, en listant les ensembles(set) et formats
        disponibles.</para>

        <para><mediaobject>
            <imageobject>
              <imagedata fileref="media/listidentifiers.jpg"></imagedata>
            </imageobject>
          </mediaobject></para>

        <para>La façon dont sont affichées les réponses est définie dans les
        fichiers :</para>

        <para><itemizedlist>
            <listitem>
              <para><filename>xsl/ihm_main.xsl </filename>(génération HTML
              pour la disposition en tableau) .</para>
            </listitem>

            <listitem>
              <para>css/style_1.css pour le style (couleurs, fontes...)</para>
            </listitem>
          </itemizedlist> A moins de vouloir modifier l'apparence de l'IHM,
        aucune modification n'est nécessaire pour ce dernier fichier.</para>
      </section>

      <section>
        <title>Ajout de liens sur le moteur de rendu</title>

        <para>L'IHM propose par défaut des liens sur les documents du serveur
        Webdav, mais on peut également avoir des liens sur un moteur de rendu
        inJac.</para>

        <para>Pour obtenir ces liens sur un moteur de rendu inJac installé, en
        plus des liens directs sur le serveur Webdav, il faut renseigner les
        paramètres rendererURI et upnode du fichier ihm_main.xsl :</para>

        <para><mediaobject>
            <imageobject>
              <imagedata fileref="media/params_rendu.jpg"></imagedata>
            </imageobject>
          </mediaobject></para>
      </section>
    </section>
  </section>
</article>