<?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>Changements</title>

    <para><itemizedlist>
        <listitem>
          <para>Version 1.1</para>

          <para><itemizedlist>
              <listitem>
                <para>nouveau paramètre WebdavOAICatalog.setsFile pour le
                fichier de définition de sets</para>
              </listitem>

              <listitem>
                <para>nouveaux paramètres upnode, renderURL et intDocs</para>
              </listitem>

              <listitem>
                <para>URL de moteur de rendu inJAC pour les documents
                référencés (voir la description des fichiers de mapping pour
                la définition des formats exposés)</para>
              </listitem>
            </itemizedlist></para>
        </listitem>
      </itemizedlist></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:/java/jakarta-tomcat-5.0.28/webapps/injac-oaicat)</para>

      <para>L'emplacement de ce fichier doit être paramétré dans le fichier
      <filename>WEB-INF/web.xml</filename>, dans la balise :</para>

      <para><programlisting>  &lt;param-name&gt;properties&lt;/param-name&gt;
  &lt;param-value&gt;<emphasis role="bold">/home/injac/tomcat/webapps/injac-oai/WEB-INF/injac-oaicat.properties</emphasis>&lt;/param-value&gt;</programlisting></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">WebdavOAICatalog.setsFile</emphasis>=[nom du fichier
            pour la définition des sets OAI] (à placer dans le répertoire
            WEB-INF/) La valeur par defaut est setspecs.xml.</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">upnode</emphasis>, <emphasis
            role="bold">renderURL</emphasis> et <emphasis
            role="bold">intDocs</emphasis> : noeud racine inJAC, URL du moteur
            de rendu inJAC, et extensions des fichiers rendus en HTML. Ces
            paramètres servent à retourner une URL sur le moteur de rendu
            inJAC. Le paramètre intDocs ne doit pas être modifié, il doit
            rester en rapport avec le traitement des rendus pris en charge par
            le moteur de rendu. (Pour plus de détails sur l'utilisation des
            URL de rendu, voir la section suivante concernant les fichiers de
            mapping).</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>

      <para>Le mapping défini ici répond à deux problèmatiques : la première
      consistant à mettre en correspondance des <emphasis
      role="bold">attributs stockés dans un serveur WEBDAV</emphasis> avec des
      éléments d'un <emphasis role="bold">format exposé par un entrepôt
      OAI</emphasis>. La deuxième problématique, qui en découle, est que ces
      attributs WEBDAV sont stockés en rateau et n'ont aucune profondeur ou
      imbrication, contrairement à certains des formats que l'on voudrait
      exposer via OAI, tel que LOM par exemple.</para>

      <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é(le schéma xml pour validation est situé à
              l'emplacement
              <filename>injac-oai/schema/lomfr.xsd</filename>).</para>
            </listitem>
          </itemizedlist>Pour rendre possible la validation pour ce dernier
        format, vous devez modifier l'URL définie par l'attribut <emphasis
        role="bold">schema</emphasis> de la balise &lt;mapping&gt;, exemple :
        <programlisting>schema="http://injac.esup.org/lomfr <emphasis
              role="bold">http://saroumane.enseeiht.fr:810/injac-oai/schemas/lomfr.xsd</emphasis>"</programlisting></para>

        <para>Dans le sous-répertoire
        <filename>WEB-INF/formats/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 la validation du jeu de
                  métadonnées(Attention : ce schéma est utilisé par les
                  moissonneurs pour valider les métadonnées transmises dans
                  les réponses OAI. L'URL indiquée <emphasis
                  role="bold">doit</emphasis> référencer un emplacement
                  accessible et valide pour rendre possible cette 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><emphasis
                        role="bold">&lt;namespace&gt;</emphasis> définit un
                        nom d'espace(attribut <emphasis
                        role="bold">uri</emphasis>) et son préfixe(attribut
                        <emphasis role="bold">prefix</emphasis>)</para>
                      </listitem>
                    </itemizedlist></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>

                <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 pour l'attribut <emphasis
                  role="bold">source</emphasis> des balises <emphasis
                  role="bold">&lt;mapping-attr&gt;</emphasis> de cette balise
                  sont</para>

                  <para><itemizedlist>
                      <listitem>
                        <para><emphasis
                        role="bold">local-identifier</emphasis> : identifiant
                        local de l'enregistrement OAI</para>
                      </listitem>

                      <listitem>
                        <para><emphasis role="bold">webdavurl</emphasis> :
                        l'URL Webdav du document</para>
                      </listitem>

                      <listitem>
                        <para><emphasis role="bold">renderurl</emphasis> :
                        l'URL vers le rendu du document produit par le moteur
                        de rendu spécifié par le paramètre renderURL du
                        fichier de propriétés.</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><emphasis role="bold">&lt;webdav-attr&gt;</emphasis> 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><emphasis role="bold">Note</emphasis> : la version 1.1 permet de
        définir directement les liens sur le moteur de rendu par des
        paramètres du fichier de propriétés, et l'utilisation de la valeur
        "renderurl" dans les fichiers de mapping (voir section concernant
        ceux-ci). Le paramètrage du fichier XSL décrit ici ne vaut que si
        seules les URL WEBDAV sont utilisées.</para>

        <para>Pour obtenir, dans la navigation que propose l'IHM, des liens
        sur un moteur de rendu inJac installé , dans le cas où seule l'URL
        WEBDAV est définie dans les fichiers de mapping des formats exposés,
        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>