
                                Java CGI HOWTO

David H. Silber dhs@orbits.com.

   v0.4, 18 Novembre 1996.
     _________________________________________________________________

   _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 systme Linux, celui-ci est indpendant de
   la version d'Unix utilise. Traduction : Xavier Cazin, le 27 novembre
   1997. _
     _________________________________________________________________

1. Introduction

   Par construction du language, les variables d'environnement du systme
   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
   faons. Vous saurez comment j'ai implment l'une d'elles en
   poursuivant votre lecture.

1.1 Pr-requis

   Je considre que vous tes familiaris avec les principes qui
   sous-tendent HTML et CGI, et que vous possdez un minimum de
   connaissances de votre serveur HTTP. La programmation Java ne devra
   pas non plus vous tre trangre,  dfaut de quoi ce qui va suivre ne
   vous sera pas trs parlant.

1.2 Ce document

   http://www.orbits.com/software/Java_CGI.html est l'adresse o vous
   tes sr de trouver la dernire version de ce document.

1.3 Le package lui-mme

   L'archive ftp://ftp.orbits.com/pub/software/java_cgi-0.4.tgz contient
   la dernire version du package dcrit ici. Vous y trouverez galement
   le source SGML de ce document (en anglais bien sr).

   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
   http://www.orbits.com/software/Java_CGI.html si vous utilisez ce
   logiciel. Vous permettrez ainsi  d'autres d'accder aux classes Java
   CGI.

1.4 Publicit gratuite

   Ce document a t mis au point avec la bienveillance de _Stellar
   Orbits Technology Services_. Si vous voulez savoir ce que nous
   faisons, allez voir  http://www.orbits.com/.

2. Configuration de votre serveur (avec explications)

   Cette section vous conduira  travers l'installation de mon package
   _Java CGI_, et sera agrmente d'explications gnreuses qui vous
   permettront de mesurer les consquences de vos actes. Si vous
   souhaitez simplement installer les programmes, sans vous soucier du
   pourquoi et du comment, sautez directement  la section Configuration
   du serveur (version courte).

2.1 Contraintes logicielles et matrielles

   Ce logiciel devrait fonctionner sur n'importe quel systme  la Unix
   sur lequel se trouvent au moins installs le JDK et un serveur Web.
   J'utilise pour ma part un _Linux Debian_ sur lequel tourne le dmon
   HTTP _apache_. Si cela ne fonctionne pas sur votre installation,
   n'hsitez pas  me contacter  dhs@orbits.com.

   Malheureusement, l'interprteur Java n'est pas particulirement
   conome en mmoire ; si vous devez utiliser souvent des programmes de
   CGI en Java, quelques mgaoctets de RAM supplmentaires ne seront pas
   de trop.

2.2 Java CGI

   Le logiciel que j'ai crit s'appelle _Java CGI_ (Note: au cas o vous
   ne l'auriez pas encore remarqu (NdT)). Vous pouvez le rcuprer par
   ftp anonyme  l'adresse
   ftp://www.orbits.com/pub/software/java_cgi-0.4.tgz. (Le numro de
   version peut avoir chang.)

2.3 Dploiement des sources

   Choisissez un rpertoire o vous pourrez tranquillement dployer
   l'archive du package. Je suggre gnralement /usr/local/src.
   Dsarchivez ensuite  l'aide de la commande (Note : les "lignuxeurs"
   prfreront sans doute le plus lgant tar xzvf java_cgi-0.4.tgz
   (NdT).) :
      gzip -dc java_cgi-0.4.tgz | tar -xvf -

   Cela aura pour effet de crer un rpertoire de nom java_cgi-0.4. Vous
   y trouverez les fichiers auxquels nous feront rfrence dans la suite.
   (Si le numro de version a chang, suivez les instructions qui s'y
   trouvent  partir de maintenant).

2.4 Chemins locaux

   Vous allez devoir dcider de l'endroit o vous souhaitez que les
   programmes Java CGI rsident. La plupart du temps, vous aurez intrt
    les placer dans un rpertoire parallle au rpertoire cgi-bin. La
   configuration de mon serveur _apache_ indiquait /var/web/cgi-bin comme
   rpertoire cgi-bin par dfaut. J'ai donc plac mes programmes Java CGI
   dans le rpertoire /var/web/javacgi. Il n'est pas conseill de placer
   ces programmes dans l'un des rpertoires rfrencs par CLASSPATH.
   ditez le Makefile pour reflter la configuration de votre systme. En
   tant qu'utilisateur root, lancez make install. Cela aura pour effet de
   compiler vos programmes Java, modifier le script java.cgi pour qu'il
   s'adapte  votre systme, 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 plutt make all.

2.5 Test de votre installation

   Les documents javacgitest.html, javaemailtest.html et
   javahtmltest.html devraient maintenant tre installs. Si vous avez
   choisi make all, ils se trouveront dans le rpertoire spcifi par la
   variable WEBDIR du Makefile. Dans le cas contraire, vous pouvez lancer
   make test pour les crer  partir de javacgitest.html-dist,
   javaemailtest.html-dist et javahtmltest.html-dist.

   Aprs vous tre assur que votre installation s'tait droule
   correctement, vous pouvez supprimer les fichiers CGI_Test.class,
   Email_Test.class et HTML_Test.class de votre rpertoire JAVACGI, ainsi
   que javacgitest.html, javaemailtest.html et javahtmltest.html de votre
   rpertoire WEBDIR. Ils montrent les informations utilisateurs
   auxquelles le serveur est normalement seul  avoir accs.

3. Configuration du serveur (version courte)

     * Rcuprez le package _Java CGI_  partir de
       ftp://www.orbits.com/pub/software/java_cgi-0.4.tgz. (Le numro de
       version peut avoir chang.)
     * Dployez la distribution  l'aide de la commande
       gzip -dc java_cgi-0.4.tgz | tar -xvf -
       (Si le numro de version de la distribution a chang, utilisez les
       instructions qui s'y trouvent  partir de maintenant.)
     * ditez le Makefile que vous trouverez dans le nouveau rpertoire
       java_cgi-0.4 pour qu'il reflte la configuration de votre systme.
     * En tant que root, lancez make install. Cela aura pour effet de
       compiler les programmes Java, prendre en compte les informations
       propres  votre systme, et installer les divers fichiers.
       Si vous souhaitez disposer d'une version HTML de ce document,
       ainsi que d'un document test en HTML, lancez plutt make all.
     * Vous devriez maintenant tre par.

4. Excution d'un programme Java CGI

4.1 Difficults d'excution de programmes Java avec le modle CGI

   L'excution d'un programme Java depuis un serveur Web pose deux types
   de problmes majeurs :

  Les programmes Java ne s'excutent pas comme des binaires ordinaires

   Il faut lancer l'interprteur Java et fournir la classe principale (le
   programme  excuter) sur la ligne de commande. Les formulaires HTML
   ne permettent pas d'envoyer directement une ligne de commande au
   serveur Web.

  Java n'accde pas _a priori_ aux variables d'environnement

   Toutes les variables d'environnement requises par le programme Java
   doivent lui tre passes explicitement. Il n'existe pas de mthode
   similaire  la fonction getenv() de _C_ .

4.2 Solutions proposes

   Pour contourner ces obstacles, j'ai crit une script shell de CGI, qui
   fournit les informations ncessaires  l'interprteur Java.

  Le script java.cgi

   Ce script de shell se charge de l'interaction entre le dmon HTTP et
   le programme Java CGI que vous souhaitez utiliser. Il extrait le nom
   du programme que vous souhaitez lancer  partir des donnes fournies
   par le serveur. Il rcupre ensuite toutes les valeurs d'environnement
   dans un fichier temporaire. Enfin, il lance l'interprteur Java en lui
   passant le nom du fichier contenant les informations d'environnement,
   ainsi que le nom du programme  excuter.

   Le script java.cgi a t configur et install selon les procdure
   dcrites  la section Decide On Your Local Path Policies.

  Invocation de java.cgi depuis un formulaire HTML

   Mes formulaires qui utilisent les programmes Java CGI spcifient
   l'action  effectuer de la faon suivante :
 <form action="/cgi-bin/java.cgi/CGI_Test" method="POST">

   o /cgi-bin/ est votre rpertoire local d'excutables CGI, java.cgi
   est l'interface permettant de lancer les programmes Java, et CGI_Test
   est un exemple de programme Java  excuter.

5. Utilisation des classes Java CGI

   Trois classes principales sont pour l'instant supportes : CGI, Email
   et HTML. Je pense y ajouter des classes capables de grer des entres
   et des sorties formates en MIME (respectivement MIMEin & MIMEout).

   Quelques classes de test et de support sont galement disponibles :
   CGI_Test, Email_Test et HTML_Test doivent permettre de tester votre
   installation. Elles peuvent aussi servir de point de dpart  vos
   propres programmes Java bass sur cette bibliothque de classes. La
   classe Text est une superclasse des classes Email et HTML.

5.1 CGI

  Syntaxe

   public class CGI

  Description

   La classe CGI dtient les "informations SGI" : les valeurs
   d'environnement initialises par le serveur Web ainsi que le nom et la
   valeur issus du formulaire quand l'action _submit_ est slectionne.
   Toutes les informations sont stockes dans un objet de classe
   Properties.

   Cette classe se trouve dans le package "Orbits.net".

  Liste des membres
     _________________________________________________________________

       CGI()         //  Constructeur.
       getNames()    //  Recupere la liste de noms.
       getValue()    //  Recupere la valeur a partir du nom.
     _________________________________________________________________

  Voir aussi

   CGI_Test.

  CGI()

   _Finalit_
          Construit un objet contenant les donnes CGI disponibles.

   _Syntaxe_
          public CGI()

   _Description_
          Lorsqu'un objet CGI est construit, toutes les informations CGI
          disponibles sont rcupres et stockes dans le nouvel objet.

  getNames()

   _Finalit_
          Dresse la liste des noms dfinis par le formulaire.

   _Syntaxe_
          public Enumeration getNames ()

   _Description_
          Fournit la liste complte des noms pour lesquels des valeurs
          correspondantes ont t dfinies.

   _Retourne_
          Une Enumeration de tous les noms dfinis.

  getValue()

   _Finalit_
          Rcupre la _valeur_ associe au _nom_ spcifi.

   _Syntaxe_
          public String getValue ( String nom )

   _Description_
          Cette mthode fournit la correspondance entre les noms et les
          valeurs envoyes depuis un formulaire HTML.

   _Paramtre_

        _nom_
                La cl par laquelle les valeurs sont choisies.

   _Retourne_
          Une String contenant la valeur.

5.2 CGI_Test

   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 _Java CGI_ fonctionne correctement.

  Liste des membres
     _________________________________________________________________

       main()      //   main() du programme
     _________________________________________________________________

  Voir aussi

   CGI.

  main()

   _Finalit_
          Fournit une mthode main().

   _Syntaxe_
          public static void main( String argv[] )

   _Description_
          Il s'agit du point d'entre d'un programme CGI qui ne fait rien
           part retourner la liste des couples nom/valeur.

   _Paramtre_

        _argv[]_
                Arguments passs au programme par le script java.cgi. Non
                utilis pour l'instant.

5.3 Email

  Syntaxe

   public class Email extends Text

  Description

   Les messages sont construits au moyen des mthodes add*() de la classe
   Text et les mthodes spcifiques au courrier lectronique fournies par
   cette classe. Une fois compos, le message est envoy vers sa
   destination finale.

   Cette classe se trouve dans le package "Orbits.net".

  Liste des membres
     _________________________________________________________________

       Email()      //  Constructeur
       send()       //  Envoie le message e-mail
       sendTo()     //  Ajoute une destination au message
       subject()    //  Initialise le champ Subject: du message
     _________________________________________________________________

  Voir aussi

   Email_Test, Text.

  Email()

   _Finalit_
          Construit un objet qui contiendra un message lectronique.

   _Syntaxe_
          public Email()

   _Description_
          Cre un message vide qui sera rempli par les mthodes Email.

   _Voir aussi_
          Text.

  send()

   _Finalit_
          Envoie le message e-mail.

   _Syntaxe_
          public void send ()

   _Description_
          Formatage et envoi du message. Si aucune adresse de destination
          n'a t prcise, ne fait rien.

  sendTo()

   _Finalit_
          Ajoute une destination pour ce message.

   _Syntaxe_
          public String sendTo ( String adresse )

   _Description_
          Ajoute adresse  la liste des destinations pour cette mthode.
          Il n'existe pas de limite _a priori_ pour le nombre de
          destinations d'un message e-mail. Je suis sr qu'avec une liste
          assez grande, on peut dpasser la taille acceptable pour le
          _Mail Transport Agent_, voire la mmoire disponible sur votre
          systme.

   _Paramtre_

        _adresse_
                Une destination  laquelle envoyer ce message.

  subject()

   _Finalit_
          Initialise le sujet du message.

   _Syntaxe_
          public void subject ( String sujet )

   _Description_
          Cette mthode remplit le champ Subject: du message. Si elle est
          appele plusieurs fois, le sujet utilis sera le dernier
          demand.

   _Paramtre_

        _sujet_
                Le texte du champ Subject: du message.

5.4 Email_Test

   Cette classe fournit  la fois un exemple d'utilisation de la classe
   Email et un programme de test qu'on pourra utiliser pour s'assurer que
   le package _Java CGI_ fonctionne correctement.

  Liste des membres
     _________________________________________________________________

       main()      //  main() du programme
     _________________________________________________________________

  Voir aussi

   Email.

  main()

   _Finalit_
          Fournit une mthode main().

   _Syntaxe_
          public static void main( String argv[] )

   _Description_
          Il s'agit du point d'entre d'un programme CGI qui retourne une
          liste des couples nom/valeur disponibles. Cette liste sera
          galement envoye  l'adresse spcifie dans la variable Email.

   _Paramtre _

        _argv[]_
                Arguments passs au programme par le script java.cgi. Non
                utilis pour l'instant.

5.5 HTML

  Syntaxe

   public class HTML extends Text

  Description

   Les messages sont crs  l'aide des mthodes add*() de la classe Text
   et des mthodes spcifique au HTML ajoutes par cette classe. Une fois
   termin, le message est envoy.

   Aucun test n'est effectu pour l'instant pour s'asurer que les
   mthodes de construction de liste sont utilises dans le bon ordre.
   C'est donc au programmeur de faire attention  ne pas violer la
   syntaxe HTML.

   Cette classe se trouve dans le package "Orbits.net".

  Liste des membres
     _________________________________________________________________

       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.
     _________________________________________________________________

  Voir aussi

   HTML_Test, Text.

  HTML()

   _Finalit_
          Construit un objet qui contiendra un message HTML.

   _Syntaxe_
          public HTML()

   _Description_
          Cre un message vide qui sera rempli par les mthodes HTML.

   _Voir aussi_
          Text.

  author()

   _Finalit_
          Initialise le nom de l'auteur du document.

   _Syntaxe_
          public void author ( String auteur )

   _Description_
          Donne au document un nom d'auteur ayant pour valeur author.

   _Paramtre_

        _auteur_
                Texte  utiliser en tant que nom d'auteur du message.

   _Voir aussi_
          title().

  definitionList()

   _Finalit_
          Cre une liste de dfinitions.

   _Syntaxe_
          public void definitionList ()

   _Description_
          Initialise une liste de dfinition. Une _liste de dfinitions_
          est une liste spcialise telle que chaque entre de la liste
          soit un _terme_ suivi du _texte_ correspondant  la dfinition
          de ce terme. La cration d'une liste de dfinitions doit tre
          suivie par celle d'au moins un couple terme/texte, et d'un
          appel  la mthode endList(). _Notons que, pour le moment, les
          listes ne peuvent pas tre imbriques._

   _Voir aussi_
          definitionListTerm(), endList(), listItem().

  definitionListTerm()

   _Finalit_
          Ajoute un terme  la liste de dfinitions.

   _Syntaxe_
          public void definitionListTerm ()

   _Description_
          Ajoute un terme  la liste de dfinitions. Le texte dfinissant
          le partie terme de l'entre courante de la liste devra tre
          insr dans le message aprs l'appel de cette mthode, et avant
          qu'une mthode listItem correspondante soit appele.

   _Voir aussi_
          definitionList(), listItem().

  endList()

   _Finalit_
          Termine une liste.

   _Syntaxe_
          public void endList ()

   _Description_
          Cette mthode permet de clore une liste. _Notons que, pour le
          moment, les listes ne peuvent pas tre imbriques._

   _Voir aussi_
          definitionList().

  listItem()

   _Finalit_
          Ajoute une entre  une liste.

   _Syntaxe_
          public void listItem ()

          __public void listItem ( String article )

          __public boolean listItem ( String terme, String article )

   _Description_
          Ajoute une entre  une liste. Si la premire forme est
          utilise, le texte de l'article de liste courant devra tre
          ajout au message aprs l'appel de cette mthode, et avant tout
          autre appel  des mthodes de liste. Dans la deuxime et
          troisime forme, le texte article est pass comme paramtre 
          la mthode, au lieu (ou en plus) d'tre ajout au message. La
          troisime forme est spcifique aux listes de dfinitions et
          fournit  la fois le terme et la dfinition de l'entre de
          liste.

   _Paramtres_

        _article_
                Le texte de cette entre de liste de dfinitions.

        _terme_
                Le texte de la partie terme de cette entre de liste de
                dfinitions.

   _Voir aussi_
          definitionList(), definitionListTerm(), endList().

  send()

   _Finalit_
          Envoie le message HTML.

   _Syntaxe_
          public void send ()

   _Description_
          Envoie le message HTML.

  title()

   _Finalit_
          Donne une valeur au titre du document.

   _Syntaxe_
          public void title ( String titre )

   _Description_
          Initialise le texte du titre du document.

   _Paramtre_

        _titre_
                Le texte du titre de ce message.

   _Voir aussi_
          author().

5.6 HTML_Test

   Cette classe offre  la fois un exemple d'utilisation de la classe
   HTML et un programme de test qui peu servir  s'assurer que le package
   _Java CGI_ fonctionne correctement.

  Liste des membres
     _________________________________________________________________

       main()      //  main() du programme.
     _________________________________________________________________

  Voir aussi

   HTML.

  main()

   _Finalit_
          Fournit une mthode main().

   _Syntaxe_
          public static void main( String argv[] )

   _Description_
          Il s'agit du point d'entre pour un programme CGI qui retourne
          une liste des couples nom/valeur d'un document HTML, chaque
          couple tant un lment d'une liste de dfinitions.

   _Paramtre _

        _argv[]_
                Arguments passs au programme par le script java.cgi Non
                utilis pour l'instant.

5.7 Text

  Syntaxe

   public abstract class Text

  Description

   Cette classe est la superclasse des classes Email et HTML. Les
   messages sont construits  l'aide des mthodes de cette classe, puis
   complts et formats grce aux mthodes des sous-classes.

   Cette classe se trouve dans le package "Orbits.text".

  Liste des membres
     _________________________________________________________________

       Text()            //  Constructeur.
       add()             //  Ajoute du texte a cet objet.
       addLineBreak()    //  Ajoute une rupture de ligne.
       addParagraph()    //  Ajoute une rupture de paragraphe.
     _________________________________________________________________

  Voir aussi

   Email, HTML.

  add()

   _Finalit_
          Ajoute du texte  cet article

   _Syntaxe_
          public void add ( char ajout )

          __public void add ( String ajout )

          __public void add ( StringBuffer ajout )

   _Description_
          Ajoute le texte ajout  la suite du contenu de cet article.

   _Paramtre_

        _ajout_
                Texte  ajouter.

   _Voir aussi_
          addLineBreak(), addParagraph().

  addLineBreak()

   _Finalit_
          Force une rupture de ligne  cet endroit dans le texte.

   _Syntaxe_
          public void addLineBreak ()

   _Description_
          Insre une rupture de ligne dans le texte,  l'endroit du point
          courant.

   _Voir aussi_
          add(), addParagraph().

  addParagraph()

   _Finalit_
          Dbute un nouveau paragraphe.

   _Syntaxe_
          public void add ()

   _Description_
          Dbute un nouveau paragraphe  ce point du flot textuel.

   _Voir aussi_
          add(), addLineBreak().

6. Amliorations prvues

     * Ajouter  la classe Email :

        _Email( int capacit )_
                Quand on connat  l'avance l'espace  allou au message.

        _sendTo( String [] adresse )_
                Ajoute une liste de destinations principales (champ To:)
                au message e-mail.

        _sendCc( String adresse )_
                Ajoute une destination au champ Cc: (Carbon-Copy) du
                message e-mail.

        _sendCc( String [] address )_
                Ajoute une liste de destinations au champ Cc:
                (Carbon-Copy) du message e-mail.

        _sendBcc( String adresse )_
                Ajoute une destination au champ Bcc: (Blind Carbon-Copy)
                du message e-mail.

        _sendBcc( String [] adresse )_
                Ajoute une liste de destinations au champ Bcc: (Blind
                Carbon-Copy) du message e-mail.

     * Ajouter  la classe HTML :

        _HTML( int capacit )_
                Quand on connat  l'avance l'espace  allou au message.

        _public void unorderedList()_
                Dmarre une liste non ordonne.

        _public void orderedList()_
                Dmarre une liste ordonne.

        _public void directoryList()_
                Dmarre une liste de rpertoires.

        _public void menuList()_
                Dmarre une liste de menu.

        _void anchor( String anchorName )_
                Spcifie une ancre.

        _void link( String url, String text )_
                Spcifie un lien.

        _void applet( String url, String altText )_
                Spcifie un lien applet.

     * Autoriser l'imbrication des listes HTML.
     * Ajouter du code de gestion d'erreur pour s'assurer que le
       formatage des listes HTML s'effectue dans le bon ordre.
     * L'emplacement du fichier des informations d'environnement devra
       tre configurable  partir du Makefile.
     * liminer les couples nom/valeur vides qui apparaissent dans la
       liste quand la mthode GET est utilise pour le transfert des
       donnes.
     * Rflchir  un moyen d'implmenter l'interface
       java.util.Enumeration avec CGI pour fournir des noms de variables.
     * Ajouter une classe Test, qui permettrait d'utiliser toutes les
       mthodes de ce package.
     * Documenter la manire dont CGI_Test, Email_Test et HTML_Test se
       rfrent mutuellement pour fournir des tests incrmentaux
       facilitant le dbogage.
     * Documenter la manire dont Test se sert de toutes les
       fonctionnalits prsentes dans le package.

7. Modifications

7.1 Modifications entre les versions 0.3 et 0.4

     * Dveloppement de la classe HTML pour qu'elle fournisse des
       fonctionnalits minimales.
     * criture de la classe HTML_Test et de javahtmltest.html-dist.
     * Ajout des mthodes HTML grant les listes de dfinitions.

7.2 Modifications entre les versions 0.2 et 0.3

     * Ajout des classes Text et Email. HTML a t galement ajout, sans
       qu'il soit vraiment utilisable.
     * Placement des diverses classes dans des packages. Les classes
       principales se trouvent dans Orbits.net.*, la classe de support
       Text se trouve dans Orbits.text.Text.
     * CGItest devient CGI_Test.
     * Ajout de la classe Email_Test.

7.3 Modifications entre les versions 0.1 et 0.2

     * Les variables d'environnement sont places dans un fichier
       temporaire, au lieu d'tre passes  l'interprteur Java sur la
       ligne de commande. La classe CGI et le script java.cgi durent tre
       modifis.
     * Le document javacgitest.html devient partie intgrante de la
       distribution.
     * Les fichiers texte qui sont modifis par make lors de
       l'installation sont fournis avec des noms termins par _-dist_.
