<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (C) 2000-2010  Ministere de la culture et de la communication (France), AJLSM
See LICENCE file
-->
<!DOCTYPE webpage PUBLIC "-//Norman Walsh//DTD Website V2.1b1//EN" "../../../dtd/website.dtd">

<webpage id="xsp_generalites"> 

  <head>
	 <title lang="fr">Les pages XSP de <trademark>Cocoon</trademark></title>
	 <titleabbrev lang="fr">Pages XSP</titleabbrev>
	 <author>
		<firstname>Martin</firstname>
		<surname>Sévigny</surname>
		<affiliation>
		  <orgname>AJLSM</orgname> 
		</affiliation>
	 </author>
	 <author>
		<firstname>Frédéric</firstname>
		<surname> Glorieux</surname>
		<affiliation>
		  <orgname>AJLSM</orgname> 
		</affiliation>
	 </author>
	 <author lang="fr">
		<firstname>Malo</firstname>
		<surname>Pichot</surname>
		<affiliation>
		  <orgname>AJLSM</orgname> 
		</affiliation>
	 </author>
	 <revhistory>
		<revision lang="fr">
		  <revnumber>1.0</revnumber> 
		  <date>2003-06-04</date> 
		</revision>
	 </revhistory>
  </head>

  <section lang="fr" id="preambule"> 
	 <title>Préambule</title>
	 <para lang="fr"> Cette page ne se substitue pas à une documentation de 
		<ulink url="http://xml.apache.org/cocoon/"><trademark>Cocoon</trademark></ulink> (même si elle fait cruellement défaut en français !) ; seuls les principes permettant de comprendre une application SDX seront abordés dans cette section. Toutefois, les termes techniques employés seront généralement liés à une URL de référence (en anglais).</para>
  </section> 
  <section id="xsp_quelques_mots"> 
	 <title>XSP en quelques mots</title>
	 <variablelist> 
		<varlistentry> 
		  <term>Tubes XML</term> 
		  <listitem>
			 <para>Une application SDX s'exécute dans le contexte de 
				<ulink url="http://xml.apache.org/cocoon/"><trademark>Cocoon</trademark></ulink>. Toutes les fonctionnalités de cet environnement y sont disponibles, en particulier, la définition d'un 
				<ulink url="http://xml.apache.org/cocoon/userdocs/concepts/sitemap.html"><filename>sitemap.xmap</filename></ulink>. Ce "plan du site" interprète les URLs demandées pour distribuer les ressources, selon un mécanisme astucieux et puissant, les 
				<ulink url="http://xml.apache.org/cocoon/userdocs/concepts/index.html#basic-mechanisms">pipelines</ulink> ("tubes" ?). Inspiré d'<ulink url="http://www.linux-france.org/prj/jargonf/P/pipe.html">Unix</ulink>, ce concept rationalise les étapes d'un processus XML : 
				<ulink url="http://xml.apache.org/cocoon/userdocs/generators/generators.html">génération</ulink> d'une source, 
				<ulink url="http://xml.apache.org/cocoon/userdocs/transformers/transformers.html">transformations</ulink> successives, pour une 
				<ulink url="http://xml.apache.org/cocoon/userdocs/serializers/serializers.html">sérialisation</ulink> finale.</para>
		  </listitem></varlistentry><varlistentry><term>Générateurs dynamiques</term><listitem>
			 <para>Les services d'un serveur SDX (recherche et restitution de documents) sont accessibles de l'extérieur (grâce à des URLs pérennes), mais l'intérêt décisif commence à l'intérieur. On peut développer des logiques applicatives complexes avec les pages serveurs de <trademark>Cocoon</trademark> (<ulink url="http://xml.apache.org/cocoon/userdocs/xsp/logicsheet.html">XSP</ulink>). Dans l'esprit des "tubes", XSP est un générateur d'événements XML. Plus classiquement, c'est un langage serveur. 
				<ulink url="http://xml.apache.org/cocoon/userdocs/generators/jsp-generator.html">JSP</ulink> ou 
				<ulink url="http://xml.apache.org/cocoon/userdocs/generators/php-generator.html">PHP</ulink> peuvent eux aussi être acceptés comme générateurs. </para>
		  </listitem></varlistentry><varlistentry><term>Syntaxe XML</term><listitem>
			 <para>Pourquoi avoir choisi ce "langage" plutôt que d'autres plus diffusés ? Parce ce qu'il s'agit d'un langage purement XML (comme 
				<ulink url="http://www.w3.org/TR/xslt">XSL</ulink>), directement inclus dans le coeur du document à générer. Les 
				<ulink url="../../schemas/xsp.xsd">instructions</ulink> sont identifiées par un 
				<ulink url="http://www.w3.org/TR/REC-xml-names/">namespace</ulink> (<literal>http://apache.org/xsp</literal>). En contexte serveur, les éléments appartenant à cet espace de noms seront transformés en code <trademark>Java</trademark> (grâce à des filtres SAX), puis compilés dynamiquement (mécanisme similaire à 
				<ulink url="http://java.sun.com/products/jsp/">JSP</ulink>).</para>
		  </listitem></varlistentry><varlistentry><term><trademark>Java</trademark></term><listitem>
			 <para>Une page XSP devient donc une classe <trademark>Java</trademark>. Ceci permet d'inclure facilement du code qui sera exécuté dans le contexte de cette classe (le fichier généré est à chercher dans le répertoire <filename class="directory">work</filename> de votre moteur de servlets). On a donc accès à un langage évolué, ainsi qu'à toutes les classes publiques disponibles dans l'environnement en cours. Une page dynamique XSP n'a donc pas besoin d'ajouter de librairie pour étendre son langage ; elle sert surtout à ouvrir <trademark>Java</trademark> à un contexte XML.</para>
			 <example id="exemple_01"> 
				<title>Récupération d'une variable <trademark>Java</trademark> dans une XSP</title>
				<para>Cette page XSP : </para>
				<programlisting> 
&lt;?xml version="1.0"?&gt;
&lt;xsp:page xmlns:xsp="http://apache.org/xsp"&gt; 
 &lt;xsp:logic&gt; java.util.Date today = new java.util.Date(); &lt;/xsp:logic&gt;
 &lt;document&gt;
  &lt;today&gt;
   &lt;xsp:attribute name="date"&gt;
    &lt;xsp:expr&gt;today&lt;/xsp:expr&gt;
   &lt;xsp:attribute&gt;
  &lt;/today&gt;
 &lt;/document&gt;
&lt;/xsp:page&gt;
		</programlisting> 
				<para>donnera (si la Sitemap n'interpose aucune autre transformation) : </para>
				<programlisting>
&lt;?xml version="1.0"?&gt;
&lt;document&gt;
 &lt;today date="2001/10/04 14:35:34"&gt;
&lt;/document&gt;</programlisting> 
			 </example></listitem></varlistentry><varlistentry><term>Page SDX</term><listitem>
			 <para>SDX fonctionne à l'intérieur d'une page XSP, avec un son propre vocabulaire XML défini par un 
				<ulink url="../../schemas/api-sdx.xsd">schéma</ulink>. Les actions SDX sont elles aussi compilées, pour ouvrir tous les services du serveur. Soit la page suivante (la plus simple) : </para>
			 <programlisting>
&lt;xsp:page xmlns:xsp="http://apache.org/xsp"&gt;
 &lt;sdx:page xmlns:sdx="http://www.culture.gouv.fr/ns/sdx/sdx"/&gt;
&lt;/xsp:page&gt;
</programlisting> 
			 <para>Elle effectue de nombreuses opérations d'initialisation, et à la requête <literal>{serveur SDX}/sdxworld/test.xsp?parametre=château+fort</literal> elle générera avant transformation : </para>
			 <programlisting>
&lt;sdx:document
 xmlns:xsp="http://apache.org/xsp"
 xmlns:sdx="http://www.culture.gouv.fr/ns/sdx/sdx" 
 xml:lang="fr-FR"
 server="http://localhost:8080/sdx"
 api-url="http://localhost:8080/sdx/sdx/api-url"
 app="fr.gouv.culture.sdx.sdxworld"
 uri="http://localhost:8080/sdx/sdxworld/test.xsp" 
 query="?parametre=valeur"
 date="Thu Oct 31 13:14:13 CET 2002"&gt;

 &lt;sdx:user anonymous="true"/&gt;

 &lt;sdx:parameters&gt;
  &lt;sdx:parameter 
   type="get" 
   name="parametre" 
   value="château fort" 
   escapedValue="ch%E2teau+fort"
  /&gt;
 &lt;/sdx:parameters&gt;

&lt;/sdx:document&gt;
</programlisting></listitem></varlistentry><varlistentry><term>Document SDX</term><listitem>
			 <para>Avant toute opération sur des bases de documents, une page SDX apporte de l'information contextuelle, parfois très utile aux transformations ultérieures (notez par exemple la liste des paramètres passés en URL, avec leurs valeurs claires ou encodées qui permettent par exemple de construire des URLs valides). Tous les éléments renvoyés par SDX sont eux aussi arrêtés par un 
				<ulink url="../../schemas/sdx-document.xsd">schéma</ulink>.</para>
		  </listitem></varlistentry></variablelist> 
  </section> 
  <section> 
	 <title>Les bibliothèques de balises</title>
	 <subtitle>Transformation logique</subtitle> 
	 <para>Ces bibliothèques de balises sont obtenues par une transformation préalable de la page XSP, avant qu'elle soit compilée. On conçoit que l'on peut ainsi factoriser et partager du code souvent utilisé, sans avoir à le recopier dans toutes les pages XSP qui en ont besoin.</para>
	 <para>Par exemple, supposons que dans une application plusieurs pages XSP aient besoin d'inclure la date présente. On voudrait que cette information s'insère à l'endroit désiré du document destination, avec par exemple un élément <sgmltag>&lt;my:date/&gt;</sgmltag>. La définition précise d'un espace de noms évite le risque de confusions lors de transformations multiples. Une page XSP pourrait avoir le code suivant :</para>
	 <programlisting>
&lt;?xml version="1.0"?&gt;
&lt;?xml-logicsheet href="logicsheet-my.xsl"?&gt;
&lt;xsp:page xmlns:xsp="http://apache.org/xsp" xmlns:my="my"&gt;
 &lt;document&gt;
  &lt;my:date/&gt;
 &lt;/document&gt;
&lt;/xsp:page&gt; </programlisting> 
	 <para>Il est fait appel ici à une transformation XSL <filename>logicsheet-my.xsl</filename> qui s'effectuera avant la compilation de la page. Cette feuille logique se conçoit comme une transformation d'identité, qui intercepte certains noms pour les remplacer. Exemple :</para>
	 <programlisting>
...
&lt;xsl:template match="my:date" xmlns:my="my"&gt;
 &lt;xsp:logic&gt; java.util.Date today = new java.util.Date(); &lt;/xsp:logic&gt;
 &lt;today&gt;
  &lt;xsp:attribute name="date"&gt;
   &lt;xsp:expr&gt;today&lt;/xsp:expr&gt;
  &lt;xsp:attribute&gt;
 &lt;/today&gt;
&lt;/xsl:template&gt;
...
</programlisting> 
	 <para>Avant compilation, la page XSP ressemblera fort à l'exemple précédent et sa sortie sera identique.</para>
  </section> 
  <section> 
	 <title>La feuille logique SDX</title>
	 <para>L'interface XSP de SDX résulte d'une telle feuille. Ce fichier est livré dans l'archive <filename>sdx*.jar</filename>, que l'on trouve dans le répertoire <filename>sdx/WEB-INF/lib</filename> de la distribution. On peut l'extraire avec un utilitaire ZIP (ou le programme <filename>jar</filename> du JDK <trademark>Java</trademark>), en la cherchant dans l'arborescence <filename>fr/gouv/culture/sdx/logicsheet/sdx.xsl</filename> ou dans les fichiers qu'elle importe, situés dans le même arborescence.</para>
	 <para><trademark>Cocoon</trademark> comporte déjà de nombreuses feuilles logiques prédéfinies dans le fichier de configuration <filename>sdx/WEB-INF/cocoon.xconf</filename> (la plupart des générateurs). Par défaut, la bibliothèque SDX est accessible par la déclaration suivante : </para>
	 <programlisting>
...
&lt;target-language name="java"&gt;
 &lt;!-- Defines the XSP Core logicsheet for the Java language --&gt;
 &lt;parameter 
  name="core-logicsheet" 
  value="resource://org/apache/cocoon/components/language/markup/xsp/java/xsp.xsl"/&gt;
 &lt;!-- The SDX logicsheet. The XSLT file is in the SDX jar. --&gt;
 &lt;builtin-logicsheet&gt;
  &lt;parameter 
    name="prefix" 
    value="sdx"
  /&gt;
  &lt;parameter 
    name="uri" 
    value="http://www.culture.gouv.fr/ns/sdx/sdx"
  /&gt;
  &lt;parameter 
    name="href" 
    value="resource://fr/gouv/culture/sdx/logicsheet/sdx.xsl"
  /&gt;
 &lt;/builtin-logicsheet&gt;
&lt;/target-language&gt;
</programlisting> 
	 <para>SDX ne vous suffit plus ? Vous pouvez l'étendre ou développer vos propres feuilles logiques.</para>
  </section> 

</webpage> 
