Les changements à l'API-XSP

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.

La source de référence sur les éléments supportés par SDX-2 est le schéma api-sdx.xsd. Afin de valider une page serveur, un schéma xsp.xsd est aussi fourni ; il est importé par api-sdx.xsd. 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 W3C 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é.

Notez dès maintenant que l'espace de noms XSP a changé. 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 : xmlns:xsp="http://apache.org/xsp" (au lieu de xmlns:xsp="http://www.apache.org/1999/XSP/Core"). 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 sitemap.xmap. Ces opérations peuvent s'effectuer sans risque par un rechercher/remplacer sur lot de fichiers.

<?xml version="1.0"?>
<!-- Ces "PI" ne sont plus utiles sous Cocoon-2
<?cocoon-process type="xsp"?>
<?cocoon-process type="xslt"?>
<?xml-stylesheet href="xsl/accueil.xsl" type="text/xsl"?>
-->
<xsp:page language="java"
    xmlns:sdx="http://www.culture.gouv.fr/ns/sdx/sdx"
    xmlns:xsp="http://apache.org/xsp">
    <sdx:page>
      ...
    </sdx:page>
</xsp:page>

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.

Les fonctions non supportées

<sdx:checkRights/>

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.

Pour la remplacer, nous proposons d'utiliser les groupes (avec <sdx:userIsMember/>) ou encore d'utiliser la nouvelle fonction <sdx:userIs/> pour vérifier l'identité précise d'un utilisateur.

<sdx:insertXMLFile/>

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 XInclude et CInclude dans Cocoon-2, nettement plus puissants. Voir la documentation de Cocoon pour en savoir plus sur leur utilisation

<sdx:showTable/>

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.

<sdx:selectSSH/>

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 sitemap.xmap.

Les fonctions dépréciées

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 ils seront éventuellement supprimés.

<sdx:index/>: Ce nom ne devrait plus être utilisé ; on lui préférera désormais le nom <sdx:terms/>.

Les fonctions et attributs modifiés

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.

<sdx:execute*Query hpp="-1"/> , <sdx:terms hpp="-1"/>: L'attribut hpp 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 hitsPerPage, afin de rentrer en cohérence avec les attributs hppParam, ou hppSession.
<sdx:execute*Query page="1" pageParam="p"/> , <sdx:terms page="1" pageParam="p"/>: Les attributs page et pageParam 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 pageNo et pParam.
<sdx:execute*Query sfParam="1" soParam="p"/>: Les attributs sfParam et soParam spécifient un champ de tri et l'ordre (ascendant ou descendant) selon lequel ordonner une liste de résultats. Ils remplacent sfParams et soParams (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é <sdx:sort field="region" order="ascendant"/> (à la manière de <xsl:sort/>).
<sdx:executeLinearQuery fieldParam="f" valueParam="v" opParam="op"/>: Les attributs fieldParam, valueParam et opParam spécifient respectivement le paramètre répétable pour les champs, valeurs et opérateurs d'une requête linéaire. Ils remplacent fieldsParam, queryParam et connParam.

TODO fifParams, fivParams, baseQuery, bqParam, baseOperator, boParam, <sdx:executeDateIntervalQuery/>, <sdx:filter/>, <sdx:uploadDocument/>

Auteurs : Martin Sévigny ( AJLSM ) ; Frédéric Glorieux ( AJLSM ) - 2002/09/25

	Home
Copyright © 2000, 2001, 2002, 2003, 2004 Ministère de la culture et de la communication, AJLSM.