<?xml version="1.0"?>
<!DOCTYPE webpage PUBLIC "-//Norman Walsh//DTD Website V2.1b1//EN" "../../../dtd/website.dtd" [
  <!ENTITY api-sdx SYSTEM "../api-sdx/api-sdx.xml" NDATA XML>
  <!ENTITY attaches SYSTEM "attaches.xml" NDATA XML>
  <!ENTITY fragments SYSTEM "fragmentation.xml" NDATA XML>
  <!ENTITY original SYSTEM "original.xml" NDATA XML>
  <!ENTITY parametres SYSTEM "parametres.xml" NDATA XML>
  <!ENTITY pipeline SYSTEM "pipeline.xml" NDATA XML>
  <!ENTITY schema-api SYSTEM "../../schemas/api-sdx.xsd" NDATA XML>
]>

<webpage id="indexation_pipeline"> 

  <head>
	 <title>Pipeline d'indexation</title>
	 <titleabbrev>Pipeline</titleabbrev>
	 <author>
		<firstname>Martin</firstname>
		<surname>Sévigny</surname>
		<affiliation>
		  <orgname>AJLSM</orgname> 
		</affiliation>
	 </author>
	 <revhistory>
		<revision>
		  <revnumber>1.0</revnumber> 
		  <date>2003-06-03</date> 
		</revision>
	 </revhistory>
  </head>

  <para lang="fr">Les documents XML passent à travers une ou plusieurs transformations avant d'être indexés. Ces transformations sont regroupées sous le concept de <emphasis>pipeline</emphasis>. L'objectif de ce pipeline est de fournir à SDX l'information dont il a besoin pour gérer correctement l'indexation du document, de ses 
	 <olink targetdocent="fragments">fragments</olink> et de ses 
	 <olink targetdocent="attaches">documents attachés</olink>.</para>
  <para lang="fr">Le pipeline d'indexation doit être configuré (ou déclaré) afin de pouvoir être utilisé. Cette configuration peut se faire à deux endroits : dans le fichier de configuration de l'application (<filename>conf/application.xconf</filename>) ou dynamiquement, par exemple dans une page XSP ou via l'API Java. La configuration du pipeline dans le <filename>application.xconf</filename> et dans une page XSP fait appel à la même structure XML.</para>
  <section lang="fr"> 
	 <title>Structure XML pour configurer un pipeline</title>
	 <para>La configuration d'un pipeline dans un <filename>application.xconf</filename> ou dans une page XSP se fait à l'aide d'une structure XML. Cette structure est formellement définie par un 
		<ulink url="../../schemas/application-xconf.xsd">schéma</ulink> qui définit un élément <sgmltag class="element">sdx:pipeline</sgmltag> qui peut contenir une ou plusieurs transformations exprimées par un élément <sgmltag class="element">sdx:transformation</sgmltag>. Le schéma constitue la référence ultime, mais nous allons ici donner un exemple complet pour bien illustrer le concept.</para>
	 <example lang="fr"> 
		<title>Déclaration d'un pipeline d'indexation</title>
		<programlisting>
  &lt;sdx:pipeline&gt;
    &lt;sdx:transformation id="step1" keep="true" type="XSLT" src="index.xsl"/&gt;
    &lt;sdx:transformation id="step2" type="com.ajlsm.sdx.pipeline.Trans" log="true" help="1"/&gt;
  &lt;/sdx:pipeline&gt;
</programlisting> 
		<para>Dans cet exemple, la première transformation est de type XSLT et la XSLT se situe dans le fichier <filename>index.xsl</filename> (dont l'emplacement exact est déterminé par l'URL de base du fichier qui contient la déclaration, par exemple le fichier <filename>application.xconf</filename>). L'attribut <sgmltag class="attribute">id</sgmltag>, obligatoire, contient l'identifiant de cette étape. L'attribut <sgmltag class="attribute">keep</sgmltag> indique que le résultat de cette transformation doit être conservé par SDX et réutilisé lors de l'affichage du document (voir la partie sur les 
		  <olink targetdocent="original">documents originaux et les documents d'usage</olink>) ; il est bien entendu optionnel.</para>
		<para>La seconde transformation est déterminée par la classe <literal>com.ajlsm.sdx.pipeline.Trans</literal>, dont la seule contrainte est qu'elle implémente l'interface <literal>fr.gouv.culture.sdx.pipeline.Transformation</literal> et, évidemment, qu'elle soit accessible à Java (donc dans le CLASSPATH) lorsque SDX tourne. Nous avons volontairement ajouté les attributs <sgmltag class="attribute">log</sgmltag> et <sgmltag class="attribute">help</sgmltag> ici pour illustrer le fait que le développeur est invité à utiliser ce mécanisme pour passer des informations à la classe, car celle-ci, lors de sa configuration, recevra l'ensemble de l'élément XML <sgmltag class="element">sdx:transformation</sgmltag> qui le déclare (y compris les attributs non pris en charge par SDX) mais également les sous-éléments.</para>
	 </example> 
  </section> 
  <section lang="fr"> 
	 <title>Cas particulier de la configuration dans une XSP</title>
	 <para>Lorsque la configuration d'un pipeline s'effectue dans une page dynamique XSP, on peut tirer parti de cet aspect pour gérer de véritables pipelines dynamiques, en particulier en passant des valeurs dynamiques pour différents 
		<olink targetdocent="parametres">paramètres</olink>. Les mécanismes habituels de l'API SDX sont utilisés pour passer ces paramètres. Voyons un exemple le plus complet possible :</para>
	 <example> 
		<title>Déclaration dynamique d'un pipeline d'indexation</title>
		<programlisting>
  &lt;xsp:logic&gt;
    String myFormat = "xml";
  &lt;/xsp:logic&gt;
  &lt;sdx:pipeline&gt;
    &lt;sdx:parameter name="type" valueParam="t"/&gt;
    &lt;sdx:parameter name="format" valueString="myFormat"/&gt;
    &lt;sdx:parameter name="pref" valueSession="myPref"/&gt;
    &lt;sdx:parameter name="categorie" value="Architecture"/&gt;
    &lt;sdx:transformation id="step1" type="XSLT" srcParam="s"/&gt;
  &lt;/sdx:pipeline&gt;
</programlisting> 
		<para>Dans cet exemple, quatre paramètres dynamiques sont passés au pipeline ; la source de la transformation XSLT est également passée de manière dynamique. Ce qu'il faut noter dans cet exemple :</para>
		<orderedlist>
		  <listitem>
			 <para>L'élément <sgmltag class="element">sdx:pipeline</sgmltag> peut avoir des sous-éléments <sgmltag class="element">sdx:parameter</sgmltag> ; ces derniers doivent obligatoirement se trouver avant les sous-éléments <sgmltag class="element">sdx:transformation</sgmltag> (voir le 
				<ulink url="../../schemas/api-sdx.xsd">schéma de l'API SDX</ulink> pour une définition plus précise) ;</para>
		  </listitem><listitem>
			 <para>Le comportement des éléments <sgmltag class="element">sdx:parameter</sgmltag> est exactement le même que dans d'autres circonstances, c'est-à-dire qu'on peut définir les paramètres en utilisant un paramètre d'URL (<sgmltag class="attribute">valueParam</sgmltag>), une variable Java préalablement déclarée et initialisée (<sgmltag class="attribute">valueString</sgmltag>), une information stockée en objet de session (<sgmltag class="attribute">valueSession</sgmltag>) ou une chaîne de caractère codée en dur (<sgmltag class="attribute">value</sgmltag>) ;</para>
		  </listitem><listitem>
			 <para>L'attribut <sgmltag class="attribute">src</sgmltag> de l'élément <sgmltag class="element">sdx:transformation</sgmltag> fait l'objet d'un traitement particulier afin de permettre de spécifier la source d'une transformation XSLT à l'aide des mécanismes habituels des paramètres dans l'API SDX. Dans l'exemple, on suppose que la source est passée par le paramètre d'URL <replaceable class="parameter">s</replaceable>, mais il aurait également pu être codé en dur, provenir d'une variable Java ou d'un objet de session.</para>
		  </listitem>
		</orderedlist>
	 </example> 
	 <para>Ce mécanisme de configuration dynamique des <emphasis>pipelines</emphasis> est très puissant. Ainsi, au moment même de l'indexation, vous avez le choix entre :</para>
	 <orderedlist>
		<listitem>
		  <para>Utiliser le <emphasis>pipeline</emphasis> par défaut déclaré dans le fichier <filename>application.xconf</filename>, en n'utilisant pas d'élément <sgmltag class="element">sdx:pipeline</sgmltag> ;</para>
		</listitem><listitem>
		  <para>Passer des paramètres dynamiques, pour contextualiser légèrement votre pipeline d'indexation ;</para>
		</listitem><listitem>
		  <para>Choisir dynamiquement la source d'une transformation XSLT lorsque le contexte exige des changements importants et où une même XSLT ne peut pas tenir compte de tous les changements possibles.</para>
		</listitem>
	 </orderedlist>
	 <para>En terminant, il est bon de rappeler que les <emphasis>pipelines</emphasis> dynamiques peuvent être utilisés à l'intérieur des éléments qui déclenchent l'indexation de documents dans SDX, soit les éléments <sgmltag class="element">sdx:uploadDocument</sgmltag> ou <sgmltag class="element">sdx:uploadDocuments</sgmltag>.</para>
  </section> 

</webpage> 
