<?xml version="1.0"?>
<!DOCTYPE webpage PUBLIC "-//Norman Walsh//DTD Website V2.1b1//EN" "../../../dtd/website.dtd" [
	<!ENTITY apps SYSTEM "../introduction/applications.xml" NDATA XML>
	<!ENTITY architecture SYSTEM "../introduction/architecture.xml" NDATA XML>
	<!ENTITY bases SYSTEM "../introduction/bases.xml" NDATA XML>
	<!ENTITY config SYSTEM "../configuration/index.xml" NDATA XML>
	<!ENTITY config-bases SYSTEM "../configuration/base.xml" NDATA XML>
	<!ENTITY config-entrepot SYSTEM "../configuration/entrepot.xml" NDATA XML>
	<!ENTITY entrepots SYSTEM "../introduction/entrepots.xml" NDATA XML>
]>
<webpage id="migration_configuration">
	<head>
		<title>La configuration d'une application SDX-2 issue d'une application SDX-1</title>
		<titleabbrev>Configuration</titleabbrev>
		<author>
			<firstname>Martin</firstname>
			<surname>Sévigny</surname>
			<affiliation>
				<orgname>AJLSM</orgname>
			</affiliation>
		</author>
		<revhistory>
			<revision>
				<revnumber>1.0</revnumber>
				<date>2002/10/31</date>
			</revision>
		</revhistory>
	</head>
	<para>Ce document ne constitue pas la documentation complète concernant la configuration d'une application SDX-2. Nous allons seulement indiquer comment les informations de configuration de SDX-1 doivent être modifiées pour la version 2. En d'autres mots, il s'agit d'un guide qui permet de transformer le fichier de configuration d'une application SDX-1 (<filename>db_info.xml</filename>) en fichier de configuration d'une application SDX-2 (<filename>application.xconf</filename>).</para>
	<para>Avant de lire ce guide, il est important de lire et comprendre la section de la documentation qui introduit l'<olink targetdocent="architecture">architecture</olink> de SDX-2. En particulier, il est important de comprendre les notions d'<olink targetdocent="apps">
			<emphasis>applications</emphasis>
		</olink>, de <olink targetdocent="bases">
			<emphasis>bases de documents</emphasis>
		</olink> et d'<olink targetdocent="entrepots">
			<emphasis>entrepôts de documents</emphasis>
		</olink>. De plus, il pourra être utile de se référer à la <olink targetdocent="config">documentation complète de la configuration d'une application SDX-2</olink> pour ajouter des paramètres inexistants en SDX-1 et donc non discutés ici.</para>
	<section>
		<title>Les fichiers impliqués</title>
		<para>En version 1, la configuration d'une application SDX est contenue dans un document XML qui se situait nécessairement dans un fichier <filename>db_info.xml</filename> situé dans un dossier nommé <filename>conf</filename> qui se situe dans le dossier de l'application. Par exemple, pour une application SDX avec identifiant <emphasis>test</emphasis>, la configuration est dans le fichier <filename>webapps/sdx/test/conf/db_info.xml</filename>.</para>
		<para>En version 2, la situation est presque la même. En effet, la configuration est toujours contenue dans un document XML&#xA0;; ce document XML est toujours situé dans le dossier <filename>conf</filename> d'une application, mais il s'appelle maintenant <filename>application.xconf</filename>. Nous devons également souligner que le nom du dossier dans lequel réside une application sous SDX n'a plus besoin de coïncider avec son identifiant, ce qui laisse une certaine souplesse dans le déploiement des applications.</para>
	</section>
	<section>
		<title>Identification et configuration</title>
		<para>Le fichier de configuration d'une application SDX-1 commence de cette manière&#xA0;:</para><programlisting><![CDATA[
<sdx:dbInfo code="sdxdoc"
  xmlns:sdx="http://www.culture.gouv.fr/ns/sdx/sdx">
]]>  
</programlisting>
		<para>En SDX-2, cet élément supérieur devient plutôt quelque chose comme&#xA0;:</para>
		<programlisting><![CDATA[			
<sdx:application
        id="fr.gouv.culture.sdx.sdxworld"
        xml:lang="fr"
        xmlns:sdx="http://www.culture.gouv.fr/ns/sdx/sdx">
]]>          
		</programlisting>
		<para>On doit noter ici que l'élément supérieur est maintenant <sgmltag>&lt;sdx:application/&gt;</sgmltag>, que l'attribut <sgmltag>code</sgmltag> a disparu, que l'espace de noms SDX est le même, et que deux nouvelles informations font leur entrée&#xA0;:</para>
		<orderedlist>
			<listitem>
				<para>L'<emphasis role="bold">identifiant public</emphasis> de l'application, qui devrait être unique parmi toutes les applications SDX, et c'est pourquoi nous invitons à le définir en utilisant la technique des noms de domaines inversés. Par exemple, pour une application de la DRAC Bretagne, cela pourrait être <emphasis>fr.gouv.culture.drac-bretagne.inventaire</emphasis>. Cet identifiant public est obligatoire, et il permet de rendre les bases facilement réplicables d'une installation à l'autre tout en étant utilisé pour identifier les cibles de recherches multibases.</para>
			</listitem>
			<listitem>
				<para>La <emphasis role="bold">langue par défaut</emphasis> de l'application, cette langue pouvant être utilisée pour déterminer des analyseurs de mots par défaut, des algorithmes de tri par défaut, des langues d'interface par défaut, etc. Nous conseillons vivement d'indiquer une langue à l'aide de cet attribut, même s'il s'agit d'une application multilingue. Il est possible de spécifier d'autres langues dans différents contextes, celle associée à cet élément est uniquement une langue par défaut.</para>
			</listitem>
		</orderedlist>
		<para>La suite du fichier de configuration SDX-1 est un élément <sgmltag>&lt;sdx:configuration/&gt;</sgmltag> qui contient des informations sur les langues (<sgmltag>&lt;sdx:languages/&gt;</sgmltag>), les <emphasis>locales</emphasis> (<sgmltag>&lt;sdx:locales/&gt;</sgmltag>), la configuration de l'outil de recherche (<sgmltag>&lt;sdx:lucene/&gt;</sgmltag>), les catalogues d'entités externes (<sgmltag>&lt;sdx:catalogs/&gt;</sgmltag>), la transformation d'indexation (<sgmltag>&lt;sdx:extraction/&gt;</sgmltag>), la transformation préliminaire (<sgmltag>&lt;sdx:transformation/&gt;</sgmltag>) ainsi que certains paramètres (<sgmltag>&lt;sdx:parameters/&gt;</sgmltag>). L'élément <sgmltag>&lt;sdx:configuration/&gt;</sgmltag> lui-même n'est plus nécessaire.</para>
		<para>Nous avons déjà vu comment indiquer la langue par défaut d'une application, les autres méthodes de spécification de langues seront indiquées lorsqu'elles s'appliquent. Les éléments <sgmltag>&lt;sdx:languages/&gt;</sgmltag> et <sgmltag>&lt;sdx:locales/&gt;</sgmltag> ne sont donc plus nécessaires et peuvent être ignorés. La configuration de l'outil de recherche ne se fait plus globalement comme dans SDX-1, c'est pourquoi l'élément <sgmltag>&lt;sdx:lucene/&gt;</sgmltag> n'est plus utile non plus. Son contenu sera réutilisé ailleurs dans la configuration.</para>
		<para>Les catalogues d'entités externes sont toujours utiles en SDX-2, et leur configuration est presque la même. Le seul changement, c'est l'attribut <sgmltag>file</sgmltag> qui est renommé <sgmltag>src</sgmltag>, par souci de cohérence. Son contenu est une URL relative à l'endroit où se situe le fichier de configuration. On peut insérer l'élément <sgmltag>&lt;sdx:catalogs/&gt;</sgmltag> et ses sous-éléments directement sous <sgmltag>&lt;sdx:application/&gt;</sgmltag>.</para>
		<para>Les éléments <sgmltag>&lt;sdx:extraction/&gt;</sgmltag> et <sgmltag>&lt;sdx:transformation/&gt;</sgmltag> sont importants car ils indiquent les transformations XSLT à utiliser pour indexer et peut-être transformer préalablement les documents XML dans SDX. En version 2, ces informations sont précisées selon un mécanisme nettement plus puissant appelé <emphasis>pipeline</emphasis>. Ces deux éléments peuvent donc être supprimés.</para>
		<para>Enfin, les paramètres... TODO.</para>
	</section>
	<section>
		<title>Les informations générales</title>
		<para>Dans la configuration d'une application SDX-1, il était possible de décrire une application en insérant un élément <sgmltag>&lt;sdx:informations/&gt;</sgmltag> et ses sous-éléments. En SDX-2, ces éléments n'existent plus. Toutefois, si vous voulez ajouter toute autre information au document XML de configuration (<filename>application.xconf</filename>), vous pouvez le faire, en autant que vous respectiez ces deux consignes&#xA0;:</para>
		<orderedlist>
			<listitem>
				<para>Utilisez un espace de noms différent de celui de SDX.</para>
			</listitem>
			<listitem>
				<para>Ne modifiez pas la hiérarchisation des éléments de l'espace de noms SDX. Par exemple, l'élément <sgmltag>&lt;sdx:catalogs/&gt;</sgmltag> doit être un enfant immédiat de <sgmltag>&lt;sdx:application/&gt;</sgmltag>. Si vous insérez un élément entre les deux, les catalogues seront pas pris en compte.</para>
			</listitem>
		</orderedlist>
		<para>Cette manière de procéder est nettement plus souple. Nous voulons toutefois signaler qu'il est possible que des informations standards de description des applications SDX soient proposées, par exemple en utilisant des métadonnées Dublin Core.</para>
	</section>
	<section>
		<title>Les bases de documents, les entrepôts  et la recherche</title>
		<para>La dernière partie de la configuration d'une application SDX-1 concerne les champs de recherche, définis dans un élément <sgmltag>&lt;sdx:fieldList/&gt;</sgmltag>. En SDX-2, cette liste de champs sera aussi présente, mais dans le contexte d'une base de documents (voir l'<olink targetdocent="architecture">architecture</olink>).</para>
		<para>Une application SDX-1 est conçue, par définition, avec une seule base de documents et un seul entrepôt, car ces concepts ne sont pas vraiment présents en SDX-1. A tout le moins, le développeur ne peut pas effectuer de choix ou de configuration particulière. Nous allons donc supposer que la migration s'effectue vers une application SDX-2 à une seul base et un seul entrepôt de documents.</para>
		<section>
			<title>L'entrepôt de documents</title>
			<para>Les documents XML indexés par SDX-1 sont stockés dans une base de données relationnelle, par exemple MySQL. Cette option peut aussi être choisie en SDX-2, mais elle n'est pas la seule disponible. On peut également choisir un entrepôt <emphasis>système de fichiers</emphasis> ou un entrepôt <emphasis>URL</emphasis>. Cet aspect de la configuration étant inexistant en SDX-1, nous vous invitons à consulter la documentation sur la configuration des entrepôts pour savoir comment effectuer cette partie de la migration.</para>
			<para>Soulignons toutefois que les documents XML ne pourront pas rester dans votre base relationnelle SDX-1, sauf si vous utilisez un entrepôt URL et que vous mettez en place un outil pour servir ces documents depuis des URL. Cette approche ne permet pas, toutefois, l'ajout de documents par SDX. Vous pouvez donc effectuer votre choix de type et de configuration d'entrepôt sans tenir compte du fait que vous migrez depuis SDX-2.</para>
		</section>
		<section>
			<title>La base de documents</title>
			<para>La configuration de la base de documents sera relativement simple lors d'une migration, car les principales informations sont déjà présentes dans la configuration de l'application en version 1. La documentation de référence concernant la <olink targetdocent="config-bases">configuration des bases de documents</olink> pourra vous être utile si vous voulez aller plus loin.</para>
			<para>Vous devrez d'abord déterminer un identifiant pour votre base de documents, et normalement votre base (unique) devrait être la base par défaut. Le début de la configuration sera donc semblable à ceci&#xA0;:</para>
			<programlisting>
				<sgmltag>&lt;sdx:documentBase id="mon_id" type="lucene" default="true"&gt;</sgmltag>
			</programlisting>
			<para>Ensuite, vous pouvez recopier intégralement l'élément <sgmltag>&lt;sdx:fieldList/&gt;</sgmltag> (et ses sous-éléments) de votre configuration SDX-1 dans votre configuration en version 2. En effet, la définition des champs est totalement compatible.</para>
			<para>SDX-2 vous offre toutefois plus de souplesse quant à la langue des contenus indexés. En version 1, une seule langue par application était possible. En version 2, chaque champ peut avoir sa propre langue, et donc ses propres outils linguistiques. Bien entendu, dans le contexte d'une migration, tous les champs ont la même langue, alors il est conseillé de la définir au niveau de l'élément <sgmltag>&lt;sdx:fieldList/&gt;</sgmltag>, en y ajoutant un attribut <sgmltag>xml:lang</sgmltag> avec le code de langue approprié. Par exemple&#xA0;:</para>
			<programlisting>&lt;sdx:fieldList xml:lang="fr-CA"/&gt;</programlisting>
			<para>Spécifier la langue des champs implique également le choix d'un analyseur de texte pour l'indexation. En SDX-1, c'est l'élément <sgmltag>&lt;sdx:lucene&gt;</sgmltag> qui le précisait, la valeur par défaut étant un analyseur de mots pour le français. En SDX-2, le choix de l'analyseur de mots est une conséquence de la spécification de la langue, sauf indication contraire.</para>
			<para>Si vous voulez spécifier votre propre classe pour un analyseur, vous devez utiliser l'attribut <sgmltag>analyzerClass</sgmltag> et y mettre le nom complet de la classe Java qui doit nécessairement étendre la classe <filename>fr.gouv.culture.sdx.search.lucene.analysis.Analyzer</filename>. Vous pouvez aussi spécifier un fichier de configuration pour l'analyseur à l'aide de l'attribut <sgmltag>analyzerConf</sgmltag>. Ce fichier de configuration peut être spécifié même si vous ne précisez pas de classe particulière.</para>
			<para>La configuration d'une base de documents SDX-2 doit aussi inclure un élément <sgmltag>&lt;sdx:index&gt;</sgmltag> qui indique de quelle manière l'indexation se fera. Cet élément contient un élément <sgmltag>&lt;sdx:pipeline&gt;</sgmltag> qui est la définition d'une séquence de transformations XML. Lors d'une migration, cette configuration sera presque toujours faite ainsi&#xA0;:</para>
			<programlisting>
				<sgmltag>
&lt;sdx:index&gt;
  &lt;sdx:pipeline&gt;
    &lt;sdx:transformation id="step1" type="xslt" src="indexation.xsl"/&gt;
  &lt;/sdx:pipeline&gt;
&lt;/sdx:index&gt;
</sgmltag>
			</programlisting>
			<para>Dans cette configuration, vous devez indiquer dans l'attribut <sgmltag>src</sgmltag> le chemin vers votre feuille de style d'indexation.</para>
			<para>TODO&#xA0;: comment ajouter une transformation préalable?</para>
		</section>
	</section>
</webpage>
