<?xml version="1.0"?>
<!DOCTYPE webpage PUBLIC "-//Norman Walsh//DTD Website V2.1b1//EN" "../../../dtd/website.dtd" [
  <!ENTITY actions SYSTEM "actions.xml" NDATA XML>
  <!ENTITY actions_recuperation SYSTEM "actions_recuperation.xml" NDATA XML>
  <!ENTITY actions_requetes SYSTEM "actions_requetes.xml" NDATA XML>
]>
<webpage id="parametres_sdx">

  <head>
    <title lang="fr">La logique des paramètres SDX</title>
    <titleabbrev lang="fr">Paramètres SDX</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>2005-05-20</date>
      </revision>
    </revhistory>
  </head>

  <section>
    <title>Concepts clés</title>
    <para>Les actions (ou services) fournies par SDX montrent un gros besoin de paramètres. Une application SDX étant essentiellement une application serveur, on devine qu'il y a plusieurs sources possibles pour fixer ces paramètres. Reste à en définir précisément les priorités, afin qu'une page puisse s'appuyer sur cet ordre pour définir des logiques fines, bien que très économes en syntaxe. C'est ce que nous entendons éclairer dans cette section de la documentation.</para>
    <table>
      <title>Priorité des paramètres par ordre décroissant<footnote>
          <para>Le paramètre Java prime sur le paramètre SDX.</para>
        </footnote>
      </title>
      <tgroup cols="4">
        <colspec colnum="1" colname="col1" colwidth="18.68*"/>
        <colspec colnum="2" colname="col2" colwidth="1.00*"/>
        <colspec colnum="3" colname="col3" colwidth="9.84*"/>
        <colspec colnum="4" colname="col4" colwidth="9.84*"/>
        <thead>
          <row>
            <entry colname="col1">Nom</entry>
            <entry colname="col2">Propriétaire ou déclencheur</entry>
            <entry colname="col3">Mode d'acquisition</entry>
            <entry colname="col4">Syntaxe</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry colname="col1">
              <ulink url="#string">Paramètre Java</ulink>
            </entry>
            <entry colname="col2">Application</entry>
            <entry colname="col3">Calcul</entry>
            <entry colname="col4">
              <sgmltag class="attribute">*String="variable Java"</sgmltag>
            </entry>
          </row>
          <row>
            <entry colname="col1">
              <ulink url="#strings">Paramètre Java</ulink>
            </entry>
            <entry colname="col2">Application</entry>
            <entry colname="col3">Calcul</entry>
            <entry colname="col4">
              <sgmltag class="attribute">*Strings="variable[] Java"</sgmltag>
            </entry>
          </row>
          <row>
            <entry colname="col1">
              <ulink url="#sitemap">Paramètre Sitemap</ulink>
              <emphasis role="bold">SDX 2.1</emphasis>
            </entry>
            <entry colname="col2">Application</entry>
            <entry colname="col3">Sitemap</entry>
            <entry colname="col4">
              <sgmltag class="attribute">*Sitemap="nom spécifique"</sgmltag>
            </entry>
          </row>
          <row>
            <entry colname="col1">
              <ulink url="#param">Paramètre HTTP</ulink>
            </entry>
            <entry colname="col2">Utilisateur</entry>
            <entry colname="col3">Paramètre URL</entry>
            <entry colname="col4">
              <sgmltag class="attribute">*Param="paramètre http"</sgmltag>
            </entry>
          </row>
          <row>
            <entry colname="col1">
              <ulink url="#session">Paramètre session</ulink>
            </entry>
            <entry colname="col2">Utilisateur</entry>
            <entry colname="col3">Session</entry>
            <entry colname="col4">
              <sgmltag class="attribute">*Session="cle"</sgmltag>
            </entry>
          </row>
          <row>
            <entry colname="col1">
              <ulink url="#application">Paramètre simple (CHECK)</ulink>
            </entry>
            <entry colname="col2">Application</entry>
            <entry colname="col3">Statique</entry>
            <entry colname="col4">
              <sgmltag class="attribute">name="valeur"</sgmltag>
            </entry>
          </row>
          <row>
            <entry colname="col1">
              <ulink url="#sdx">Paramètre SDX</ulink>
            </entry>
            <entry colname="col2">SDX</entry>
            <entry colname="col3">SDX</entry>
            <entry colname="col4">Valeurs par défaut <emphasis>codées en dur</emphasis> dans SDX</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    <example id="exemple_01">
      <title>Priorité de définition des paramètres SDX</title>
      <para>Un petit exemple introduira bien ces différences. Le code ci-dessous n'a besoin d'aucune transformation particulière pour être visible sur un navigateur (pourvu que la Sitemap soit correctement configurée).</para>
      <programlisting>
&lt;?xml version="1.0"?&gt;
&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;html&gt;&lt;head&gt;&lt;title&gt;SDX - paramètres&lt;/title&gt;&lt;/head&gt;&lt;body&gt;
    &lt;h1&gt;Les paramètres SDX&lt;/h1&gt;

    &lt;xsp:logic&gt;
      String java=null;
      if (!"".equals(request.getParameter("java")))
        java=request.getParameter("java");
    &lt;/xsp:logic&gt;

    &lt;div&gt;
      &lt;sdx:executeSimpleQuery
        query="sdxall:1"
        querySession="cache"
        queryParam="question"
        queryString="java"/&gt;
    &lt;/div&gt;

    &lt;textarea rows="10" col="80" style="width:100%"&gt;
      &lt;sdx:executeSimpleQuery
        query="sdxall:1"
        querySession="cache"
        queryParam="question"
        queryString="java"/&gt;
    &lt;/textarea&gt;

    &lt;p&gt;Pour tester l'ordre croissant
    des priorités,
    inscrivez des valeurs différentes
    dans plusieurs champs.&lt;/p&gt;

    &lt;form method="get"&gt;
    &lt;ol&gt;
      &lt;li&gt;
        Un paramètre dans l'application @query="sdxall:1"
      &lt;/li&gt;
      &lt;li&gt;
        Une valeur en session=
        &lt;xsp:expr&gt;session.getAttribute("cache")&lt;/xsp:expr&gt;
      &lt;/li&gt;
      &lt;li&gt;
        Un paramètre d'application ?question=
        &lt;input name="question"/&gt;
      &lt;/li&gt;
      &lt;li&gt;
        Une variable String java=
        &lt;input name="java"/&gt;
      &lt;/li&gt;
      &lt;div&gt;
        &lt;input type="submit"/&gt;
      &lt;/div&gt;
    &lt;/ol&gt;
    &lt;/form&gt;

    &lt;/body&gt;&lt;/html&gt;
  &lt;/sdx:page&gt;
&lt;/xsp:page&gt;
</programlisting>
    </example>
  </section>
  <section>
    <title>Définitions</title>
    <variablelist>
      <varlistentry id="string">
        <term>Paramètre <trademark>Java</trademark> : <sgmltag class="attribute">nameString="variable_java"</sgmltag>
        </term>
        <listitem>
          <para>L'action SDX prendra son paramètre de la variable <trademark>Java</trademark> indiquée (à condition qu'elle ne soit pas nulle). Attention ! Cette variable doit être de type <literal>java.lang.String</literal>.</para>
          <example id="exemple_parametre_java_string">
            <title>Utilisation de paramètre <trademark>java</trademark> dans la construction d'une requête</title>
            <para>Le code XSP ci-dessous récupère la valeur recherchée et l'insère dans des guillemets doubles afin de forcer le moteur de recherche à travailler sur le groupe de valeurs précisemment (rechercher <literal>station inra</literal>, ne revient pas au même que de rechercher <literal>&quot;station inra&quot;</literal>).</para>
<programlisting xml:space="preserve">
&lt;?xml version="1.0"?&gt;
&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:logic&gt;
      String fulltext = '"'+request.getParameterValues("query")+'"';
      &lt;sdx:executeSimpleQuery valueString="fulltext" /&gt;
    &lt;/xsp:logic&gt;
  &lt;/sdx:page&gt;
&lt;/xsp:page&gt;
</programlisting>
          </example>
        </listitem>
      </varlistentry>
      <varlistentry id="strings">
        <term>Paramètre <trademark>Java</trademark> : <sgmltag class="attribute">nameStrings="variable_java[]"</sgmltag>
        </term>
        <listitem>
          <para>L'action SDX prendra son paramètre du tableau de la variable <trademark>Java</trademark> indiquée (à condition qu'elle ne soit pas nulle). Attention ! Cette variable doit être de type <literal>java.lang.String</literal>.</para>
          <example id="exemple_parametre_java_strings">
            <title>Utilisation de paramètre <trademark>java</trademark> dans la construction d'une requête</title>
            <para>Le code XSP ci-dessous montre comment on peut filtrer dynamiquement une liste de termes recherchés afin d'alimenter une ListQuery. Une valeur peut ainsi être rejetée.</para>
<programlisting xml:space="preserve">
&lt;?xml version="1.0"?&gt;
&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:logic&gt;
      String[] typedocParam = request.getParameterValues("typedoc");
      String[] typedocs = new String[typedocParam.length];
      for(inti=0; i &lt; typedocParam.length; i++){
        if( !typedocParam[i].equals("une_mauvaise_valeur") )
            typedocs[i] = typedocParam[i];
      }
      &lt;sdx:executeListQuery field="typedoc" valueStrings="typedocs" /&gt;
    &lt;/xsp:logic&gt;
  &lt;/sdx:page&gt;
&lt;/xsp:page&gt;
</programlisting>
          </example>
        </listitem>
      </varlistentry>
      <varlistentry id="sitemap">
        <term>Paramètre Sitemap : <sgmltag class="attribute">nameSitemap="nom spécifique"</sgmltag>
        </term>
        <listitem>
          <para>Les paramètres Sitemap ont été développés depuis le version 2.1 de SDX. L'avantage d'utiliser un tel paramètre dans une application est qu'un paramètre Sitemap peut être dynamique (calculé à partir d'une URL comme le montre l'<ulink url="#exemple_parametre_sitemap">exemple ci-dessous</ulink>) ou simplement statique (codée en dur dans la Sitemap).</para>
          <example id="exemple_parametre_sitemap">
            <title>Paramètre Sitemap dynamique (TODO : Pas clair dans un contexte XSP)</title>
            <para>Dans l'exemple suivant, on utilise la Sitemap pour retirer les paramètres nécessaires à l'exécution d'une action SDX :
                  <olink localinfo="sdx_includedocument" targetdocent="actions_recuperation"><sgmltag class="element">sdx:includeDocument</sgmltag>
              </olink>. Le but est d'afficher un document préalablement indexé par une application SDX.</para>
            <itemizedlist>
              <listitem>
                <para>Le générateur <literal>document.xsp</literal> contenant l'action <sgmltag class="element">sdx:includeDocument</sgmltag> ; </para>
              </listitem>
              <listitem>
                <para>L'URL <literal>{serveur SDX}/sdxtest/docs/F19993315A26T2.xml</literal> ; </para>
              </listitem>
              <listitem>
                <para>Le code de la Sitemap chargé de générer le contenu de l'URL : </para>
                <programlisting>
&lt;map:match pattern="*/*.xml"&gt;
  &lt;map:generate type="xsp" src="document.xsp"&gt;
    &lt;map:parameter name="base" value="{1}"/&gt;
    &lt;map:parameter name="id" value="{2}"/&gt;
  &lt;/map:generate&gt;
  &lt;map:serialize type="xml"/&gt;
&lt;/map:match&gt;
</programlisting>
              </listitem>
            </itemizedlist>
          </example>
        </listitem>
      </varlistentry>
      <varlistentry id="param">
        <term>Paramètre HTTP : <sgmltag class="attribute">nameParam="http_param"</sgmltag>
        </term>
        <listitem>
          <para>Cet attribut indique que l'action arrête d'écouter le paramètre http par défaut (<literal>?name=value</literal>), pour désormais réagir à <literal>?http_param=value</literal>.</para>
        </listitem>
      </varlistentry>
      <varlistentry id="session">
        <term>Paramètre session : <sgmltag class="attribute">nameSession="cle"</sgmltag>
        </term>
        <listitem>
          <para>La force des interfaces web est qu'elle n'exigent pas de connexion continue avec le serveur. La conséquence, c'est le manque de persistance des informations d'une transaction à une autre. On peut passer un paramètre d'URL de page en page, mais cela devient très incommode pour le développeur d'application (comme pour l'utilisateur souhaitant garder des URLs pérennes). Un moteur de servlets tels que celui sous-jacent à SDX (i.e. <trademark>Cocoon</trademark>) permet de garder une session pour chaque utilisateur connecté (i.e. une fenêtre de navigateur). Ce mécanisme est notamment employé par SDX pour conserver des informations comme l'identité de l'utilisateur ou les résultats de requêtes dans lesquels on désirera naviguer page par page.</para>
          <para>Chaque application peut souhaiter fixer des valeurs persistantes au choix de l'utilisateur, comme le nombre de résultats par page, l'inclusion ou non de documents dans les résultats de recherche ; d'autant plus que la Sitemap Cocoon permet de résoudre une ressource en fonction de ces paramètres de session (<emphasis>matcher</emphasis> de session). L'utilisateur peut ainsi choisir et conserver une XSL de présentation en ayant actionné une et une seule fois un paramètre stocké désormais dans sa session. Le développeur d'applications saura imaginer d'autres options.</para>
          <para>Lorsqu'un paramètre de type <sgmltag class="attribute">*Session="cle"</sgmltag> est ajouté à une action (par exemple
                <olink localinfo="sdx_executesimplequery" targetdocent="actions_requetes"><sgmltag class="element">sdx:executeSimpleQuery</sgmltag>
            </olink>), il indique que <emphasis>désormais</emphasis> toute valeur fournie par l'utilisateur (<ulink url="#param">paramètre http</ulink>) sera stockée dans l'objet de session <sgmltag class="attvalue">cle</sgmltag>. On a donc un comportement persistant de l'action, changeant à chaque nouvelle valeur donnée en paramètre utilisateur. (TODO : clarifier)</para>
        </listitem>
      </varlistentry>
      <varlistentry id="application">
        <term>Paramètre simple : <sgmltag class="attribute">name="valeur"</sgmltag>
        </term>
        <listitem>
          <para>Valeur fixée par le développeur d'application.</para>
        </listitem>
      </varlistentry>
      <varlistentry id="sdx">
        <term>Paramètre SDX</term>
        <listitem>
          <para>Au mieux, SDX fournit le contexte nécessaire à l'exécution des actions par l'intermédiaire de valeurs par défaut <emphasis role="italic">codées en dur</emphasis> dans SDX. Ainsi pour exécuter une recherche, il n'est pas nécessaire de préciser l'application (<sgmltag class="attribute">app</sgmltag>), SDX fournira l'identifiant de l'application courante dans <sgmltag class="attribute">app</sgmltag>.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>

</webpage>
