<!doctype linuxdoc system>

<!-- Document traduit avec l'aide d'Emacs et du mode psgml. L'indentation
     utilisée a été spécifiée par (setq sgml-indent-step 1).NdT.
  -->

 <article>
   <title>Java CGI HOWTO
   <author>David H. Silber <tt><htmlurl url="mailto:dhs@orbits.com"
       name="dhs@orbits.com"></tt>. 
   <date>v0.4, 18 Novembre 1996.
   <abstract>
    Ce document vous explique comment convaincre votre serveur WWW
    d'utiliser des programmes de CGI écrits en Java, et montre l'emploi de
    Java dans l'écriture de programmes de CGI. Bien que les HOWTO se
    restreignent en principe au système Linux, celui-ci est indépendant de
    la version d'Unix utilisée. <em>Traduction : <htmlurl
      url="mailto://xavier@oreilly.com" name="Xavier Cazin">, le 27
     novembre 1997</em>.
   </abstract>
      
  <toc>
  
  <sect>Introduction
   <p>
    Par construction du language, les variables d'environnement du système
    ne sont pas facilement accessibles au programmeur Java. Par ailleurs,
    le JDK (Java Development Kit) rend impossible l'invocation directe d'un
    programme, ce qui ne facilite pas le traitement standard par CGI des
    formulaires HTML. On peut contourner ces limitations de plusieurs
    façons. Vous saurez comment j'ai implémenté l'une d'elles en
    poursuivant votre lecture.
    
   <sect1>Pré-requis
    <p>
     Je considère que vous êtes familiarisé avec les principes qui
     sous-tendent HTML et CGI, et que vous possédez un minimum de
     connaissances de votre serveur HTTP. La programmation Java ne devra
     pas non plus vous être étrangère, à défaut de quoi ce qui va suivre ne
     vous sera pas très parlant.

   <sect1>Ce document
    <p>
     <htmlurl url="http://www.orbits.com/software/Java&lowbar;CGI.html"
      name="http://www.orbits.com/software/Java&lowbar;CGI.html"> est
      l'adresse où vous êtes sûr de trouver la dernière version de ce
      document.

   <sect1>Le package lui-même
    <p>
     L'archive
     <htmlurl url="ftp://ftp.orbits.com/pub/software/java&lowbar;cgi-0.4.tgz"
      name="ftp://ftp.orbits.com/pub/software/java&lowbar;cgi-0.4.tgz">
     contient la dernière version du package décrit ici. Vous y trouverez
     également le source SGML de ce document (en anglais bien sûr).

     La distribution du package suit les recommandations de la LGPL (GNU
     Library General Public License). Ce document peut être distribué selon
     les termes gouvernant le copyright des Linux HOWTO.

     Merci de bien vouloir mentionner le document
     <htmlurl url="http://www.orbits.com/software/Java&lowbar;CGI.html"
      name="http://www.orbits.com/software/Java&lowbar;CGI.html"> si vous
     utilisez ce logiciel. Vous permettrez ainsi à d'autres d'accéder aux
     classes Java CGI.

   <sect1>Publicité gratuite
    <p>
     Ce document a été mis au point avec la bienveillance de <bf>Stellar
      Orbits Technology Services</bf>. Si vous voulez savoir ce que nous
     faisons, allez voir à <htmlurl url="http://www.orbits.com/"
      name="http://www.orbits.com/">.


  <sect>Configuration de votre serveur (avec explications)
    <label id="install-long">
   <p>
    Cette section vous conduira à travers l'installation de mon package
    <em>Java CGI</em>, et sera agrémentée d'explications généreuses qui
    vous permettront de mesurer les conséquences de vos actes. Si vous
    souhaitez simplement installer les programmes, sans vous soucier du
    pourquoi et du comment, sautez directement à la section 
    <ref id="install-short"
     name="Configuration du serveur (version courte)">.

   <sect1>Contraintes logicielles et matérielles
    <p>
     Ce logiciel devrait fonctionner sur n'importe quel système à la Unix
     sur lequel se trouvent au moins installés le JDK et un serveur
     Web. J'utilise pour ma part un <em>Linux Debian</em> sur lequel tourne
     le démon HTTP <em>apache</em>. Si cela ne fonctionne pas sur votre
     installation, n'hésitez pas à me contacter à
     <tt><htmlurl url="mailto:dhs@orbits.com" name="dhs@orbits.com"></tt>.

     Malheureusement, l'interpréteur Java n'est pas particulièrement
     économe en mémoire ; si vous devez utiliser souvent des programmes de
     CGI en Java, quelques mégaoctets de RAM supplémentaires ne seront pas
     de trop.

   <sect1>Java CGI
    <p>
     Le logiciel que j'ai écrit s'appelle <em>Java CGI</em> (Note: au
      cas où vous ne l'auriez pas encore remarqué (NdT)). Vous
     pouvez le récupérer par ftp anonyme à l'adresse <htmlurl
      url="ftp://www.orbits.com/pub/software/java&lowbar;cgi-0.4.tgz"
      name="ftp://www.orbits.com/pub/software/java&lowbar;cgi-0.4.tgz">.
     (Le numéro de version peut avoir changé.)

   <sect1>Déploiement des sources
    <p>
     Choisissez un répertoire où vous pourrez tranquillement déployer
     l'archive du package. Je suggère généralement <tt>/usr/local/src</tt>.
     Désarchivez ensuite à l'aide de la commande (Note : les
      <sq>lignuxeurs</sq> préfèreront sans doute le plus élégant <tt>tar
       xzvf java&lowbar;cgi-0.4.tgz</tt> (NdT).) : <verb>
      gzip -dc java&lowbar;cgi-0.4.tgz | tar -xvf - </verb>
     Cela aura pour effet de créer un répertoire de nom
     <tt>java&lowbar;cgi-0.4</tt>. Vous y trouverez les fichiers auxquels
     nous feront référence dans la suite. (Si le numéro de version a
     changé, suivez les instructions qui s'y trouvent à partir de
     maintenant).

   <sect1>Chemins locaux
     <label id="make-programs">
    <p>
     Vous allez devoir décider de l'endroit où vous souhaitez que les
     programmes Java CGI résident. La plupart du temps, vous aurez intérêt
     à les placer dans un répertoire parallèle au répertoire
     <tt>cgi-bin</tt>. La configuration de mon serveur <em>apache</em>
     indiquait <tt>/var/web/cgi-bin</tt> comme répertoire <tt>cgi-bin</tt>
     par défaut. J'ai donc placé mes programmes Java CGI dans le répertoire
     <tt>/var/web/javacgi</tt>. Il n'est pas conseillé de placer ces
     programmes dans l'un des répertoires référencés par
     <tt>CLASSPATH</tt>. &Eacute;ditez le Makefile pour refléter la
     configuration de votre système. En tant qu'utilisateur root, lancez
     <tt>make install</tt>. Cela aura pour effet de compiler vos programmes
     Java, modifier le script <tt>java.cgi</tt> pour qu'il s'adapte à votre
     système, et installer les programmes au bon endroit. Si vous souhaitez
     également disposer d'une version HTML de ce document, et d'un document
     test en HTML, lancez plutôt <tt>make all</tt>.

   <sect1>Test de votre installation
     <label id="install-test">
    <p>
     Les documents <tt>javacgitest.html</tt>, <tt>javaemailtest.html</tt>
     et <tt>javahtmltest.html</tt> devraient maintenant être installés. Si
     vous avez choisi <tt>make all</tt>, ils se trouveront dans le
     répertoire spécifié par la variable WEBDIR du <tt>Makefile</tt>. Dans
     le cas contraire, vous pouvez lancer <tt>make test</tt> pour les créer
     à partir de <tt>javacgitest.html-dist</tt>,
     <tt>javaemailtest.html-dist</tt> et <tt>javahtmltest.html-dist</tt>.
    <p>
     Après vous être assuré que votre installation s'était déroulée
     correctement, vous pouvez supprimer les fichiers
     <tt>CGI&lowbar;Test.class</tt>, <tt>Email&lowbar;Test.class</tt> et
     <tt>HTML&lowbar;Test.class</tt> de votre répertoire JAVACGI, ainsi que
     <tt>javacgitest.html</tt>, <tt>javaemailtest.html</tt> et
     <tt>javahtmltest.html</tt> de votre répertoire WEBDIR. Ils montrent
     les informations utilisateurs auxquelles le serveur est normalement
     seul à avoir accès.

  <sect>Configuration du serveur (version courte)
    <label id="install-short">
   <p>
    <itemize>
     <item>
      Récupérez le package <em>Java CGI</em> à partir de
      <htmlurl url="ftp://www.orbits.com/pub/software/java&lowbar;cgi-0.4.tgz"
       name="ftp://www.orbits.com/pub/software/java&lowbar;cgi-0.4.tgz">.
      (Le numéro de version peut avoir changé.)
     </item>
     <item>
      Déployez la distribution à l'aide de la commande<verb>
       gzip -dc java&lowbar;cgi-0.4.tgz | tar -xvf -</verb>
      (Si le numéro de version de la distribution a changé, utilisez les
       instructions qui s'y trouvent à partir de maintenant.)
     </item>
     <item>
      &Eacute;ditez le <tt>Makefile</tt> que vous trouverez dans le nouveau
      répertoire <tt>java&lowbar;cgi-0.4</tt> pour qu'il reflète la
      configuration de votre système.
     </item>
     <item>
      En tant que root, lancez <tt>make install</tt>. Cela aura pour effet
      de compiler les programmes Java, prendre en compte les informations
      propres à votre système, et installer les divers fichiers. 
      <p> 
       Si vous souhaitez disposer d'une version HTML de ce document, ainsi
       que d'un document test en HTML, lancez plutôt <tt>make all</tt>.
     </item>
     <item>
      Vous devriez maintenant être paré.
     </item>
    </itemize>

  <sect>Exécution d'un programme Java CGI
   <p>

   <sect1>Difficultés d'exécution de programmes Java avec le modèle CGI
    <p>
     L'exécution d'un programme Java depuis un serveur Web pose deux types
     de problèmes majeurs :
    <sect2>Les programmes Java ne s'exécutent pas comme des binaires ordinaires
     <p>
      Il faut lancer l'interpréteur Java et fournir la classe principale
      (le programme à exécuter) sur la ligne de commande. Les formulaires
      HTML ne permettent pas d'envoyer directement une ligne de commande au
      serveur Web.
    <sect2>Java n'accède pas <em>a priori</em> aux variables d'environnement
     <p>
      Toutes les variables d'environnement requises par le programme Java
      doivent lui être passées explicitement. Il n'existe pas de méthode
      similaire à la fonction <tt>getenv()</tt> de <bf>C</bf> .

   <sect1>Solutions proposées
    <p>
     Pour contourner ces obstacles, j'ai écrit une script shell de CGI, qui
     fournit les informations nécessaires à l'interpréteur Java.
    <sect2>Le script java.cgi
     <p>
      Ce script de shell se charge de l'interaction entre le démon HTTP et
      le programme Java CGI que vous souhaitez utiliser. Il extrait le nom
      du programme que vous souhaitez lancer à partir des données fournies
      par le serveur. Il récupère ensuite toutes les valeurs
      d'environnement dans un fichier temporaire. Enfin, il lance
      l'interpréteur Java en lui passant le nom du fichier contenant les
      informations d'environnement, ainsi que le nom du programme à
      exécuter.
     <p>
      Le script <tt>java.cgi</tt> a été configuré et installé selon les
      procédure décrites à la section
      <ref id="make-programs" name="Decide On Your Local Path Policies">.
    <sect2>Invocation de java.cgi depuis un formulaire HTML
     <p>
      Mes formulaires qui utilisent les programmes Java CGI spécifient
      l'action à effectuer de la façon suivante :<verb>
 <form action="/cgi-bin/java.cgi/CGI&lowbar;Test" method="POST"></verb> où
      <tt>/cgi-bin/</tt> est votre répertoire local d'exécutables CGI,
      <tt>java.cgi</tt> est l'interface permettant de lancer les programmes
      Java, et <tt>CGI&lowbar;Test</tt> est un exemple de programme Java à
      exécuter.

  <sect>Utilisation des classes Java CGI
   <p>
    Trois classes principales sont pour l'instant supportées :
    <ref id="cgi-class" name=CGI>,
    <ref id="email-class" name=Email> et
    <ref id="html-class" name=HTML>. Je pense y ajouter des classes
    capables de gérer des entrées et des sorties formatées en MIME 
    (respectivement MIMEin &amp; MIMEout).
   <p>
    Quelques classes de test et de support sont également disponibles :
    <ref id="cgi-test-class" name="CGI&lowbar;Test">,
    <ref id="email-test-class" name="Email&lowbar;Test"> et
    <ref id="email-test-class" name="HTML&lowbar;Test"> doivent permettre
    de tester votre installation. Elles peuvent aussi servir de point de
    départ à vos propres programmes Java basés sur cette bibliothèque de
    classes. La classe <ref id="text-class" name=Text> est une superclasse
    des classes <tt>Email</tt> et <tt>HTML</tt>.

   <sect1>CGI<label id="cgi-class">
    <p>
    <sect2>Syntaxe
     <p>
      <tt>public class CGI</tt>
    <sect2>Description
     <p>
      La classe CGI détient les <sq>informations SGI</sq> : les valeurs
      d'environnement initialisées par le serveur Web ainsi que le nom et
      la valeur issus du formulaire quand l'action <bf>submit</bf> est
      sélectionnée. Toutes les informations sont stockées dans un objet de
      classe <tt>Properties</tt>.
     <p>
      Cette classe se trouve dans le package <sq>Orbits.net</sq>.
    <sect2>Liste des membres
     <p>
      <code>
       CGI()         //  Constructeur.
       getNames()    //  Recupere la liste de noms.
       getValue()    //  Recupere la valeur a partir du nom.
      </code>
    <sect2>Voir aussi
     <p>
      <tt>CGI&lowbar;Test</tt>.
    <sect2>CGI()
     <p>
      <descrip>
       <tag/Finalité/Construit un objet contenant les données CGI disponibles.
       <tag/Syntaxe/<tt>public CGI()</tt>
       <tag/Description/Lorsqu'un objet CGI est construit, toutes les
        informations CGI disponibles sont récupérées et stockées dans le
        nouvel objet.
      </descrip>
    <sect2>getNames()
     <p>
      <descrip>
       <tag/Finalité/Dresse la liste des noms définis par le formulaire.
       <tag/Syntaxe/<tt>public Enumeration getNames ()</tt>
       <tag/Description/ Fournit la liste complète des noms pour lesquels
       des valeurs correspondantes ont été définies.
       <tag/Retourne/Une <tt>Enumeration</tt> de tous les noms définis.
      </descrip>
    <sect2>getValue()
     <p>
      <descrip>
       <tag/Finalité/Récupère la <bf>valeur</bf> associée au <bf>nom</bf>
        spécifié.
       <tag/Syntaxe/<tt>public String getValue ( String nom )</tt>
       <tag/Description/Cette méthode fournit la correspondance entre les
        <tt>noms</tt> et les <tt>valeurs</tt> envoyées depuis un formulaire
        HTML.
       <tag/Paramètre/
        <descrip>
         <tag/nom/La clé par laquelle les valeurs sont choisies.
        </descrip>
       <tag/Retourne/Une <tt>String</tt> contenant la valeur.
      </descrip>

   <sect1>CGI&lowbar;Test<label id="cgi-test-class">
    <p>
     Cette classe fournit à la fois un exemple d'utilisation de la classe
     CGI, et un programme de test, qu'on pourra utiliser pour confirmer que
     le package <em>Java CGI</em> fonctionne correctement.
    <sect2>Liste des membres
     <p>
      <code>
       main()      //   main() du programme
      </code>
    <sect2>Voir aussi
     <p>
      <tt>CGI</tt>.
    <sect2>main()
     <p>
      <descrip>
       <tag/Finalité/ Fournit une méthode <tt>main()</tt>.
       <tag/Syntaxe/ <tt>public static void main( String argv[] )</tt>
       <tag/Description/ Il s'agit du point d'entrée d'un programme CGI qui
       ne fait rien à part retourner la liste des couples nom/valeur.
       <tag>Paramètre
        <descrip>
         <tag/argv[]/ Arguments passés au programme par le script
          <tt>java.cgi</tt>.
          Non utilisé pour l'instant.
        </descrip>
      </descrip>

   <sect1>Email<label id="email-class">
    <p>
    <sect2>Syntaxe
     <p>
      <tt>public class Email extends Text</tt>
    <sect2>Description
     <p>
      Les messages sont construits au moyen des méthodes <tt>add*()</tt> de
      la classe <tt>Text</tt> et les méthodes spécifiques au courrier
      électronique fournies par cette classe. Une fois composé, le message
      est envoyé vers sa destination finale.
     <p>Cette classe se trouve dans le package <sq>Orbits.net</sq>.
    <sect2>Liste des membres
     <p>
      <code>
       Email()      //  Constructeur
       send()       //  Envoie le message e-mail
       sendTo()     //  Ajoute une destination au message
       subject()    //  Initialise le champ Subject: du message
      </code>
    <sect2>Voir aussi
     <p>
      <tt>Email&lowbar;Test, Text</tt>.
    <sect2>Email()
     <p>
      <descrip>
       <tag/Finalité/ Construit un objet qui contiendra un message
        électronique.
       <tag/Syntaxe/ <tt>public Email()</tt>
       <tag/Description/ Crée un message vide qui sera rempli par les
        méthodes Email.
       <tag/Voir aussi/ <tt>Text</tt>.
      </descrip>
    <sect2>send()
     <p>
      <descrip>
       <tag/Finalité/ Envoie le message e-mail.
       <tag/Syntaxe/ <tt>public void send ()</tt>
       <tag/Description/ Formatage et envoi du message. Si aucune adresse
       de destination n'a été précisée, ne fait rien.
      </descrip>
    <sect2>sendTo()
     <p>
      <descrip>
       <tag/Finalité/ Ajoute une destination pour ce message.
       <tag/Syntaxe/ <tt>public String sendTo ( String adresse )</tt>
       <tag/Description/ Ajoute <tt>adresse</tt> à la liste des
        destinations pour cette méthode. Il n'existe pas de limite <em>a
         priori</em> pour le nombre de destinations d'un message e-mail. Je
        suis sûr qu'avec une liste assez grande, on peut dépasser la taille
        acceptable pour le <em>Mail Transport Agent</em>, voire la mémoire
        disponible sur votre système.
       <tag/Paramètre/
        <descrip>
         <tag/adresse/ Une destination à laquelle envoyer ce message.
        </descrip>
      </descrip>
    <sect2>subject()
     <p>
      <descrip>
       <tag/Finalité/ Initialise le sujet du message.
       <tag/Syntaxe/ <tt>public void subject ( String sujet )</tt>
       <tag/Description/ Cette méthode remplit le champ 
        <tt>Subject:</tt> du message. Si elle est appelée plusieurs fois,
       le sujet utilisé sera le dernier demandé.
       <tag/Paramètre/
        <descrip>
         <tag/sujet/ Le texte du champ <tt>Subject:</tt> du message.
        </descrip>
      </descrip>

   <sect1>Email&lowbar;Test<label id="email-test-class">
    <p>
     Cette classe fournit à la fois un exemple d'utilisation de la classe
     <tt>Email</tt> et un programme de test qu'on pourra utiliser pour
     s'assurer que le package <em>Java CGI</em> fonctionne correctement.
    <sect2>Liste des membres
     <p>
      <code>
       main()      //  main() du programme
      </code>
    <sect2>Voir aussi
     <p>
      <tt>Email</tt>.
    <sect2>main()
     <p>
      <descrip>
       <tag/Finalité/ Fournit une méthode <tt>main()</tt>.
       <tag/Syntaxe/ <tt>public static void main( String argv[] )</tt>
       <tag/Description/ Il s'agit du point d'entrée d'un programme CGI qui
       retourne une liste des couples nom/valeur disponibles. Cette liste
        sera également envoyée à l'adresse spécifiée dans la variable
       <tt>Email</tt>. 
       <tag>Paramètre 
        <descrip>
         <tag/argv[]/ Arguments passés au programme par le script
          <tt>java.cgi</tt>. Non utilisé pour l'instant.
        </descrip>
      </descrip>

   <sect1>HTML<label id="html-class">
    <p>
    <sect2>Syntaxe
     <p>
      <tt>public class HTML extends Text</tt>
    <sect2>Description
     <p>
      Les messages sont créés à l'aide des méthodes <tt>add*()</tt> de la
      classe <tt>Text</tt> et des méthodes spécifique au HTML ajoutées par
      cette classe. Une fois terminé, le message est envoyé.
     <p>
      Aucun test n'est effectué pour l'instant pour s'asurer que les
      méthodes de construction de liste sont utilisées dans le bon
      ordre. C'est donc au programmeur de faire attention à ne pas violer
      la syntaxe HTML.
     <p>
      Cette  classe se trouve dans le package <sq>Orbits.net</sq>.
    <sect2>Liste des membres
     <p>
      <code>
       HTML()                  //  Constructeur.
       author()                //  Initialise le nom de l'auteur du document.
       definitionList()        //  Cree une liste de definitions.
       definitionListTerm()    //  Ajoute un terme a la liste de definitions.
       endList()               //  Termine une liste.
       listItem()              //  Ajoute une entree a une liste.
       send()                  //  Envoie le message HTML.
       title()                 //  Initialise le titre du document.
      </code>
    <sect2>Voir aussi
     <p>
      <tt>HTML&lowbar;Test, Text</tt>.
    <sect2>HTML()
     <p>
      <descrip>
       <tag/Finalité/ Construit un objet qui contiendra un message HTML.
       <tag/Syntaxe/ <tt>public HTML()</tt>
       <tag/Description/ Crée un message vide qui sera rempli par les
       méthodes HTML.
       <tag/Voir aussi/ <tt>Text</tt>.
      </descrip>
    <sect2>author()
     <p>
      <descrip>
       <tag/Finalité/ Initialise le nom de l'auteur du document.
       <tag/Syntaxe/ <tt>public void author ( String auteur )</tt>
       <tag/Description/ Donne au document un nom d'auteur ayant pour
        valeur <tt>author</tt>.
       <tag/Paramètre/
        <descrip>
         <tag/auteur/ Texte à utiliser en tant que nom d'auteur du message.
        </descrip>
       <tag/Voir aussi/ <tt>title()</tt>.
      </descrip>
    <sect2>definitionList()
     <p>
      <descrip>
       <tag/Finalité/ Crée une liste de définitions.
       <tag/Syntaxe/ <tt>public void definitionList ()</tt>
       <tag/Description/ Initialise une liste de définition. Une <em>liste
         de définitions</em> est une liste spécialisée telle que chaque
        entrée de la liste soit un <em>terme</em> suivi du <em>texte</em>
        correspondant à la définition de ce terme. La création d'une liste
        de définitions doit être suivie par celle d'au moins un couple
        terme/texte, et d'un appel à la méthode <tt>endList()</tt>.
        <em>Notons que, pour le moment, les listes ne peuvent pas être
         imbriquées.</em>
       <tag/Voir aussi/ <tt>definitionListTerm()</tt>, <tt>endList()</tt>,
        <tt>listItem()</tt>.
      </descrip>
    <sect2>definitionListTerm()
     <p>
      <descrip>
       <tag/Finalité/ Ajoute un terme à la liste de définitions.
       <tag/Syntaxe/ <tt>public void definitionListTerm ()</tt>
       <tag/Description/ Ajoute un terme à la liste de définitions. Le texte
        définissant le partie terme de l'entrée courante de la liste devra
        être inséré dans le message après l'appel de cette méthode, et
        avant qu'une méthode <tt>listItem</tt> correspondante soit appelée.
       <tag/Voir aussi/ <tt>definitionList()</tt>, <tt>listItem()</tt>.
      </descrip>
    <sect2>endList()
     <p>
      <descrip>
       <tag/Finalité/ Termine une liste.
       <tag/Syntaxe/ <tt>public void endList ()</tt>
       <tag/Description/ Cette méthode permet de clore une liste.
        <em>Notons que, pour le moment, les listes ne peuvent pas être
         imbriquées.</em>
       <tag/Voir aussi/ <tt>definitionList()</tt>.
      </descrip>
    <sect2>listItem()
     <p>
      <descrip>
       <tag/Finalité/ Ajoute une entrée à une liste.
       <tag/Syntaxe/ <tt>public void listItem ()</tt>
       <tag// <tt>public void listItem ( String article )</tt>
       <tag// <tt>public boolean listItem ( String terme, String article )</tt>
       <tag/Description/ Ajoute une entrée à une liste. Si la première
       forme est utilisée, le texte de l'article de liste courant devra
       être ajouté au message après l'appel de cette méthode, et avant tout
       autre appel à des méthodes de liste. Dans la deuxième et troisième
       forme, le texte
        <tt>article</tt> est passé comme paramètre à la méthode, au lieu (ou
       en plus) d'être ajouté au message. La troisième forme est spécifique
       aux listes de définitions et fournit à la fois le terme et la
       définition de l'entrée de liste.
       <tag/Paramètres/
        <descrip>
         <tag/article/ Le texte de cette entrée de liste de définitions.
         <tag/terme/ Le texte de la partie terme de cette entrée de liste
         de définitions.
        </descrip>
       <tag/Voir aussi/ <tt>definitionList()</tt>,
        <tt>definitionListTerm()</tt>,
        <tt>endList()</tt>.
      </descrip>
    <sect2>send()
     <p>
      <descrip>
       <tag/Finalité/ Envoie le message HTML.
       <tag/Syntaxe/ <tt>public void send ()</tt>
       <tag/Description/ Envoie le message HTML.
      </descrip>
    <sect2>title()
     <p>
      <descrip>
       <tag/Finalité/ Donne une valeur au titre du document.
       <tag/Syntaxe/ <tt>public void title ( String titre )</tt>
       <tag/Description/ Initialise le texte du titre du document.
       <tag/Paramètre/
        <descrip>
         <tag/titre/ Le texte du titre de ce message.
        </descrip>
       <tag/Voir aussi/ <tt>author()</tt>.
      </descrip>
   <sect1>HTML&lowbar;Test<label id="html-test-class">
    <p>
     Cette classe offre à la fois un exemple d'utilisation de la classe
     <tt>HTML</tt> et un programme de test qui peu servir à s'assurer que
     le package <em>Java CGI</em> fonctionne correctement.
    <sect2>Liste des membres
     <p>
      <code>
       main()      //  main() du programme.
      </code>
    <sect2>Voir aussi
     <p>
      <tt>HTML</tt>.
    <sect2>main()
     <p>
      <descrip>
       <tag/Finalité/ Fournit une méthode <tt>main()</tt>.
       <tag/Syntaxe/ <tt>public static void main( String argv[] )</tt>
       <tag/Description/ Il s'agit du point d'entrée pour un programme CGI
       qui retourne une liste des couples nom/valeur d'un document HTML,
       chaque couple étant un élément d'une liste de définitions.
       <tag>Paramètre 
        <descrip>
         <tag/argv[]/ Arguments passés au programme par le script
          <tt>java.cgi</tt> Non utilisé pour l'instant.
        </descrip>
      </descrip>

   <sect1>Text<label id="text-class">
    <p>
    <sect2>Syntaxe
     <p>
      <tt>public abstract class Text</tt>
    <sect2>Description
     <p>
      Cette classe est la superclasse des classes <tt>Email</tt> et
      <tt>HTML</tt>. Les messages sont construits à l'aide des méthodes de
      cette classe, puis complétés et formatés grâce aux méthodes des
      sous-classes.
     <p>
      Cette classe se trouve dans le package <sq>Orbits.text</sq>.
    <sect2>Liste des membres
     <p>
      <code>
       Text()            //  Constructeur.
       add()             //  Ajoute du texte a cet objet.
       addLineBreak()    //  Ajoute une rupture de ligne.
       addParagraph()    //  Ajoute une rupture de paragraphe.
      </code>
    <sect2>Voir aussi
     <p>
      <tt>Email</tt>, <tt>HTML</tt>.
    <sect2>add()
     <p>
      <descrip>
       <tag/Finalité/ Ajoute du texte à cet article
       <tag/Syntaxe/ <tt>public void add ( char ajout )</tt>
       <tag// <tt>public void add ( String ajout )</tt>
       <tag// <tt>public void add ( StringBuffer ajout )</tt>
       <tag/Description/ Ajoute le texte <tt>ajout</tt> à la suite du
        contenu de cet article.
       <tag/Paramètre/
        <descrip>
         <tag/ajout/ Texte à ajouter.
        </descrip>
       <tag/Voir aussi/ <tt>addLineBreak()</tt>, <tt>addParagraph()</tt>.
      </descrip>
    <sect2>addLineBreak()
     <p>
      <descrip>
       <tag/Finalité/ Force une rupture de ligne à cet endroit dans le texte.
       <tag/Syntaxe/ <tt>public void addLineBreak ()</tt>
       <tag/Description/ Insère une rupture de ligne dans le texte, à
       l'endroit du point courant.
       <tag/Voir aussi/ <tt>add()</tt>, <tt>addParagraph()</tt>.
      </descrip>
    <sect2>addParagraph()
     <p>
      <descrip>
       <tag/Finalité/ Débute un nouveau paragraphe.
       <tag/Syntaxe/ <tt>public void add ()</tt>
       <tag/Description/ Débute un  nouveau paragraphe à ce point du flot
        textuel.
       <tag/Voir aussi/ <tt>add()</tt>, <tt>addLineBreak()</tt>.
      </descrip>

  <sect>Améliorations prévues
   <p>
    <itemize>
     <item>
      Ajouter à la classe Email :
      <descrip>
       <tag/Email( int capacité )/ Quand on connaît à l'avance l'espace à
        alloué au message.
       <tag/sendTo( String [] adresse )/ Ajoute une liste de destinations
        principales (champ <tt>To:</tt>) au message e-mail.
       <tag/sendCc( String adresse )/ Ajoute une destination au champ
        <tt>Cc:</tt> (Carbon-Copy) du message e-mail.
       <tag/sendCc( String [] address )/ Ajoute une liste de destinations
        au champ <tt>Cc:</tt> (Carbon-Copy) du message e-mail.
       <tag/sendBcc( String adresse )/ Ajoute une destination au champ
        <tt>Bcc:</tt> (Blind Carbon-Copy) du message e-mail.
       <tag/sendBcc( String [] adresse )/ Ajoute une liste de destinations
        au champ <tt>Bcc:</tt> (Blind Carbon-Copy) du message e-mail.
      </descrip>
     </item>
     <item>
      Ajouter à la classe HTML :
      <descrip>
       <tag/HTML( int capacité )/ Quand on connaît à l'avance l'espace à
        alloué au message.
       <tag/public void unorderedList()/ Démarre une liste non ordonnée.
       <tag/public void orderedList()/  Démarre une liste ordonnée.
       <tag/public void directoryList()/ Démarre une liste de répertoires.
       <tag/public void menuList()/ Démarre une liste de menu.
       <tag/void anchor( String anchorName )/ Spécifie une ancre.
       <tag/void link( String url, String text )/ Spécifie un lien.
       <tag/void applet( String url, String altText )/ Spécifie un lien applet.
      </descrip>
     </item>
     <item>
      Autoriser l'imbrication des listes HTML.
     </item>
     <item>
      Ajouter du code de gestion d'erreur pour s'assurer que le formatage
      des listes HTML s'effectue dans le bon ordre.
     </item>
     <item>
      L'emplacement du fichier des informations d'environnement devra être
      configurable à partir du <tt>Makefile</tt>.
     </item>
     <item>
      &Eacute;liminer les couples nom/valeur vides qui apparaissent dans la
      liste quand la méthode GET est utilisée pour le transfert des
      données.
     </item>
     <item>
      Réfléchir à un moyen d'implémenter l'interface java.util.Enumeration
      avec CGI pour fournir des noms de variables.
     </item>
     <item>
      Ajouter une classe <tt>Test</tt>, qui permettrait d'utiliser toutes
      les méthodes de ce package.
     </item>
     <item>
      Documenter la manière dont <tt>CGI&lowbar;Test</tt>,
      <tt>Email&lowbar;Test</tt> et <tt>HTML&lowbar;Test</tt> se réfèrent
      mutuellement pour fournir des tests incrémentaux facilitant le
      débogage.
     </item>
     <item>
      Documenter la manière dont Test se sert de toutes les fonctionnalités
      présentes dans le package.
     </item>
    </itemize>

  <sect>Modifications
   <p>

   <sect1>Modifications entre les versions 0.3 et 0.4
    <p>
     <itemize>
      <item>
       Développement de la classe HTML pour qu'elle fournisse des
       fonctionnalités minimales.
      </item>
      <item>
       &Eacute;criture de la classe HTML&lowbar;Test et de
       javahtmltest.html-dist.
      </item>
      <item>
       Ajout des méthodes HTML gérant les listes de définitions.
      </item>
     </itemize>

   <sect1>Modifications entre les versions 0.2 et 0.3
    <p>
     <itemize>
      <item>
       Ajout des classes Text et Email. HTML a été également ajouté, sans
       qu'il soit vraiment utilisable.
      </item>
      <item>
       Placement des diverses classes dans des packages. Les classes
       principales se trouvent dans <tt>Orbits.net.*</tt>, la classe de
       support <tt>Text</tt> se trouve dans <tt>Orbits.text.Text</tt>.
      </item>
      <item>
       <tt>CGItest</tt> devient <tt>CGI&lowbar;Test</tt>.
      </item>
      <item>
       Ajout de la classe <tt>Email&lowbar;Test</tt>.
      </item>
     </itemize>

   <sect1>Modifications entre les versions 0.1 et 0.2
    <p>
     <itemize>
      <item>
       Les variables d'environnement sont placées dans un fichier
       temporaire, au lieu d'être passées à l'interpréteur Java sur la
       ligne de commande. La classe <tt>CGI</tt> et le script
       <tt>java.cgi</tt> durent être modifiés.
      </item>
      <item>
       Le document <tt>javacgitest.html</tt> devient partie intégrante de
       la distribution.
      </item>
      <item>
       Les fichiers texte qui sont modifiés par <tt>make</tt> lors de
       l'installation sont fournis avec des noms terminés par
       <em>-dist</em>.
      </item>
     </itemize>

</article>
