<?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>Installation</subtitle>

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

    <para>Cette application est basée sur le projet <ulink
    url="http://www.bibl.ulaval.ca/lius/index.html">LIUS</ulink> de
    l'université de Laval au Québec, qui s'appuie sur la version 1.4.3 de
    <ulink url="???">Lucene</ulink> en l'enrichissant de fonctionnalités pour
    exploiter une plus large palette de format de fichiers. Elle représente le
    module indexation de l'application inJAC, utilisé à partir du <ulink
    url="http://esup-portail.org/consortium/espace/CMS_3F/cocoon-injac/current/">moteur
    de rendu</ulink>.</para>

    <para><emphasis role="bold">Attention</emphasis> : à partir de la version
    1.1 il faut utiliser le moteur de rendu 2.4 ou supérieur.</para>

    <para>Cette application indexe le contenu d'un espace inJAC, et a donc
    besoin de se connecter à un <ulink
    url="http://esup-portail.org/consortium/espace/Stockage_2F/index.html#Serveur">Serveur
    Webdav</ulink> opérationnel, avec un espace inJac valide.</para>

    <para>Toutefois, dans le cadre d'une utilisation avec un moissonneur OAI,
    le serveur WEBDAV n'est pas requis.</para>

    <para>Sur la machine même, un environnement Java (JRE ou JDK), version
    1.4.X à partir du 1.4.2(non testé sur JDK 1.5), ainsi qu'un moteur de
    servlet/jsp (TOMCAT 5.0.28 ou supérieur) doivent être préalablement
    installés.</para>
  </section>

  <section>
    <title>Changements</title>

    <para><itemizedlist>
        <listitem>
          <para><emphasis role="bold">Version 1.3</emphasis></para>

          <para><itemizedlist>
              <listitem>
                <para>outil de merge d'index configurable par fichier xml
                (voir document d'utilisation, section "Fusion d'index")</para>
              </listitem>

              <listitem>
                <para>amélioration de la visualisation d'un index (navigation
                par pages, visualisation des champs indexés)</para>
              </listitem>

              <listitem>
                <para>repackaging avec fichiers de compilation/déploiement
                ANT</para>
              </listitem>

              <listitem>
                <para>modification du flux de recherche /search (voir
                changelog)</para>
              </listitem>

              <listitem>
                <para>Nouvelles propriétés : <emphasis
                role="bold">oai.indexing.class, oai.encoding, </emphasis>
                <emphasis role="bold">merge.config</emphasis>, <emphasis
                role="bold">merge.liusConfig</emphasis>, <emphasis
                role="bold">maxPageCount</emphasis>, <emphasis
                role="bold">widget.titlebar</emphasis>, <emphasis
                role="bold">widget.content</emphasis> (voir section
                Configuratrion Générale)</para>
              </listitem>

              <listitem>
                <para>Renommage de propriétés : <emphasis
                role="bold">exist.urlField.name</emphasis> devient <emphasis
                role="bold">oai.urlField.name</emphasis> et <emphasis
                role="bold">exist.Config</emphasis>, <emphasis
                role="bold">oai.Config</emphasis> (voir section Configuratrion
                Générale)</para>
              </listitem>

              <listitem>
                <para>les chemins indiqués par <emphasis
                role="bold">oai.Config</emphasis> et <emphasis
                role="bold">liusConfigFile</emphasis> sont désormais relatifs
                à l'application (ex : ex : WEB-INF/configs/xx.xml)</para>
              </listitem>
            </itemizedlist></para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Version 1.2</emphasis><itemizedlist>
              <listitem>
                <para>ajout des contextes indexRecord et indexStringRecord
                pour l'indexation depuis une application distante cliente (de
                type moissonneur OAI-ori-harvester) d'enregistrement OAI (voir
                section Indexation OAI)</para>
              </listitem>

              <listitem>
                <para>remplacement des librairies jaxen-core.jar et
                jaxen-jdom.jar par jaxen-1.1-beta-9.jar</para>
              </listitem>

              <listitem>
                <para>restructuration des packages Java</para>
              </listitem>

              <listitem>
                <para>ajout de propriétés dans le fichier de configuration
                indexation.properties : <itemizedlist>
                    <listitem>
                      <para><emphasis
                      role="bold">field.type.keyword</emphasis> pour définir
                      quelles MD Webdav sont indexées en tant que champ Lucene
                      de type Keyword</para>
                    </listitem>

                    <listitem>
                      <para><emphasis role="bold">renderContext </emphasis>:
                      URI utilisée pour le rendu des documents inJAC.</para>
                    </listitem>

                    <listitem>
                      <para><emphasis role="bold">exist.Config</emphasis> :
                      fichier de configuration du mapping xml des différents
                      formats pour l'indexation OAI</para>
                    </listitem>

                    <listitem>
                      <para><emphasis
                      role="bold">exist.urlField.name</emphasis> : nom du
                      champ défini dans le fichier exist.Config utilisé comme
                      URL d'accès au document dans les résultats de
                      recherche</para>
                    </listitem>
                  </itemizedlist></para>
              </listitem>

              <listitem>
                <para>ajout de l'attribut <emphasis
                role="bold">namespace</emphasis> dans la balise &lt;hit&gt; du
                resultat XML (SearchServlet), définissant le type de
                métadonnées associées au document stocké dans inJAC.</para>
              </listitem>
            </itemizedlist></para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Version 1.1</emphasis><itemizedlist>
              <listitem>
                <para>fil RSS renvoyant une liste des derniers documents
                indexés(voir documentation d'utilisation)</para>
              </listitem>

              <listitem>
                <para>retour des résultats d'une requête en XML ou en HTML et
                corrections liées à l'encodage (voir documentation
                d'utilisation).</para>
              </listitem>

              <listitem>
                <para>possibilité de paramétrer la liste des métadonnées que
                l'on veut dans les résultats(voir documentation
                d'utilisation)</para>
              </listitem>

              <listitem>
                <para>paramétrage des métadonnées correspondant au titre et à
                la description des documents retournés.</para>
              </listitem>
            </itemizedlist></para>
        </listitem>
      </itemizedlist></para>
  </section>

  <section>
    <title>Installation</title>

    <section>
      <title>déployer l'application</title>

      <para>Le déploiement s'effectue en décompressant l'archive dans un
      répertoire accueillant une application WEB Java( répertoire
      <filename>/webapps</filename> de Tomcat par exemple).</para>
    </section>

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

      <para>Une fois décompressé, créer le fichier
      <filename>indexation.properties</filename> à partir du fichier d'exemple
      <filename>indexation.example.properties </filename>situé dans
      i<filename>njac-indexing/WEB-INF/classes</filename> :</para>

      <para><programlisting>#filesystem path to repository for created index
indexPath=F:/injac-indexes
#default values filling create index form
defaultUrl=http://slide-priv:8080/slide/files/injac/injacRoot 
defaultUser=admin
#warning : filling this property makes it visible for any user connecting
# to this application !
# if accessible on public network, better use a dummy value
defaultPassword=password
#default mode for metadata indexing : (none|all|injac)
metadata-mode=all
# config file for LIUS indexer(full path) 
liusConfigFile=/appli/java/injac/tomcat/injac-indexing/WEB-INF/configs/liusFilesConfig.xml

# set to true forces ssl connection 
forceSSL=true
#leave blank if default port 443, else prefix with colon (i.e :8443)
httpsPort=:8443
#warning : setting this property to on makes visible the content of this file for any user accessing this application !
debug=off

# -- RESULT SETTINGS --

#list of metadata names used in different formats configured in Canal Stockage for title and desc
titleMD=title,gen_title
descriptionMD=description,gen_description
#list of indexed MD to include in results (could be overriden by request parameter)
resultMD=document-state,description

#List of md to be indexed as Lucene keyword type fields
field.type.keyword=

# -- URLs params --
# URL of inJac renderer. If not defined URLs will be WEBDAV's ones(overridable by request param)
renderURL=http://injac.monEtablissement.fr/injac
#render context : /nav for browsing mode, /doc for document-only mode
renderContext=/nav

# upper node of inJac spaces. If not defined URLs will be WEBDAV's ones(overridable by request param)
upnode=injacRoot
#extensions for html rendering files 
intDocs=xml html htm txt jpg png gif XML HTML HTM TXT JPG PNG GIF
#css file for html results
cssFile=css/results-skin-esup1.css
#max document per page when viewing an index
maxPageCount=100
#elements for widgets
widget.titlebar=/appli/java/injac/tomcat/webapps/injac-indexing/widgets/titlebar.html
widget.content=/appli/java/injac/tomcat/webapps/injac-indexing/widgets/content.html

#config file for indexing OAI records (full path)
oai.Config=/appli/java/injac/tomcat/injac-indexing/WEB-INF/configs/liusOAIConfig.xml
oai.urlField.name=renderURL
#optimize index frequency
oai.optimize.frequency=100
# class for indexing  from OAI string record - beware to have enough jvm memory if using RAM indexing 
oai.indexing.class=org.injac.indexing.index.oaipmh.StringOAIIndexing
# OAI records encoding type
oai.encoding=UTF-8
# default configuration file for merge command
merge.config=/appli/java/injac/tomcat/injac-indexing/WEB-INF/configs/mergeDC.xml
# config file for merging index
merge.liusConfig=/appli/java/injac/tomcat/injac-indexing/WEB-INF/configs/liusFilesConfig.xml</programlisting></para>

      <para><emphasis role="bold">Attention</emphasis> : Sous Linux, un espace
      à la fin d'une ligne de propriété peut-être fatal ! Vérifiez que les
      paramètres sont immédiatement suivis d'un retour à la ligne !</para>

      <para>Description des paramètres de configuration :</para>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">indexPath</emphasis></para>

          <para>Chemin système désignant le répertoire où vont être générés
          les index.</para>
        </listitem>

        <listitem>
          <para>Informations pour pré-remplir le formulaire de création
          d'index</para>

          <para><itemizedlist>
              <listitem>
                <para><emphasis role="bold">defaultUrl</emphasis> : URL WEBDAV
                de l'espace racine à indexer</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">defaultUser</emphasis> : nom
                d'utilisateur pour l'accès à l'espace racine</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">defaultPassword</emphasis> : mot
                de passe pour l'accès à l'espace racine</para>

                <para><emphasis role="bold">Attention</emphasis> : La
                définition du mot de passe dans le fichier de configuration
                doit s'utiliser uniquement dans le cas d'un réseau privé, car
                il pourra être lu en éditant la source de la page. Si l'accès
                se fait par un réseau public comme Internet, il vaut mieux
                mettre un mot de passe fictif.</para>
              </listitem>

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

                <para><itemizedlist>
                    <listitem>
                      <para>none : aucune métadonnée n'est indexée</para>
                    </listitem>

                    <listitem>
                      <para>all : toutes les métadonnées inJAC sont
                      indexées(dont le nom d'espace est "INJAC:")</para>
                    </listitem>

                    <listitem>
                      <para>injac : seules les métadonnées inJAC de l'espace
                      racine sont indexées</para>
                    </listitem>
                  </itemizedlist></para>
              </listitem>
            </itemizedlist></para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">liusConfigFile</emphasis></para>

          <para>Fichier pour configurer l'indexation (Chemin absolu). Un
          fichier est défini par défaut. Voir la <ulink
          url="http://www.bibl.ulaval.ca/lius/documents/LiusFr.htm#_Toc103747643">documentation</ulink>
          en ligne du projet LIUS concernant le fichier de
          configuration.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">forceSSL</emphasis></para>

          <para>Force l'utlisation de SSL lors de la création d'index, si
          l'accès se fait à travers un réseau public. Ceci garanti le cryptage
          des informations de connexion.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">httpsPort</emphasis></para>

          <para>Port utilisé dans le cas ou forceSSL est égal à "true"</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">debug</emphasis></para>

          <para>Permet d'obtenir des informations de déboggage sur la page
          HTML :</para>

          <para><itemizedlist>
              <listitem>
                <para>"on" = mode deboggage</para>
              </listitem>

              <listitem>
                <para>"off" = mode normal.</para>
              </listitem>
            </itemizedlist></para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">field.type.keyword</emphasis> : liste
          des métadonnées devant être indexées comme des mots-clés,
          c'est-à-dire qui sont indexés d'une seule pièce, au contraire des
          autres métadonnées qui sont indexées comme des textes, et découpés
          en mots séparés.</para>
        </listitem>

        <listitem>
          <para>paramétrages des résultats</para>

          <para><itemizedlist>
              <listitem>
                <para><emphasis role="bold">titleMD</emphasis></para>

                <para>Liste des métadonnées contenant le titre du document
                dans les différents formats de saisie du Canal de
                Stockage</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">descriptionMD</emphasis></para>

                <para>Liste des métadonnées contenant la description du
                document dans les différents formats de saisie du Canal de
                Stockage</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">resultMD</emphasis></para>

                <para>Liste des métadonnées, séparées par des <emphasis
                role="bold">virgules</emphasis>, à renvoyer dans les résultats
                de recherche (voir la documentation d'utilisation)</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">cssFile</emphasis></para>

                <para>Fichier CSS définissant le style pour le rendu HTML des
                résultats de recherche faits avec l'URI <emphasis
                role="bold">htmlSearch</emphasis> (voir la documentation
                d'utilisation).</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">maxPageCount</emphasis></para>

                <para>Nombre de documents listés par page (pour la
                visualisation d'un index).</para>
              </listitem>
            </itemizedlist></para>
        </listitem>

        <listitem>
          <para>paramétrage des widgets<itemizedlist>
              <listitem>
                <para><emphasis role="bold">widget.titlebar</emphasis></para>

                <para>Section de code HTML définissant la barre de titre d'un
                widget.</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">widget.content</emphasis></para>

                <para>Section de code HTML définissant le contenu d'un
                widget.</para>
              </listitem>
            </itemizedlist></para>
        </listitem>

        <listitem>
          <para>paramétrages des liens de rendu des documents inJAC :
          <itemizedlist>
              <listitem>
                <para><emphasis role="bold">renderURL</emphasis> : URL de
                l'instance du module de navigation inJAC liés à l'espace du
                serveur Webdav indexé.</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">renderContext</emphasis> : Les
                valeurs possibles sont : <itemizedlist>
                    <listitem>
                      <para>/nav = document avec contexte de navigation</para>
                    </listitem>

                    <listitem>
                      <para>/doc = document seul</para>
                    </listitem>
                  </itemizedlist></para>
              </listitem>
            </itemizedlist></para>
        </listitem>

        <listitem>
          <para>paramètres de l'indexation OAI :<itemizedlist>
              <listitem>
                <para><emphasis role="bold">oai.Config</emphasis> : nom du
                ficher de configuration (chemin absolu) pour l'indexation de
                fiches(record) OAI.</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">oai.urlField.name</emphasis> : nom
                du champ défini dans le fichier exist.Config utilisé comme URL
                d'accès au document dans les résultats de recherche.</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">oai.optimize.frequency</emphasis>
                fréquence d'optimisation (en nombre de documents)</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">oai.indexing.class</emphasis>
                classe utilisée pour l'indexation OAI. Deux classes sont
                fournies :</para>

                <para><itemizedlist>
                    <listitem>
                      <para>org.injac.indexing.index.oaipmh.StringOAIIndexing</para>
                    </listitem>

                    <listitem>
                      <para>org.injac.indexing.index.oaipmh.RamStringOAIIndexing</para>
                    </listitem>
                  </itemizedlist></para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">oai.encoding</emphasis> : type
                d'encodage des enregistrements OAI envoyés par le
                moissonneur</para>
              </listitem>
            </itemizedlist></para>
        </listitem>

        <listitem>
          <para>paramètres de l'outil de fusion(merge) d'index :<itemizedlist>
              <listitem>
                <para><emphasis role="bold">merge.config</emphasis> : fichier
                de configuration utilisé lorsque la commande merge est
                invoquée sans arguments</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">merge.liusConfig</emphasis> :
                fichier de configuration utilisé pour la fusion
                d'index.</para>
              </listitem>
            </itemizedlist></para>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <title>Configuration de l'indexation OAI</title>

      <para>Le fichier l<filename>iusOAIConfig.xml</filename> défini par
      défaut pour la propriété <emphasis role="bold">oai.Config</emphasis>
      sert à recenser les métadonnées issues d'une section XML d'un
      enregistrement OAI que l'on veut indexer dans des champs Lucene. Une
      balise &lt;xmlFile&gt; est définie pour chaque type de métadonnée que
      l'on veut traiter, identifié par un attribut <emphasis
      role="bold">ns</emphasis> (namespace) :</para>

      <programlisting>&lt;xmlFile ns="http://ltsc.ieee.org/xsd/LOM"&gt;</programlisting>

      <para>Dans le fichier fourni deux formats sont définis : LOM et Dublin
      Core.</para>

      <para>Chaque balise &lt;luceneField&gt; contient un attribut <emphasis
      role="bold">name</emphasis> qui défini le nom du champ indexé, un
      attribut <emphasis role="bold">xpathSelect</emphasis> qui cible quel
      élément XML doit être utilisé pour la valeur du champ, et enfin un
      attribut <emphasis role="bold">type</emphasis> :<programlisting>&lt;luceneField name="renderURL"
xpathSelect="//lom:technical/lom:location" type="Keyword" /&gt;
&lt;luceneField name="title"
xpathSelect="//lom:general/lom:title" type="Text" /&gt;</programlisting></para>
    </section>

    <section>
      <title>Niveau de débogage</title>

      <para>Le niveau de débogage peut être modifié en éditant le fichier
      WEB-INF\classes\log4j.properties. Les niveaux disponibles sont :
      <emphasis role="bold">debug</emphasis>, <emphasis
      role="bold">info</emphasis>, <emphasis role="bold">warn</emphasis>,
      <emphasis role="bold">error</emphasis> et <emphasis
      role="bold">fatal</emphasis>, du plus prolixe au plus concis. Le niveau
      de déboggage influe sur les performances de l'application.</para>

      <para><emphasis role="bold">Note</emphasis> : il faut également adapter
      le chemin du fichier de log, à la ligne :</para>

      <para><programlisting>log4j.appender.R.File=E:/Java/jakarta-tomcat-5.0.28/logs/injac-index.log</programlisting></para>
    </section>
  </section>
</article>