<?xml version="1.0"?>
<!DOCTYPE webpage PUBLIC "-//Norman Walsh//DTD Website V2.1b1//EN" "../../../dtd/website.dtd" [
	<!ENTITY config SYSTEM "configuration.xml" NDATA XML>
]>
<webpage id="api-xsp">
	<head>
		<title>Les changements à l'API-XSP</title>
		<titleabbrev>API-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>
		<revhistory>
			<revision>
				<revnumber>1.0</revnumber>
				<date>2002/09/25</date>
			</revision>
		</revhistory>
	</head>
	<para>L'API-XSP de SDX est utilisée dans les pages serveur de Cocoon-2 afin d'appeler les services de SDX. Elle permette d'exécuter des opérations, et selon les cas, peut retourner des éléments XML (résultats de recherche, rapport d'opération ...). Ces noeuds s'intègrent à la place de l'élément SDX, dans le document généré par la page XSP. Ce principe ne change pas avec la version 2, et de façon générale l'API-SDX (SDX-2) est compatible.</para>
	<para>La source de référence sur les éléments supportés par SDX-2 est le schéma <ulink url="../../schemas/api-sdx.xsd"><filename>api-sdx.xsd</filename></ulink>. Afin de valider une page serveur, un schéma <ulink url="../../schemas/xsp.xsd"><filename>xsp.xsd</filename></ulink> est aussi fourni&#xA0;; il est importé par <ulink url="../../schemas/api-sdx.xsd"><filename>api-sdx.xsd</filename></ulink>. Cela signifie que les modifications expliquées ici seront automatiquement découvertes en validant une page serveur SDX contre son schéma. Un éditeur XML compatible avec cette norme <ulink url="http://www.w3.org/XML/Schema">W3C</ulink> peut permettre de vérifier un lot de fichiers et de s'arrêter en ouvrant un élément non supporté, ou un attribut dont le nom a changé.</para>
	<para>Notez dès maintenant que <emphasis role="bold">l'espace de noms XSP a changé</emphasis>. Pour que vos pages serveurs soient prises en compte par Cocoon-2 (ou correctement validées), il faut désormais associer cet attribut à l'élément racine&#xA0;: <sgmltag>xmlns:xsp="http://apache.org/xsp"</sgmltag> (au lieu de <sgmltag>xmlns:xsp="http://www.apache.org/1999/XSP/Core"</sgmltag>). Par ailleurs, les instructions de traitement ("Processing Instructions") ne sont plus nécessaires, les transformations XSL ou les déclarations Cocoon d'une page XSP étant désormais gérées dans le <filename>sitemap.xmap</filename>. Ces opérations peuvent s'effectuer sans risque par un rechercher/remplacer sur lot de fichiers.</para>
	<programlisting>
&lt;?xml version="1.0"?&gt;
&lt;!-- Ces "PI" ne sont plus utiles sous Cocoon-2
&lt;?cocoon-process type="xsp"?&gt;
&lt;?cocoon-process type="xslt"?&gt;
&lt;?xml-stylesheet href="xsl/accueil.xsl" type="text/xsl"?&gt;
--&gt;
&lt;xsp:page language="java"
    xmlns:sdx="http://www.culture.gouv.fr/ns/sdx/sdx"
    xmlns:xsp="http://apache.org/xsp"&gt;
    &lt;sdx:page&gt;
      ...
    &lt;/sdx:page&gt;
&lt;/xsp:page&gt;
</programlisting>
	<para>Dans ce document, seront surtout soulignés les points d'incompatibilité, la documentation de référence de l'API-SDX définissant l'ensemble des fonctionnalités permises.</para>
	<section>
		<title>Les fonctions non supportées</title>
		<variablelist>
			<varlistentry>
				<term>
					<sgmltag>&lt;sdx:checkRights/&gt;</sgmltag>
				</term>
				<listitem>
					<para>Cette fonction permettait de vérifier les droits de l'utilisateur en cours en fonction d'une liste de droits prédéfinis par SDX. Il s'agissait du seul aspect de SDX qui n'était pas générique et il n'était pas conseillé d'utiliser ces droits spécifiques. C'est pourquoi cette fonction a disparu avec SDX-2.</para>
					<para>Pour la remplacer, nous proposons d'utiliser les groupes (avec <sgmltag>&lt;sdx:userIsMember/&gt;</sgmltag>) ou encore d'utiliser la nouvelle fonction <sgmltag>&lt;sdx:userIs/&gt;</sgmltag> pour vérifier l'identité précise d'un utilisateur.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>
					<sgmltag>&lt;sdx:insertXMLFile/&gt;</sgmltag>
				</term>
				<listitem>
					<para>Cette fonction permettait d'include des fichiers XML dans le contenu du document XML produit par la XSP. Elle n'est plus utile avec l'ajout des transformateurs <emphasis role="bold">XInclude</emphasis> et <emphasis role="bold">CInclude</emphasis> dans Cocoon-2, nettement plus puissants. Voir la <ulink url="http://xml.apache.org/cocoon/userdocs/transformers/xinclude-transformer.html">documentation</ulink> de Cocoon pour en savoir plus sur leur utilisation</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>
					<sgmltag>&lt;sdx:showTable/&gt;</sgmltag>
				</term>
				<listitem>
					<para>Le support des tables associées a été abandonné dans SDX-2. La puissance de l'outil de recherche, la souplesse de configuration, et la possibilité d'avoir des processus d'indexation très sophistiqués rendent ces tables associées moins utiles.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>
					<sgmltag>&lt;sdx:selectSSH/&gt;</sgmltag>
				</term>
				<listitem>
					<para>Cette fonction permettait de spécifier dynamiquement la feuille de style XSLT à utiliser pour une page XSP, par exemple en fonction d'un paramètre de la requête URL. Telle qu'implantée, cette fonction est incompatible avec la nouvelle architecture Cocoon-2, et c'est pourquoi elle a été abandonnée. Le même résultat peut être obtenu en utilisant des paramètres dans <filename>sitemap.xmap</filename>.</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</section>
	<section>
		<title>Les fonctions dépréciées</title>
		<para>Dans le but d'uniformiser le vocabulaire SDX mais aussi afin de rendre ce vocabulaire plus représentatif, quelques synonymes de fonctions ont été ajoutés, et les anciens noms sont maintenant dépréciés, même s'ils fonctionnent toujours. Nous déconseillons donc fortement leur utilisation&#xA0; ils seront éventuellement supprimés.</para>
		<variablelist>
			<varlistentry>
				<term>
					<sgmltag>&lt;sdx:index/&gt;</sgmltag>
				</term>
				<listitem>
					<para>Ce nom ne devrait plus être utilisé&#xA0;; on lui préférera désormais le nom <sgmltag>&lt;sdx:terms/&gt;</sgmltag>.</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</section>
	<section>
		<title>Les fonctions et attributs modifiés</title>
		<para>Certaines fonctions voient leur comportement modifié, c'est-à-dire que si l'on utilise cette fonction de la même manière qu'avec SDX-1, le comportement ne sera pas nécessairement identique. Ces variations sont en général dues à des noms de paramètres ayant changé, la plupart du temps pour uniformiser le vocabulaire et le rendre plus représentatif.</para>
		<variablelist>
			<varlistentry>
				<term>
					<sgmltag>&lt;sdx:execute*Query hpp="-1"/&gt;</sgmltag>
				</term>
				<term>
					<sgmltag>&lt;sdx:terms hpp="-1"/&gt;</sgmltag>
				</term>
				<listitem>
					<para>L'attribut <sgmltag>hpp</sgmltag> spécifie le nombre d'items par page d'une liste de résultats (renvoyés par une recherche ou une liste de termes). Il remplace l'ancien attribut <sgmltag>hitsPerPage</sgmltag>, afin de rentrer en cohérence avec les attributs <sgmltag>hppParam</sgmltag>, ou <sgmltag>hppSession</sgmltag>.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>
					<sgmltag>&lt;sdx:execute*Query page="1" pageParam="p"/&gt;</sgmltag>
				</term>
				<term>
					<sgmltag>&lt;sdx:terms page="1" pageParam="p"/&gt;</sgmltag>
				</term>
				<listitem>
					<para>Les attributs <sgmltag>page</sgmltag> et <sgmltag>pageParam</sgmltag> spécifient le numéro d'une page à afficher dans une liste de résultats (soit par une valeur statique, soit par un paramètre HTTP). Ces noms remplacent <sgmltag>pageNo</sgmltag> et <sgmltag>pParam</sgmltag>.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>
					<sgmltag>&lt;sdx:execute*Query sfParam="1" soParam="p"/&gt;</sgmltag>
				</term>
				<listitem>
					<para>Les  attributs <sgmltag>sfParam</sgmltag> et <sgmltag>soParam</sgmltag> spécifient un champ de tri et l'ordre (ascendant ou descendant) selon lequel ordonner une liste de résultats. Ils remplacent <sgmltag>sfParams</sgmltag> et <sgmltag>soParams</sgmltag> (toute la différence tient à un "s"). Afin d'alléger les URLs, on préfèrera sans doute employer l'élément répétable et imbriqué <sgmltag>&lt;sdx:sort field="region" order="ascendant"/&gt;</sgmltag> (à la manière de <sgmltag>&lt;xsl:sort/&gt;</sgmltag>).</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>
					<sgmltag>&lt;sdx:executeLinearQuery fieldParam="f" valueParam="v" opParam="op"/&gt;</sgmltag>
				</term>
				<listitem>
					<para>Les  attributs <sgmltag>fieldParam</sgmltag>, <sgmltag>valueParam</sgmltag> et <sgmltag>opParam</sgmltag> spécifient respectivement le paramètre répétable pour les champs, valeurs et opérateurs d'une requête linéaire. Ils remplacent <sgmltag>fieldsParam</sgmltag>, <sgmltag>queryParam</sgmltag> et <sgmltag>connParam</sgmltag>.</para>
				</listitem>
			</varlistentry>
		</variablelist>
		<para>TODO <sgmltag>fifParams</sgmltag>,
<sgmltag>fivParams</sgmltag>,
<sgmltag>baseQuery</sgmltag>,
<sgmltag>bqParam</sgmltag>,
<sgmltag>baseOperator</sgmltag>, 
<sgmltag>boParam</sgmltag>, <sgmltag>&lt;sdx:executeDateIntervalQuery/&gt;</sgmltag>, <sgmltag>&lt;sdx:filter/&gt;</sgmltag>, <sgmltag>&lt;sdx:uploadDocument/&gt;</sgmltag>
		</para>
	</section>
</webpage>
