<?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>Moteur d'indexation inJAC</title>

  <subtitle>Utilisation</subtitle>

  <section>
    <title>Présentation de l'Interface d'aministration</title>

    <para>Une fois le fichier indexation.properties configuré, l'utlisateur
    peut accèder à l'interface de l'application à l'URL :</para>

    <para><emphasis role="bold">[url du serveur
    Tomcat]/injac-indexing</emphasis>.</para>

    <para>La page d'accueil de l'interface s'affiche :<mediaobject>
        <imageobject>
          <imagedata fileref="media/accueilvierge.jpg"></imagedata>
        </imageobject>
      </mediaobject> Au premier lancement de l'interface, aucun index
    n'apparaît dans la liste d'index, et la recherche est désactivée. Une
    brève explication est fournie sur l'utilisation de l'interface.</para>

    <section>
      <title>Création d'un nouvel index</title>

      <para>Pour créer un nouvel index, sélectionner l'option dans le menu de
      gauche :</para>

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

      <para>Les champs du formulaires sont remplies avec les valeurs par
      défaut du fichier de configuration
      <filename>indexation.properties</filename>.</para>

      <para>Pour le moteur de rendu inJAC(version 2.3 RC1), vous devez créer
      un index nommé "<emphasis role="bold">global</emphasis>".</para>

      <para>L'URL doit être celle du chemin de l'espace WEBDAV racine à partir
      duquel l'arborescence va être parcourue pour l'indexation: elle doit
      comporter le scheme http, le nom d'hôte et le cas échéant le port, le
      contexte du serveur WEBDAV.</para>

      <para><emphasis role="bold">Rappel important</emphasis> :Si vous
      utilisez cette interface à travers un réseau public comme Internet, il
      est déconseillé de renseigner le mot de passe dans le fichier de
      configuration (voir documentation d'installation).</para>

      <para><itemizedlist>
          <listitem>
            <para><emphasis role="bold">Profil de l'utlisateur
            :</emphasis></para>

            <para>Les champs <emphasis>utilsateur</emphasis> et <emphasis>mot
            de passe</emphasis> définissent le profil utilisé pour
            l'indexation : seul seront indexés les documents visibles à cet
            utilisateur. Pour créer un index global, il faut donc utiliser un
            compte qui a la visibilité maximale.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Modes d'indexation des
            métadonnées</emphasis> :</para>

            <para>Ce menu déroulant propose les trois modes d'indexation pour
            les métadonnées :<mediaobject>
                <imageobject>
                  <imagedata fileref="media/menumetadata.jpg"></imagedata>
                </imageobject>
              </mediaobject></para>

            <para><itemizedlist>
                <listitem>
                  <para><emphasis role="bold">aucune métadonnée</emphasis> :
                  comme son nom l'indique</para>
                </listitem>

                <listitem>
                  <para>t<emphasis role="bold">outes les métadonnées
                  inJAC</emphasis>: index toutes les métadonnées de type inJAC
                  (dont le nom d'espace est "INJAC:")</para>
                </listitem>

                <listitem>
                  <para><emphasis role="bold">les métadonnées inJAC de
                  l'espace racine</emphasis> : indexe les métadonnées définies
                  pour l'espace racine, ici /injacRoot.</para>
                </listitem>
              </itemizedlist></para>

            <para>Une fois les champs renseignés, cliquez sur "indexer" pour
            commencer la première indexation. A la fin du processus
            d'indexation, une page de rapport apparaît, indiquant le nombre de
            documents indexés, la durée, ainsi qu'un message d'état. Si tout
            s'est bien déroulé, le message affiché est "OK" :<mediaobject>
                <imageobject>
                  <imagedata fileref="media/firstindexing.jpg"></imagedata>
                </imageobject>
              </mediaobject></para>

            <para><emphasis role="bold">Remarque</emphasis> :Selon le contenu
            de l'espace racine, l'indexation peut prendre un certain temps,
            notamment si ce dernier comporte des documents binaires comme
            PDF,Word ou RTF, comme c'est le cas ici.</para>
          </listitem>
        </itemizedlist></para>
    </section>

    <section>
      <title>Actions sur un index déjà créé</title>

      <para>Une fois notre index "global" créé et sélectionné, plusieurs
      actions le concernant deviennent disponibles :</para>

      <para><itemizedlist>
          <listitem>
            <para>Mise à jour</para>

            <para>Sous la section des informations figure un menu "Vie de
            l'index" avec deux actions possibles. La première est la mise à
            jour. Cette action entraine la mise à jour d'un index,
            c'est-à-dire l'indexation de tous les nouveaux documents sous
            l'espace racine défini pour cet index. <emphasis role="bold">Elle
            est protégée par le mot de passe du compte utilisateur utilisé
            pour la création de l'index.</emphasis></para>

            <para>A l'issue de la vérification, un nouveau rapport s'affiche,
            identique au premier, indiquant le nombre de nouveaux documents
            indexés, ainsi que la date et l'heure de la dernière mise à jour,
            en dessous celle de la création :<mediaobject>
                <imageobject>
                  <imagedata fileref="media/miseajour.jpg"></imagedata>
                </imageobject>
              </mediaobject></para>
          </listitem>

          <listitem>
            <para>Détruire l'index</para>

            <para>Cette action détruit complétement l'index séléctionné.
            <emphasis role="bold">Elle est protégée par le mot de passe du
            compte utilisateur utilisé pour la création de
            l'index.</emphasis></para>
          </listitem>

          <listitem>
            <para>Visualiser l'index</para>

            <para>Pour s'assurer du contenu indexé, on peut sélectioner
            l'option "Visualiser l'index" dans le menu de gauche, ou cliquer
            sur le lien "Visualiser" :</para>

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

            <para>En cliquant sur un document de la liste, on peut examiner
            les champs indexés le concernant.</para>

            <para></para>
          </listitem>
        </itemizedlist></para>
    </section>

    <section>
      <title>Recherche</title>

      <para>Le sous menu "chercher" permet de lancer une recherche sur l'index
      sélectionné, et d'afficher le résultat dans une page HTML, pour vérifier
      le bon état de l'index.</para>

      <para>Le principal client du moteur d'indexation est le moteur de rendu
      inJAC. Pour les détails sur la recherche avancée, se reporter à la
      <ulink
      url="http://esup-portail.org/consortium/espace/CMS_3F/cocoon-injac/current/utilisation.html#2.2">documentation</ulink>
      de ce dernier.</para>
    </section>

    <para></para>
  </section>

  <section>
    <title>URLS d'utilisations pour les applications clientes</title>

    <para>Cette section énumère les différentes URL utilisables par les
    applications clientes, comme le moteur de rendu inJac pour la recherche et
    le fil RSS, ou encore pour une application de tâches programmées pour la
    mise à jour des indexes.</para>

    <section>
      <title>Recherche</title>

      <section>
        <title>Les différentes URL de recherche HTML et XML</title>

        <para>Trois URL sont disponibles pour lancer une recherche, et toutes
        en en commun les mêmes paramètres :</para>

        <para><itemizedlist>
            <listitem>
              <para><emphasis role="bold">syntaxe</emphasis> des URLs</para>

              <para><emphasis
              role="bold">{hôte}</emphasis>]/injac-indexing/<emphasis
              role="bold">{htmlSearch|search|liusSearch}</emphasis>?query=<emphasis
              role="bold">{requête Lucene}</emphasis>&amp;name=<emphasis
              role="bold">{nom de l'index}</emphasis>[paramètres
              optionnels]</para>

              <para>Rôle des différentes URI pour la recherche</para>

              <para><itemizedlist>
                  <listitem>
                    <para><emphasis role="bold">htmlSearch</emphasis> :
                    recherche avec résultat en HTML (sous forme de
                    tableau)</para>
                  </listitem>

                  <listitem>
                    <para><emphasis role="bold">search</emphasis> : recherche
                    avec résultat en flux xml avec scores. Le champ par défaut
                    est "body"</para>
                  </listitem>

                  <listitem>
                    <para><emphasis role="bold">liusSearch</emphasis> :
                    recherche avec résultat en flux xml sans score, mais avec
                    champs de recherches par défaut configurés par le fichier
                    <emphasis role="bold">{liusConfigFile}</emphasis></para>

                    <para><emphasis role="bold">Note</emphasis> : les
                    paramètre de configuration <emphasis>resultMD</emphasis>,
                    <emphasis>renderURL</emphasis> et
                    <emphasis>upnode</emphasis> sont inopérants avec cette URI
                    : à la place, les champs renvoyés sont configurés dans le
                    fichier <emphasis role="bold">{liusConfigFile}</emphasis>
                    (Voir la documentation <ulink
                    url="http://www.bibl.ulaval.ca/lius/documents/LiusFr.htm#_Toc103747643">en
                    ligne</ulink> pour plus de détails) et les URLs sont
                    celles du serveur WEBDAV.</para>
                  </listitem>
                </itemizedlist></para>
            </listitem>

            <listitem>
              <para>paramètres :<itemizedlist>
                  <listitem>
                    <para><emphasis role="bold">query</emphasis> : requête
                    Lucene telle que définie dans ce <ulink
                    url="http://esup-portail.org/consortium/espace/indexation/htmlgen/exploitation.html#3.2">document</ulink>.</para>
                  </listitem>

                  <listitem>
                    <para><emphasis role="bold">name</emphasis> : nom de
                    l'index dans lequel s'effectue la recherche.</para>
                  </listitem>

                  <listitem>
                    <para><emphasis role="bold">upnode</emphasis> et <emphasis
                    role="bold">renderURL</emphasis>(optionnels) : permettent
                    de surcharger les paramètres de configuration et désigner
                    un autre moteur de rendu. Si un de ces paramètres est
                    envoyé vide, c'est les URLs WEBDAV des documents et non
                    celles du rendu qui seront renvoyées.</para>
                  </listitem>

                  <listitem>
                    <para><emphasis role="bold">resultMD</emphasis>(optionnel)
                    : permet de surcharger le paramètre de configuration du
                    même nom. Ce paramètre représente une liste des
                    métadonnées indéxées, séparées par des <emphasis
                    role="bold">virgules,</emphasis> que l'on veut obtenir
                    pour chaque document présent dans les résultats d'une
                    recherche.</para>
                  </listitem>

                  <listitem>
                    <para><emphasis role="bold">hitsOnly</emphasis> :
                    (optionnel) Pour les requêtes XML d'URI de type <emphasis
                    role="bold">search</emphasis>, permet de n'obtenir que la
                    balise <emphasis role="bold">hitts</emphasis> avec le
                    nombre de documents trouvés dans l'attribut <emphasis
                    role="bold">found</emphasis>, sans les informations sur
                    chaque document, par exemple : &lt;hits
                    found="5"/&gt;.</para>
                  </listitem>
                </itemizedlist></para>
            </listitem>
          </itemizedlist></para>
      </section>

      <section>
        <title>Exemples d'URL de recherche avec leurs résultats</title>

        <para>Voici trois exemples d'URL, une pour chaque type, avec leur
        résultats :</para>

        <para><itemizedlist>
            <listitem>
              <para>http://univ-ma_fac.fr/injac-indexing/<emphasis
              role="bold">htmlSearch</emphasis>?query=title:luc%E8ne&amp;name=global&amp;resultMD=gen_description
              :</para>

              <mediaobject>
                <imageobject>
                  <imagedata align="center"
                  fileref="media/htmlresult.jpg"></imagedata>
                </imageobject>
              </mediaobject>
            </listitem>

            <listitem>
              <para>http://univ-ma_fac.fr/injac-indexing/<emphasis
              role="bold">search</emphasis>?query=title:luc%E8ne&amp;name=global&amp;resultMD=gen_description</para>

              <mediaobject>
                <imageobject>
                  <imagedata align="center"
                  fileref="media/xmlresult.jpg"></imagedata>
                </imageobject>
              </mediaobject>
            </listitem>

            <listitem>
              <para>http://univ-ma_fac.fr/injac-indexing/<emphasis
              role="bold">liusSearch</emphasis>?query=title:luc%E8ne&amp;name=global</para>

              <mediaobject>
                <imageobject>
                  <imagedata align="center"
                  fileref="media/liusxmlresult.jpg"></imagedata>
                </imageobject>
              </mediaobject>
            </listitem>
          </itemizedlist></para>
      </section>
    </section>

    <section>
      <title>Mise à jour d'un index</title>

      <para><remark>Cette URL permet à une application de gestion de tâches
      programmées de mettre régulièrement à jour les indexes de manière
      asynchrone.</remark></para>

      <para><remark>Note : Si l'appel de cet URL est fait à travers un réseau
      public, il est fortement conseillé d'utiliser https pour encrypter les
      informations de connexion.</remark></para>

      <para><itemizedlist>
          <listitem>
            <para><emphasis role="bold">syntaxe</emphasis> de l'URL</para>

            <para>[<emphasis
            role="bold">hôte</emphasis>]/injac-indexing/<emphasis
            role="bold">updateIndex</emphasis>?user=[user]&amp;pass=<emphasis
            role="bold">[password]</emphasis>&amp;url=[<emphasis
            role="bold">url WEBDAV</emphasis> de la racine
            inJAC]&amp;name=<emphasis role="bold">{nom de
            l'index}</emphasis>&amp;mode=<emphasis role="bold">[mode
            d'indexation des métadonnées]</emphasis></para>
          </listitem>

          <listitem>
            <para>paramètres :</para>

            <para><itemizedlist>
                <listitem>
                  <para>user : nom d'utilisateur pour l'accès WEBDAV</para>
                </listitem>

                <listitem>
                  <para>pass : mot de passe</para>
                </listitem>

                <listitem>
                  <para>name : nom de l'index à mettre à jour</para>
                </listitem>

                <listitem>
                  <para>url : URL WEBDAV de l'espace inJAC racine à
                  indexer</para>
                </listitem>

                <listitem>
                  <para>mode : mode d'indexation des métadonnées</para>
                </listitem>
              </itemizedlist></para>
          </listitem>

          <listitem>
            <para>exemple :</para>

            <para><emphasis
            role="bold">https://univ-ma_fac.fr/injac-indexing/updateIndex?user=admin&amp;pass=*****&amp;url=http://slide-priv:8080/slide/files/injac/injacRoot&amp;name=global&amp;mode=1</emphasis></para>
          </listitem>
        </itemizedlist></para>
    </section>

    <section>
      <title>Fil RSS des derniers documents publiés</title>

      <para>Cette URL permet d'obtenir une liste des documents publiés les
      plus récemment, sous forme d'un fil RSS compatible 2.0.<itemizedlist>
          <listitem>
            <para><emphasis role="bold">syntaxe</emphasis> de l'URL</para>

            <para>[<emphasis
            role="bold">hote</emphasis>]/injac-indexing/indexRSS?name=<emphasis
            role="bold">{nom de l'index}</emphasis>&amp;length={<emphasis
            role="bold">nombre de documents</emphasis>}</para>
          </listitem>

          <listitem>
            <para>paramètres :</para>

            <para><itemizedlist>
                <listitem>
                  <para>name : nom de l'index</para>
                </listitem>

                <listitem>
                  <para>length : longeur de la liste des documents les plus
                  récents</para>
                </listitem>
              </itemizedlist></para>
          </listitem>

          <listitem>
            <para>exemple :</para>

            <para><emphasis
            role="bold">http://univ-ma_fac.fr/injac-indexing/indexRSS?name=global&amp;length=3</emphasis></para>

            <para><mediaobject>
                <imageobject>
                  <imagedata fileref="media/indexRSS.jpg"></imagedata>
                </imageobject>
              </mediaobject></para>
          </listitem>
        </itemizedlist></para>
    </section>
  </section>

  <section>
    <title>Outils en ligne de commande</title>

    <section>
      <title>Fusion d'index</title>

      <para>Quand les ressources indexées comportent un grand nombre de
      documents, il est préférable en terme de performances de créer plusieurs
      index de taille raisonnable, et de les fusionner ensuite.</para>

      <para>Un outil en ligne de commande, configurable via un fichier xml,
      est inclus dans injac-indexing, pour fusionner un ensemble d'index en un
      seul.</para>

      <section>
        <title>Configuration</title>

        <para>Un fichier de configuration de la fusion des index doit être
        créé, de la forme suivante :</para>

        <programlisting>&lt;merge fusionName="n7" password="abracadabra" login="admin" create="true"&gt;
  &lt;index name="global"/&gt;
  &lt;index name="theses_n7"/&gt;
  &lt;index name="m2"/&gt;
&lt;/merge&gt;</programlisting>

        <itemizedlist>
          <listitem>
            <para><emphasis role="bold">fusionName</emphasis> est le nom du
            nouvel index</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">password</emphasis> et login du nouvel
            index</para>
          </listitem>

          <listitem>
            <para>chaque balise <emphasis role="bold">&lt;index&gt;</emphasis>
            fait référence à un nom d'index à fusionner.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">create</emphasis> indique que s'il
            existe déjà, l'index [fusionName] doit être créer à
            nouveau.</para>
          </listitem>
        </itemizedlist>
      </section>

      <section>
        <title>Lancement</title>

        <para>Le lancement se fait en ligne de commande par la commande ANT
        <command>merge</command>. Sans argument, le fichier de configuration
        utilisé est celui décrit dans
        <filename>indexation.properties</filename> par la propriété <emphasis
        role="bold">merge.config</emphasis>.</para>

        <para>Exemple :</para>

        <para><command>ant merge
        /appli/java/injac/tomcat/webapps/injac-indexing/WEB-INF/mergeDC.xml</command></para>

        <para></para>
      </section>
    </section>

    <para></para>
  </section>
</article>