SDX Création de Base SDX

Une base SDX est un Lieu virtuel où des documents XML sont indexés et peuvent être recherchés.<ref>Concept de « base de documents » dans SDX</ref>

Introduction

Ce document à pour but d'expliquer de façons pratique (à travers des exemples) la création et l'exploitation de bases SDX documentaires dans Pleade.

À l'issue de ce document, l'utilisateur devra être capable de créer une nouvelle base documentaire dans Pleade, d'indexer des documents ; et d'établir sur cette nouvelle base les différents service qu'offre Pleade pour la base EAD (recherche, subset, navindex, suggest, etc.).

La création des bases dans Pleade est native ; elle se fait suivant un ensemble d'étapes bien déterminées. Ces dernières peuvent à leur tour être subdivisées en plusieurs autres étapes (exemple l'étape de publication d'un document dans la base EAD est subdivisé en quatorze sous étapes).

Ce document n'a pas pour but d'expliquer la création d'un système d'indexation aussi complexe que l'EAD dans Pleade, mais, il explique la gestion de l'indexation d'un forme de document simple (profondeur 1).

Pré-requis

Dans la suite de ce document nous allons supposé vouloir indexer une base KML nommée maBase dont un exemple de document à la structure suivante :

<?xml version="1.0" encoding="UTF-8"?>
<NOTICE>
  <GFIELD>Registre matricule</GFIELD>
  <COLLECTION>Registre matricule</COLLECTION>
  <SUBDIVISION>bureau de Langres</SUBDIVISION>
  <REF>00001</REF>
  <PATRONYME>Terrasse</PATRONYME>
  <PRENOMS>François Hippolyte</PRENOMS>
  <SURNOM>non renseigné</SURNOM>
  <SUPPLEANT>non renseigné</SUPPLEANT>
  <ANNEE_NAISSANCE>1849</ANNEE_NAISSANCE>
  <COMMUNE_NAISSANCE>Bugnières</COMMUNE_NAISSANCE>
  <COMMUNE_DOMICILE>Bugnières</COMMUNE_DOMICILE>
  <INTITULE_DOCUMENT>Registre matricule, bureau de Langres</INTITULE_DOCUMENT>
  <COTE>R 741/01</COTE>
  <IDENTIFIANT_PREMIERE_IMAGE>FRAD052_R0757_01_001.jpg</IDENTIFIANT_PREMIERE_IMAGE>
</NOTICE>

Déclaration de la base dans l'application

Cette première phase consiste à indiquer à Pleade le nom de la nouvelle base ainsi que les configurations nécessaires pour l'indexation (identifiant de la base, champs à index, structure des index, etc.). C'est dans cette étape aussi qu'on défini les entrepôts OAI pour cette base. Pour cela, on modifiera le fichier <app>/module-eadeac/conf/application.xconf<ref>Schema XML du fichier application.xconf</ref><ref>Exemple détaillé de fichier applications.xconf</ref>. Ci-dessous, un exemple de déclaration dans un Pleade fraichement installé :

<!--+ | Configuration de l'application SDX Pleade
 +--><application    xmlns="http://www.culture.gouv.fr/ns/sdx/sdx"  indexation-logging-level="1"  id=""  xml:lang="fr"  sessionObjectLimit="20">
    <!-- Catalog  file  for  EAD  -->
    <catalogs>
        <catalog  src="dtd/catalog"/>
    </catalogs>
    <admin  groupId="admins"  userId="admin"  userPassword="Pleade3"  />

    <!-- Déclaration de la liste des champs Lucene (d'indéxation) -->
    <!-- On externalise la liste des champs dans des fichiers <base>-fieldList-<type>.xconf -->
    <fieldLists>
        <xi:include  href="cocoon:/conf/ead-fieldlist.xconf" xmlns:xi="http://www.w3.org/2001/XInclude"  />
        <xi:include  href="cocoon:/conf/eac-fieldlist.xconf"  xmlns:xi="http://www.w3.org/2001/XInclude"  />
        <!-- Déclaration de la liste des champs Lucene (d'indéxation) -->
        <!-- URL résolu dans les sitemap, aggrège : champs de base, index, champs aggrégés, champs dupliqués -->
       <xi:include   href="cocoon:/conf/maBase-fieldlist.xconf" xmlns:xi="http://www.w3.org/2001/XInclude" />
    </fieldLists>

    <!--  Les  bases  de  documents  -->
    <documentBases>
        <xi:include  href="cocoon:/conf/ead-documentbase.xconf"  xmlns:xi="http://www.w3.org/2001/XInclude"  />
        <xi:include  href="cocoon:/conf/eac-documentbase.xconf"  xmlns:xi="http://www.w3.org/2001/XInclude"  />
        <!-- déclaration  base  maBase-->
        <xi:include  href="cocoon:/conf/maBase-documentbase.xconf"  xmlns:xi="http://www.w3.org/2001/XInclude"  />
    </documentBases>
</application>

La ligne 13 indique l'emplacement du fichier décrivant la liste des champs de la base, ici <app>/module-eadeac/conf/maBase-fieldlist-base.xconf. Son contenu est détaillée dans la section déclaration des champs de la base.

La ligne 21 quand à elle revnoi vers le fichier <app>/module-eadeac/conf/maBase-documentbase.xconf qui déclare la base, telle que détaillé dans la section déclaration de la base.

Déclaration de la base et de ses ressources : maBase-documentbase.xconf

La déclaration de la base se structure de la façon suivante :

• la base (<documentBase>)
  • son identifiant (id),
  • son entrepôt de donnée (<repository>)
  • le type de dépôt (type).
• et ses ressources associées :
  • la liste des champs décrit dans <fieldList> (souvent externalisés via un <xi:include>),
  • la feuille d'indexatione de la base <transformation>
  • les entrepôts OAI (<oai-repository>).

Voici un exemple avec une déclaration interne des champs de la base (cf. éléments <field>) :

<documentBase id="maBase" type="lucene" keepOriginalDocuments="false">
<!--L'entrepôt pour les documents-->
<repositories>
  <repository type="FS" id="maBase-docs" baseDirectory="docs/maBase" depth="2" extent="50" default="true" />
</repositories>

<!-- Déclaration de la liste des champs Lucene (d'indéxation) -->
<fieldList id="maBase-fieldlist" analyzerConf="analysis/fr.xml" xml:lang="fr">
    <!-- Déclaration de la liste des champs Lucene (d'indéxation) -->
    <!-- URL résolu dans les sitemap, aggrège : champs de base, index, champs aggrégés, champs dupliqués -->
    <xi:include href="cocoon:/conf/maBase-fieldlist.xconf" xmlns:xi="http://www.w3.org/2001/XInclude" />
</fieldList>

<!-- Les étapes de transformation des documents au moment de la publication. -->
<index>
  <pipeline id="index-bdmaBase">
    <!-- Remplissage des champs -->
    <transformation id="fields" type="SAXONXSLT" src="../xsl/publication/maBase/maBase-fields.xsl"/>
  </pipeline>
</index>

<!-- Entrepôt OAI&nbsp;: NB : les champs vides seront remplies par le parametres.xconf -->
<oai-repository name="" baseURL="" adminEmail="" noPerResponse="" id="maBase-oai" default="true">
  <!-- Le subset sera rempli en fonction du paramètre records -->
  <oai-subset>
  </oai-subset>

  <!-- Format OAI-DC -->
  <oai-format name="OAI Dublin core" metadataPrefix="oai_dc"
    namespace="http://www.openarchives.org/OAI/2.0/oai_dc/"
    schemaUrl="http://www.openarchives.org/OAI/2.0/oai_dc.xsd"
  >
    <pipeline id="to-oaidc">
      <transformation id="oai-dc" type="XSLT" src="oai-repository/ead/qdc/oai-dc.xsl" />
    </pipeline>
  </oai-format>
</oai-repository>
</documentBase>

Remarques : L'élément <pipeline> indique les fichiers qui permette de modifier successivement (mécanisme <map:transform> de Cocoon) le document final à indexer par le SDX. Dans la plupart des cas, nous n'aurons besoin que d'un seul transformateur, appelé (maBase-fields.xsl), qui s'occupera simplement de remplir les différents champs SDX déclarés à partir du fichier XML d'entrée.

Remarques : L'utilisation de FS comme valeur de type implique que les données d'indexation sont stockées sous forme de système de fichier (dossier sdx-data ou datadir).

Déclaration des champs de la base : maBase-fieldlist-base.xconf

On préférera déclarer les champs de façon externes dans le but d'améliorer la lisibilité des documents XML et en facilité la correction. Le fichier décrivant les champs de la base doit se situer dans <app>/module-eadeac/conf/maBase-fieldlist-base.xconf. Ce fichier se contient les informations suivantes :

• un analyseur définit par l'attribut analyzerConf de l'élément racine <fieldList>,
• la liste champs de recherche, défini par des éléments <field>, chacun ayant au moins :
  • un nom name,
  • et un type (field vs. word vs. unindexed),

<fieldList id="bm-orleans-fieldslist"
    xmlns="http://www.culture.gouv.fr/ns/sdx/sdx"
    analyzerConf="/sdx/resources/conf/analysis/fr.xml"
    xml:lang="fr"
>
  <!-- Le champ par défaut -->
    <field name="base" type="unindexed" brief="true" />

    <field name="REF" type="field" />
    <field name="PATRONYME" type="field" brief="true"/>
    <field name="PRENOMS" type="field" brief="true"/>
    <field name="SURNOM" type="field" />
    <field name="ANNEE_NAISSANCE" type="field" brief="true"/>
    <field name="COMMUNE_NAISSANCE" type="unindexed" brief="true"/>
    <field name="COMMUNE_DOMICILE" type="unindexed" brief="true"/>
    <field name="COLLECTION" type="field" />
    <field name="SUBDIVISION" type="field" />
    <field name="COTE" type="field" />
    <!-- Les champs de type word :  destinés à des recherches de type « libre » -->
    <!-- Les champs de type field (ou « valeur ») : sont destinés à une recherche exacte -->

<!-- Champs Pleade -->
    <field name="searchable" type="field"/>
    <field name="fulltext" type="word"/>
    <field name="base" type="unindexed" brief="true" />
</fieldList>

Pour la création et la configuration des champs se référer à la documentation de Pleade correspondante.

Important :

Chaque document à indexer doit posséder une référence unique qui va lui servir d'identifiant dans la base. Cette référence peut être soit :

• fournie par le document (dans notre cas le champs <REF> ou le champs <eadid> dans le cas d'un document EAD) ;
• générer automatiquement durant l'indexation (voire suite du document)..

Notice :

Les mécanismes de gestion avancés des champs et index pour l'EAD (champs agrégées, champs multivalués, etc.) ne sont pas disponibles par défaut. Il faut les implémenter indépendamment comme décrit dans la section suivante, nous détaillerons un exemple d'implémentations de champs agrégées pour la base maBase.

Externalisation de la liste des champs : maBase-fieldlist-base.xconf

Pour plus de clarté, les champs d'indexations peuvent être déclarer dans un fichier maBase-fieldlist-base.xconf. Dans ce cas, il faudra également adapter le contenu du fichier application.xconf comme suit :

<!-- Inclure la liste des champs Lucene -->
<fieldLists>
  <xi:include href="cocoon:/conf/ead-fieldlist.xconf" xmlns:xi="http://www.w3.org/2001/XInclude" />
  <xi:include href="cocoon:/conf/eac-fieldlist.xconf" xmlns:xi="http://www.w3.org/2001/XInclude" />
  <xi:include href="cocoon:/conf/maBase-fieldlist-base.xconf" xmlns:xi="http://www.w3.org/2001/XInclude" />
</fieldLists>

La fichier maBase-fieldlist-base.xconf est ensuite renseigné à l'image du fichier ead-fieldlistlist-base.xconf.

D'autres fichiers à mettre à jour

• pleade-libre/src/webapp/module-eadeac/conf/utils/sdx-xconf.xsl - Ce fichier genère le repository vers la base de données automatiquement pour ead, eac, mets, oai_dc, et qdc mais pas les nouveaux document bases. Faire une recherche pour "oai_dc" par exemple.

Indexation de la nouvelle base

Dans cette section, nous allons présenté les différents mécanismes à mettre en place pour pouvoir indexer un document de type maBase. Ces mécanismes consistent essentiellement à la mise en place de pipelines. Ces derniers seront à placer dans le fichier local.xmap.

Remarques : Pour plus de clarté, les fichiers sources (.xsl, .xsp, etc.) des pipelines de cette section seront présentés dans la section Annexe.

Les mécanismes d'authentifications seront présentés dans la section paramétrage avancés.

Pré-requis

Avant de pouvoir faire des publications et indexations, il est nécessaire de savoir où les données à publier sont stockées. Pour cela on définira une variable d'applications dans le fichier <app>.

Indexation par URL

Il faut mettre en place les pipelines nécessaire à la publication. C'est à dire :

<pipeline-gérant-la-publication>

Tester l'indexation

http://projet/results.debug?base=maBase&champ1=fulltext&op1=AND&search_type=simple&query1=sdxall%3A1&ssearch-submit-npt.x=5&ssearch-submit-npt.y=11

Termes indexés

http://bm-orleans.dev/functions/sdx-terms.xml?&base=maBase&field=monChamps

Important :

Commencé par mettre la déclaration dans le corps du fichier maBase-documentbase.xconf et externalisé les ensuite. Cela évitera les problèmes inutiles.

Indexation par l'interface

Deux fichiers sont nécessaires pour cela :

• <app>/module-eadeac/xsl/maBase-publish.xsl
• <app>/module-eadeac/xsl/maBase-publish-form.xsl

Formulaire de publication

Mise en place d'un formulaire de publication simple dans Pleade. On rajoutera le code suivant dans un sitemap, si vous ne savait pas dans quel sitemap le placer, ajouter le à local.xmap :

<map:match pattern="edit/maBase\-publish\-form\.(xsp|debug)" id="main-maBase-edit-publish-form" type="regexp">
  <map:aggregate element="aggregate">
    <map:part src="module-eadeac/xsp/maBase-publish-form.xhtml" element="template"/>
    <map:part src="cocoon://edit/functions/edit-publish/maBase-documents.xml"/>
    <map:part src="cocoon:/edit/functions/edit-publish/get-properties-publication.xml"/>
    <map:part src="cocoon:/edit/functions/edit-publish/get-properties-display.xml"/>
    <map:part src="cocoon:/edit/functions/list-search-forms.xml" element="search-forms"/>
    <map:part src="cocoon:/edit/functions/edit-publish/frag-method.xml"/>
    <map:part src="cocoon:/edit/functions/edit-publish/toc-method.xml"/>
    <map:part src="cocoon:/edit/functions/edit-publish/notsearchable-method.xml"/>
    <map:part src="cocoon:/edit/functions/edit-publish/title-method.xml"/>
    <map:part src="cocoon:/edit/functions/edit-publish/index-global.xml"/>
    <map:part src="cocoon:/edit/functions/edit-publish/inheritance.xml"/>
    <map:part src="cocoon:/edit/functions/edit-publish/index-local.xml"/>
    <map:part src="cocoon://functions/get-subset-hierarchy.xml" element="subsets"/>
  </map:aggregate>
  <map:select type="simple">
    <map:parameter name="value" value="{1}"/>
    <map:when test="xsp">
      <map:transform type="xslt2" src="module-eadeac/xsl/maBase-publish-form.xsl">
        <map:parameter name="locale" value="{request-attr:locale}"/>
        <map:parameter name="theme" value="{baselink:sitemapBaseLink}../"/>
        <map:parameter name="tmpdir" value="{contextpath:${Pleade.csv-tmp-dir}}"/>
      </map:transform>
      <map:act type="locale">
        <map:transform type="i18n">
          <map:parameter name="locale" value="{locale}"/>
          <map:parameter name="default-catalogue-id" value="module-eadeac-edit"/>
        </map:transform>
      </map:act>
      <map:serialize type="xhtml"/>
    </map:when>
    <map:otherwise>
      <map:serialize type="xml"/>
    </map:otherwise>
  </map:select>
</map:match>

Résultat de recherche

On travaillera dans le fichier module-eadeac/xsp/sdx-results.xsp.

Paramétrages avancés

À faire :

• Base de donnée sdx-csv-repositry
• Authentification dans les pipelines d'indexation

Création de la document base dans la base de données

Repository

• LuceneDocumentBase.configure(Configuration configuration)
  • SDXDocumentBase.configure(Configuration configuration)
    • SDXDocumentBase.configureRepositories(Configuration configuration)
      • ligne 349 : repo = ConfigurationUtils.createRepository(super.getLog(), super.getContext(), super.getServiceManager(), repoConfList[i]);
        • ConfigurationUtils.createRepository(Logger logger, org.apache.avalon.framework.context.Context context, ServiceManager manager, Configuration repoConf)
          • JDBCRepository.init()
            • JDBC.createTable(Connection conn)
            • AbstractJDBCDatabase

Database

• LuceneDocumentBase.configure(Configuration configuration)
  • SDXDocumentBase.configure(Configuration configuration)
    • SDXDocumentBase.configureRepositories(Configuration configuration)
      • ligne 349 : repo = ConfigurationUtils.createRepository(super.getLog(), super.getContext(),

Liens

• Pour tester les document bases que vous avez créés utiliser un lien comme : http://localhost:8080/pleade-libre/conf/application.xconf

Références

<references/>