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 syst�me Linux, celui-ci est ind�pendant de la version d'Unix utilis�e. Traduction : Xavier Cazin, le 27 novembre 1997.

1. Introduction

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.

1.1 Pr�-requis

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.

1.2 Ce document

http://www.orbits.com/software/Java_CGI.html est l'adresse o� vous �tes s�r de trouver la derni�re version de ce document.

1.3 Le package lui-m�me

L'archive ftp://ftp.orbits.com/pub/software/java_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 http://www.orbits.com/software/Java_CGI.html si vous utilisez ce logiciel. Vous permettrez ainsi � d'autres d'acc�der 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 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 Configuration du serveur (version courte).

2.1 Contraintes logicielles et mat�rielles

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 Linux Debian sur lequel tourne le d�mon HTTP apache. Si cela ne fonctionne pas sur votre installation, n'h�sitez pas � me contacter � dhs@orbits.com.

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.

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 r�cup�rer par ftp anonyme � l'adresse ftp://www.orbits.com/pub/software/java_cgi-0.4.tgz. (Le num�ro de version peut avoir chang�.)

2.3 D�ploiement des sources

Choisissez un r�pertoire o� vous pourrez tranquillement d�ployer l'archive du package. Je sugg�re g�n�ralement /usr/local/src. D�sarchivez ensuite � l'aide de la commande (Note : les "lignuxeurs" pr�f�reront sans doute le plus �l�gant tar xzvf java_cgi-0.4.tgz (NdT).) :

      gzip -dc java_cgi-0.4.tgz | tar -xvf - 
Cela aura pour effet de cr�er un r�pertoire de nom java_cgi-0.4. 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).

2.4 Chemins locaux

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 cgi-bin. La configuration de mon serveur apache indiquait /var/web/cgi-bin comme r�pertoire cgi-bin par d�faut. J'ai donc plac� mes programmes Java CGI dans le r�pertoire /var/web/javacgi. Il n'est pas conseill� de placer ces programmes dans l'un des r�pertoires r�f�renc�s par CLASSPATH. Éditez le Makefile pour refl�ter la configuration de votre syst�me. 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 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 make all.

2.5 Test de votre installation

Les documents javacgitest.html, javaemailtest.html et javahtmltest.html devraient maintenant �tre install�s. Si vous avez choisi make all, ils se trouveront dans le r�pertoire sp�cifi� par la variable WEBDIR du Makefile. Dans le cas contraire, vous pouvez lancer make test pour les cr�er � partir de javacgitest.html-dist, javaemailtest.html-dist et javahtmltest.html-dist.

Apr�s vous �tre assur� que votre installation s'�tait d�roul�e correctement, vous pouvez supprimer les fichiers CGI_Test.class, Email_Test.class et HTML_Test.class de votre r�pertoire JAVACGI, ainsi que javacgitest.html, javaemailtest.html et javahtmltest.html de votre r�pertoire WEBDIR. Ils montrent les informations utilisateurs auxquelles le serveur est normalement seul � avoir acc�s.

3. Configuration du serveur (version courte)

4. Ex�cution d'un programme Java CGI

4.1 Difficult�s d'ex�cution de programmes Java avec le mod�le CGI

L'ex�cution d'un programme Java depuis un serveur Web pose deux types de probl�mes majeurs :

Les programmes Java ne s'ex�cutent pas comme des binaires ordinaires

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.

Java n'acc�de pas a priori aux variables d'environnement

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 getenv() de C .

4.2 Solutions propos�es

Pour contourner ces obstacles, j'ai �crit une script shell de CGI, qui fournit les informations n�cessaires � l'interpr�teur Java.

Le script java.cgi

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.

Le script java.cgi a �t� configur� et install� selon les proc�dure d�crites � la section Decide On Your Local Path Policies.

Invocation de java.cgi depuis un formulaire HTML

Mes formulaires qui utilisent les programmes Java CGI sp�cifient l'action � effectuer de la fa�on suivante :

 <form action="/cgi-bin/java.cgi/CGI_Test" method="POST">
o� /cgi-bin/ est votre r�pertoire local d'ex�cutables CGI, java.cgi est l'interface permettant de lancer les programmes Java, et CGI_Test est un exemple de programme Java � ex�cuter.

5. Utilisation des classes Java CGI

Trois classes principales sont pour l'instant support�es : CGI, Email et HTML. Je pense y ajouter des classes capables de g�rer des entr�es et des sorties format�es 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 d�part � vos propres programmes Java bas�s sur cette biblioth�que de classes. La classe Text est une superclasse des classes Email et HTML.

5.1 CGI

Syntaxe

public class CGI

Description

La classe CGI d�tient les "informations SGI" : les valeurs d'environnement initialis�es par le serveur Web ainsi que le nom et la valeur issus du formulaire quand l'action submit est s�lectionn�e. Toutes les informations sont stock�es 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 donn�es CGI disponibles.

Syntaxe

public CGI()

Description

Lorsqu'un objet CGI est construit, toutes les informations CGI disponibles sont r�cup�r�es et stock�es dans le nouvel objet.

getNames()

Finalit�

Dresse la liste des noms d�finis par le formulaire.

Syntaxe

public Enumeration getNames ()

Description

Fournit la liste compl�te des noms pour lesquels des valeurs correspondantes ont �t� d�finies.

Retourne

Une Enumeration de tous les noms d�finis.

getValue()

Finalit�

R�cup�re la valeur associ�e au nom sp�cifi�.

Syntaxe

public String getValue ( String nom )

Description

Cette m�thode fournit la correspondance entre les noms et les valeurs envoy�es depuis un formulaire HTML.

Param�tre

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 m�thode main().

Syntaxe

public static void main( String argv[] )

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.

Param�tre

argv[]

Arguments pass�s 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 m�thodes add*() de la classe Text et les m�thodes sp�cifiques 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

Cr�e un message vide qui sera rempli par les m�thodes 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� pr�cis�e, 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 m�thode. Il n'existe pas de limite a priori 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 Mail Transport Agent, voire la m�moire disponible sur votre syst�me.

Param�tre

adresse

Une destination � laquelle envoyer ce message.

subject()

Finalit�

Initialise le sujet du message.

Syntaxe

public void subject ( String sujet )

Description

Cette m�thode remplit le champ Subject: du message. Si elle est appel�e plusieurs fois, le sujet utilis� sera le dernier demand�.

Param�tre

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 m�thode main().

Syntaxe

public static void main( String argv[] )

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

Param�tre

argv[]

Arguments pass�s 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 cr��s � l'aide des m�thodes add*() de la classe Text et des m�thodes sp�cifique au HTML ajout�es par cette classe. Une fois termin�, le message est envoy�.

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.

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

Cr�e un message vide qui sera rempli par les m�thodes 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.

Param�tre

auteur

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

Voir aussi

title().

definitionList()

Finalit�

Cr�e une liste de d�finitions.

Syntaxe

public void definitionList ()

Description

Initialise une liste de d�finition. Une liste de d�finitions est une liste sp�cialis�e telle que chaque entr�e de la liste soit un terme suivi du texte 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 endList(). Notons que, pour le moment, les listes ne peuvent pas �tre imbriqu�es.

Voir aussi

definitionListTerm(), endList(), listItem().

definitionListTerm()

Finalit�

Ajoute un terme � la liste de d�finitions.

Syntaxe

public void definitionListTerm ()

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 listItem correspondante soit appel�e.

Voir aussi

definitionList(), listItem().

endList()

Finalit�

Termine une liste.

Syntaxe

public void endList ()

Description

Cette m�thode permet de clore une liste. Notons que, pour le moment, les listes ne peuvent pas �tre imbriqu�es.

Voir aussi

definitionList().

listItem()

Finalit�

Ajoute une entr�e � une liste.

Syntaxe

public void listItem ()

public void listItem ( String article )

public boolean listItem ( String terme, String article )

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

Param�tres

article

Le texte de cette entr�e de liste de d�finitions.

terme

Le texte de la partie terme de cette entr�e de liste de d�finitions.

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.

Param�tre

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 m�thode main().

Syntaxe

public static void main( String argv[] )

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.

Param�tre

argv[]

Arguments pass�s 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 m�thodes de cette classe, puis compl�t�s et format�s gr�ce aux m�thodes 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.

Param�tre

ajout

Texte � ajouter.

Voir aussi

addLineBreak(), addParagraph().

addLineBreak()

Finalit�

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

Syntaxe

public void addLineBreak ()

Description

Ins�re une rupture de ligne dans le texte, � l'endroit du point courant.

Voir aussi

add(), addParagraph().

addParagraph()

Finalit�

D�bute un nouveau paragraphe.

Syntaxe

public void add ()

Description

D�bute un nouveau paragraphe � ce point du flot textuel.

Voir aussi

add(), addLineBreak().

6. Am�liorations pr�vues

7. Modifications

7.1 Modifications entre les versions 0.3 et 0.4

7.2 Modifications entre les versions 0.2 et 0.3

7.3 Modifications entre les versions 0.1 et 0.2