Télécharger
    Installer
    Présentation
    Configuration
    Indexation
    Recherche
    OAI
    Javadoc
    Référence API-XSP
    Migration
       Configuration
        Sitemap
       API-XSP
      +API-URL <-
    Schemas
    Performances


SDX

Les changements à l'API-URL

L'API-URL de SDX est utilisée pour appeler des services directement depuis un navigateur ou depuis tout environnement capable de récupérer du contenu depuis une URL. C'est le cas, notamment, d'un processeur XSLT grâce à la fonction document(), ce qui peut être utile pour compléter la présentation d'un document avec des informations annexes gérées par SDX.

Pour une migration facile, les fonctions SDX-1 conservées réagissent aux mêmes paramètres, mais ces noms et paramètres sont dépréciés..

L'accès URL vise à être compatible avec l'API-XSP, en particulier, en utilisant les mêmes paramètres URL par défaut, en utilisant les mêmes noms de fonction. Ce document souligne essentiellement, les fonctions non supportées, les nouvelles normes pour les fonctions SDX-1. La documentation de référence de l'API-SDX définit toutes les fonctionnalités, en particulier celles ajoutées.

L'URL de base est fournie dans chaque document SDX par un attribut (api-url) dans l'élément racine (<sdx:document xml:lang="fr-FR" server="{$server-url}" api-url="{$server-url}/sdx/api-url/" ... />).

Les fonctions non supportées

L'utilisation de l'une ou l'autre de ces fonctions génèrera une erreur car elles ne sont plus supportées par SDX-2.

user

Cette fonction est supprimée car elle peut causer des problèmes de sécurité et son utilité est plutôt restreinte.

tabledata

Les tables associées ne sont plus supportées en SDX-2 et cette fonction n'est donc plus utile.

html2xhtml

L'environnement Cocoon-2 permet de transformer un document HTML en format XHTML très simplement, à l'aide d'un pipeline dont la source est le document HTML et qui sérialisé avec le sérialiseur par défaut. Cette fonction spécifique à SDX n'est donc plus utile, le sitemap permet d'aller plus loin.

Les fonctions modifiées

Les modifications portent avant tout sur les paramètres, afin de les adapter à la nouvelle architecture de SDX-2 (plusieurs bases de documents par application, plusieurs entrepôts par bases de documents). Par ailleurs, l'unification du vocabulaire a déprécié certains noms.

executeSimpleQuery, executeFieldQuery, executeLinearQuery, (simplesearch) , (fieldsearch) , (linearsearch)

Les anciens noms de requêtes sont supportés avec les anciens paramètres. Attention, ils sont dépréciés. Il est conseillé d'employer les noms de l'API-SDX (l'API-XSP).

app, appbypath, (db)

L'appel à l'API-URL se voulant générique et hors contexte, il faut au moins spécifier l'application concernée par la fonction. Le reste (base de documents, entrepôt) reçoit une valeur par défaut, ce qui est le cas général d'une application SDX-1 (avec une seule base cherchable par application). Le paramètre URL ?app=fr.gouv.culture.sdx.sdxworld permet d'accéder à l'application sdxworld. Notez que le paramètre réagit à un identifiant d'application qui se veut "unique au monde" (selon le même format qu'une classe java, une sorte d'URL renversée). Ce code est un identifiant spécifié dans application.xconf. Cette convention permet à des applications sur différents serveurs de communiquer sans se confondre. Par commodité le paramètre ?appbypath= est supporté, il réagit au nom du répertoire sous le serveur SDX qui porte l'application (l'ancien "code de la base de documents"). Le paramètre URL ?db=code est déprécié, il ne fonctionne qu'avec les anciennes servlets SDX-1.

query, q, field, f, value, v, op, (o)

La formulation d'une requête de recherche peut se faire selon de nombreux types (simple, champ, linéaire ...), toutefois les paramètres nécessaires partagent une même logique. Le paramètre query est réservé uniquement à la recherche libre, en effet, la syntaxe permet par exemple des recherches sur un champ executeSimpleQuery?query=sdxall:1. La différence avec SDX-1 ne se situe pas dans le nom du paramètre, la forme abrégée ?q= fonctionne aussi, par contre, il n'est jamais utilisé en doublet avec un champ (?f=). La requête executeFieldQuery?app=fr.gouv.culture.sdx.sdxworld&field=sdxall&value=1 est identique à la précédente, notez que field accepte la forme abrégée ?f=, et value correspond à ?v=. Pour une requête linéaire, on peut procéder ainsi executeLinearQuery?app=fr.gouv.culture.sdx.sdxworld &f=sdxall&v=1&op=and&f=contenu&v=a*&op=and (ce qui donnera sensiblement les mêmes résultats que les requêtes précédentes, puisqu'il y a toujours un champ sdxall égal à 1, et souvent un mot commençant par a, "a*", dans un champ plein texte). Vous aurez remarqué que la forme ?o= a été abandonnée, au profit de ?op=. Toutefois, rappelons le, les requêtes de recherche conservées avec les anciens noms SDX-1 réagissent aux anciens paramètres.

qid, hpp, page, p, (h) , (n)

Les résultats de requête et les listes de termes demandent plusieurs informations pour être navigables page à page. D'abord, ces résultats doivent être identifiés pour être rappelés, c'est le rôle du paramètre ?qid=q5, valeur fournie par l'attribut id d'un élément <sdx:results/> ou <sdx:terms/>, (même fonction que l'ancien ?n= ). On peut vouloir fixer le nombre de résultats par page (?hpp=100), afin de modifier la valeur par défaut qui est de 20 (même fonction que l'ancien ?h=). Enfin, pour accéder à une page précise, le paramètre canonique est ?page=10, toutefois il existe aussi une forme abrégée identique à l'ancien paramètre (?p=10).

Conclusion

En résumé, une migration rapide n'oblige pas à relire toutes les XSL qui appelerait l'ancienne API-URL. Toutefois, il est conseillé d'en repenser l'usage. Elle sera conservée comme une commodité générique, mais un développeur d'application aura tout intérêt à développer ses propres "servlets", afin d'économiser le nombre de paramètres à lui passer (pour spécifier l'application, la base...). Selon l'architecture Cocoon-2, il ne s'agit en fait que d'une page XSP, passant par la même transformation logique (la "logicsheet" sdx.xsl), et sérialisée en XML (pour être lisible depuis une XSL). Voyez par vous même {$server}/sdx/sitemap.xmap, {$server}/sdx/api-url/*.xsp, {$server}/sdx/api-url/api-url.xsl.



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