Documentation SDX v 1.1 - Le fichier de configuration d'une base de documents

Introduction

La configuration d'une base de documents consiste à consigner dans un document XML quelques informations générales que doit connaître SDX au sujet de votre base, mais surtout la liste des champs de recherche définis pour cette base de documents. Ce document XML doit avoir un élément nommé sdx:dbInfo et utiliser le domaine de nom sdx dont l'URI est http://www.culture.gouv.fr/ns/sdx/sdx.

La configuration

Les éléments de configuration sont essentiels. Ils sont inclus soit comme attribut de l'élément sdx:dbInfo soit dans le sous-élément sdx:configuration. Voici un exemple complet de la section de configuration :

<?xml version="1.0"?>
<sdx:dbInfo code="sdxdoc" xmlns:sdx="http://www.culture.gouv.fr/ns/sdx/sdx">

 <sdx:configuration>

  <sdx:languages>
    <sdx:language default="1" code="fr"/>
    <sdx:language code="en"/>
  </sdx:languages>

  <sdx:locales>
    <sdx:locale language="fr" country="FR"/>
    <sdx:locale language="en" country="UK"/>
  </sdx:locales>

  <sdx:lucene>
    <sdx:index path="_lucene"/>
    <sdx:analyzer class="fr.gouv.culture.sdx.index.FrenchStandardAnalyzer"/>
  </sdx:lucene>

  <sdx:catalogs>
    <sdx:catalog file="catalog"/>
  </sdx:catalogs>

  <sdx:extraction>
    <sdx:ssh file="index.xsl"/>
  </sdx:extraction>

  <sdx:transformation>
    <sdx:ssh file="transform.xsl"/>
  </sdx:transformation>

  <sdx:parameters>
    <sdx:parameter name="nbQueriesInSession" value="10"/>
    <sdx:parameter name="nbDocumentsToIndex" value="100"/>
  </sdx:parameters>

 </sdx:configuration>

...
</sdx:dbInfo>

Le code de base de documents

Le code de la base de documents doit être répété en attribut code de l'élément sdx:dbInfo. S'il ne s'y trouve pas, le fichier de configuration ne sera pas traité et la base ne sera pas active. N'oublions pas que ce code doit aussi correspondre à :

Au nom du répertoire sous webapps/sdx où se situent vos fichiers de bases de documents.
Au code de base de documents que vous avez utilisé ou que vous utiliserez dans l'interface d'administration SDX pour ajouter cette base de documents.

Les langues

SDX n'est pas complètement multilignue, mais certaines fonctions le sont et surtout il pourra l'être éventuellement. Il est possible de préciser des langues d'interface dans la configuration SDX, mais pas obligatoire. Si aucune langue n'est spécifiée, on considère la langue comme étant celle définie par défaut et passée en paramètre à l'environnement SDX grâce au fichier web.xml.

Si vous voulez préciser la ou les langues d'interface disponibles dans votre application, vous pouvez le faire à l'aide de l'élément sdx:languages et de ses sous-éléments sdx:language. L'attribut default indique qu'il s'agit de la langue par défaut, et l'attribut code doit contenir un code de langue valide selon la norme ISO 639.

Pour l'instant, aucune utilisation n'est faite de ces informations, mais elles sont stockées.

Les localisations

Ces informations doivent être comprises dans leur sens Java, tel que le définit, par exemple, la classe java.util.Locale. Pour l'instant, les informations de localisation sont uniquement utilisées lors du tri des termes d'une liste ou de résultats de recherche. De plus, seule la première information de localisation est prise en compte, les autres sont stockées mais ignorées.

Une information de localisation est constituée de deux parties, un code de langue ISO 639 et un code de pays ISO 3166. Par exemple, pour un tri selon la langue canadienne française, les informations seraient respectivement fr et CA.

Par défaut, les informations de localisation sont à fr et FR.

L'index Lucene

Lucene est l'outil de recherche utilisé par SDX. Il gère sa propre structure de fichiers inversés, et même si Lucene peut être un peu plus général, pour l'instant SDX exige que ces fichiers soient stockés dans un répertoire. L'élément sdx:index et son attribut path indiquent le chemin d'accès de ce répertoire, interprété de façon relative au sous-répertoire conf de la base de documents. Il n'est pas possible de le situer ailleurs, et la valeur par défaut est _lucene.

Par ailleurs, Lucene utilise un analyseur syntaxique pour extraire les mots des chaînes de caractères qu'il indexe. Pour l'instant, un seul analyseur syntaxique est permis par base de documents, et la classe qui implante cet analyseur syntaxique peut être spécifiée dans l'élément sdx:analyzer et son attribut class.

Par défaut, c'est la classe fr.gouv.culture.sdx.index.FrenchStandardAnalyzer qui est utilisée. Cet analyseur effectue essentiellement trois opérations sur le texte : il sépare les mots, il supprime les mots vides et il transformes les lettres majuscules en lettres minuscules. Si on désire utiliser un analyseur qui désaccentue également les lettres, on doit spécifier la classe fr.gouv.culture.sdx.index.FrenchUnaccentedAnalyzer, également livrée avec SDX.

Si on spécifie une autre classe, elle doit implanter l'interface com.lucene.analysis.Analyzer.

Les catalogues d'entités externes

Les catalogues d'entités externes sont nécessaires lorsque les documents XML font référence à des DTD ou d'autres entités externes, et que ces entités externes ne sont pas appelées par une URL absolue. Dans ce cas, il faut indiquer à SDX et ses outils XML où se trouvent les entités externes, en fonction, par exemple, de leur chemin relatif.

Ces catalogues sont stockés dans des fichiers qui respectent le standard OASIS. Vous n'êtes pas obligés d'utiliser des catalogues, et vous pouvez en spécifier autant que vous voulez, ils seront tous pris en compte. L'élément sdx:catalog contient en attribut file le nom du fichier de catalogue, qui doit se trouver dans le répertoire conf. Pour utiliser plusieurs catalogues, répétez l'élément sdx:catalog.

La transformation d'indexation

Les documents XML doivent être manipulés afin d'être indexés. Cette manipulation s'effectue à l'aide d'une feuille de style XSLT. L'élément sdx:ssh dans l'élément sdx:extraction contient en attribut file le nom du fichier contant la feuille de style XSLT. Encore une fois, cette feuille de style doit être située dans le répertoire conf.

La transformation initiale

Pour certaines bases de documents, il peut être préférable de transformer les documents XML avant leur indexation et leur manipulation par SDX. Si c'est le cas, on doit utilisé un élément sdx:transformation qui contient un élément sdx:ssh, l'attribut file de ce dernier indiquant la feuille de style XSLT utilisée pour cette transformation. A noter que dans une telle situation, l'indexation s'effectue sur le résultat de cette transformation et que les documents originaux et les documents transformés sont stockés dans la base de données. Toutes les opérations de consultation de SDX s'effectuent sur le document transformé, mais la sauvegarde s'effectue à partir des documents originaux.

Les paramètres

On peut fournir à SDX différents paramètres, à l'aide de l'élément sdx:parameter, le nom du paramètre étant spécifié dans l'attribut name et sa valeur dans l'attribut value. Les paramètres reconnus par SDX sont les suivants :

nbQueriesInSession

Le nombre de requêtes de recherche à conserver en mémoire dans l'objet de session. Les requêtes sont concervées afin de permettre de diviser les résultats en page et de ne pas refaire la requête à chaque changement de page. Cette requête étant stockée dans l'objet de session, elles sont nécessairement associées à un utilisateur en particulier.

Ce paramètre permet de gérer l'espace mémoire utilisé par SDX, car plus le nombre de requêtes conservées est élevé, plus les besoins en mémoire sont importants. Par défaut, le nombre de requêtes conservées est de 5. Si vous utilisez ce paramètre et que vous donnez comme valeur un nombre entier, ce nombre remplacera la valeur par défaut.

nbDocumentsToIndex

Lorsque SDX charge des documents, il effectue l'indexation par lots de documents plutôt qu'individuellement, et ce afin d'accélérer le processus. Par défaut, le nombre de documents par lot est de 50, mais vous pouvez modifier cette valeur avec ce paramètre.

Plus le nombre de documents par lot est élevé, plus l'indexation sera rapide, mais aussi plus les utilisateurs en consultation risquent d'être perturbés, et plus la mémoire nécessaire sera grande. En utilisation normale, le nombre de documents devrait être ajusté de façon à ce que l'indexation d'un lot puisse se faire en quelques secondes. Lors d'une opération de chargement d'un grand nombre de documents, il peut être augmenté préalablement.

Les informations générales

Les informations générales fournissent essentiellement le nom et une courte description de la base de documents. Ces informations peuvent être dans plusieurs langues, et elles sont restituées dans les documents XML dynamiques générés pas SDX et passés aux feuilles de style. Toutefois, seuls les noms et descriptions dans la langue d'interface en cours sont insérés dans ces documents XML dynamiques.

Ces informations sont spécifiées de cette façon :

<?xml version="1.0"?>
<sdx:dbInfo code="sdxdoc" xmlns:sdx="http://www.culture.gouv.fr/ns/sdx/sdx">

 <sdx:configuration>
  ...
 </sdx:configuration>

 <sdx:informations>
  <sdx:names>
    <sdx:name xml:lang="fr">Documentation SDX</sdx:name>
    <sdx:name xml:lang="en">SDX documentation</sdx:name>
  </sdx:names>

  <sdx:descriptions>
    <sdx:description xml:lang="fr">La documentation utilisateurs et
       technique de SDX.</sdx:description>
    <sdx:description xml:lang="en">SDX technical and user
       documentation.</sdx:description>
  </sdx:descriptions>
</sdx:informations>

...
</sdx:dbInfo>

Les constructions XML standards pour l'identification des langues sont utilisés (attribut xml:lang).

Les champs de recherche

Les champs de recherche constituent le coeur du fonctionnement SDX. Ils permettent non seulement la recherche d'information, mais aussi de considérer les documents comme des bases de données.

Les champs sont définis dans le fichier de configuration, dans un élément sdx:fieldList qui contient une série d'élément sdx:field. Pour chaque champ, les informations suivantes peuvent être spécifiées :

Code	Le code du champ, ou son nom si on préfère. Ce nom doit être unique dans la base de documents. De plus, il semble que les caractères _ (underscore) ne sont pas acceptés. Il est donc préférable de ne pas utiliser de caractères spéciaux, ni de lettres accentuées. Le code est spécifié à l'aide de l'attribute code de l'élément sdx:field. Il est obligatoire.
Format bref	La valeur d'un champ peut être incluse dans le format bref de présentation du document. Ce format bref est utilisé lors de la présentation des résultats d'une recherche. Par défaut, un champ n'est pas inclus dans le résultat bref. Pour inclure le champ, il faut ajouter un attribut brief à l'élément sdx:field, et lui donner une valeur vraie, par exemple 1 ou true.
Champ par défaut	Il existe un concept de champ par défaut dans SDX. Celui-ci est utilisé lorsqu'aucun champ n'est spécifié dans les requêtes de recherche. Très souvent, on utilisera un champ de type "plein texte" comme champ par défaut. Pour définir un champ par défaut, il faut ajouter un attribut default à l'élément sdx:field, et lui donner une valeur vraie, par exemple 1 ou true. Un seul champ par défaut peut être défini, si l'attribut default est utilisé dans plusieurs éléments, seul le dernier sera pris en compte.
Type de champ	Il existe quatre types de champs dans SDX. Ces types sont : Mot : la valeur du champ est analysée et les mots sont extraits, chaque mot devenant un terme cherchable. Pour un tel champ, la valeur de l'attribut type doit être word. Champ : la valeur du champ est laissée telle quelle. Pour un tel champ, la valeur de l'attribut type doit être field. Date : la valeur du champ est convertie en date, et la recherche d'intervalles de dates est alors possible, de même que la recherche de dates précises. Les dates possibles vont de l'an 0 jusqu'à l'an 20 000, la précision peut être une année, un mois, une journée, une heure, une minute ou une seconde. Les formats de date acceptés sont de la forme aaaa/mm/jj hh:mm:ss ou aaaa-mm-jj hh:mm:ss. On peut s'arrêter à n'importe quel groupe, par exemple une date telle que 1999/04 sera interprétée correctement comme le mois d'avil 1999. Pour un tel champ, la valeur de l'attribut type doit être date. Non indexé : le champ ne sera pas indexé, donc non cherchable, mais il sera retourné dans les résultats de recherche. De plus, il pourra être utilisé comme clé de tri. Pour un tel champ, la valeur de l'attribut type doit être unindexed.

Il est prévu, éventuellement, d'ajouter un type de champ numérique qui permettra de faire des recherches par intervalle.

De plus, les éléments sdx:field peuvent contenir des sous-élément sdx:name qui indiquent le nom du champ dans autant de langues que l'on désire. Ces noms sont stockés par SDX, mais ne sont pas utilisés pour l'instant.

Par ailleurs, l'élément sdx:fieldList peut prendre un attribut ignoreCase qui, si sa valeur est vraie (vrai, true, 1), signifie que la casse des noms de champ n'est pas significative. A noter que dans un tel cas, l'utilisation de l'API Java doit se faire avec attention, car tout ce qui concerne les requêtes de recherche ne tient pas compte de la casse, mais si on manipule directement les termes d'un index, les filtres, les critères, etc., alors on doit fournir le nom des champs dans la casse dont ils ont été définis.

Voici un exemple partiel d'un fichier de configuration, qui définit quelques champs de recherche :

<?xml version="1.0"?>
<sdx:dbInfo code="sdxdoc" xmlns:sdx="http://www.culture.gouv.fr/ns/sdx/sdx">

 <sdx:configuration>
  ...
 </sdx:configuration>

 <sdx:informations>
  ...
 </sdx:informations>

 <sdx:fieldList>
  <sdx:field code="fulltext" type="word"default="1">
    <name xml:lang="fr">Texte intégral</name>
    <name xml:lang="en">Full text</name>
  </sdx:field>

  <sdx:field code="title" type="field" brief="1">
    <name xml:lang="fr">Titre</name>
    <name xml:lang="en">Title</name>
  </sdx:field>

  <sdx:field code="modification" type="date">
    <name xml:lang="fr">Date de dernière modification</name>
    <name xml:lang="en">Last modification date</name>
  </sdx:field>

  <sdx:field code="author" type="field">
    <name xml:lang="fr">Auteur</name>
    <name xml:lang="en">Author</name>
  </sdx:field>

 </sdx:fieldList>

</sdx:dbInfo>

Les champs systèmes

Il existe huit champs de recherche par défaut dans SDX, et il est interdit de réutiliser les mêmes noms. Ces champs et leur signification sont :

sdxdocid	L'identifiant du document. Unique dans toute la base de documents. Il s'agit d'un champ de type champ.
sdxstatus	Le statut du document, les valeurs de ce statut sont gérées par les applications et non par SDX. Il s'agit d'un champ de type champ.
sdxmodificationdate	La date de modification du document dans la base, information externe au document lui-même et gérée par SDX. Il s'agit d'un champ de type date.
sdxcreationdate	La date de création du document dans la base, information externe au document lui-même et gérée par SDX. Il s'agit d'un champ de type date.
sdxindexed	Un champ booléen qui indique si le document est indexé ou non. Il s'agit d'un champ de type champ dont les valeurs peuvent être true ou false.
sdxowner	Le code d'utilisateur du propriétaire de ce document. Il s'agit d'un champ de type champ.
sdxscore	Ce champ est créé seulement pour permettre des tris de façon uniforme. Il contient l'indice de pertinence du document pour une requête, et varie donc avec le temps. Il ne faut pas manipuler ce champ.
sdxall	Ce champ permet de retrouver tous les documents d'une base à l'aide d'une requête de recherche. Tous les documents ont la valeur 1 pour ce champ.

Ces champs ne doivent pas faire partie du fichier de configuration, ils sont systématiquement créés et alimentés par SDX.