dhs@orbits.com
. 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.
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.
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.
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.
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/.
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).
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.
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�.)
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).
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
.
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.
gzip -dc java_cgi-0.4.tgz | tar -xvf -(Si le num�ro de version de la distribution a chang�, utilisez les instructions qui s'y trouvent � partir de maintenant.)
Makefile
que vous trouverez dans le nouveau
r�pertoire java_cgi-0.4
pour qu'il refl�te la
configuration de votre syst�me.make install
. Cela aura pour effet
de compiler les programmes Java, prendre en compte les informations
propres � votre syst�me, 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 plut�t make all
.
L'ex�cution d'un programme Java depuis un serveur Web pose deux types de probl�mes majeurs :
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.
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 .
Pour contourner ces obstacles, j'ai �crit une script shell de CGI, qui fournit les informations n�cessaires � l'interpr�teur Java.
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.
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.
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
.
public class CGI
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".
CGI() // Constructeur. getNames() // Recupere la liste de noms. getValue() // Recupere la valeur a partir du nom.
CGI_Test
.
Construit un objet contenant les donn�es CGI disponibles.
public CGI()
Lorsqu'un objet CGI est construit, toutes les informations CGI disponibles sont r�cup�r�es et stock�es dans le nouvel objet.
Dresse la liste des noms d�finis par le formulaire.
public Enumeration getNames ()
Fournit la liste compl�te des noms pour lesquels des valeurs correspondantes ont �t� d�finies.
Une Enumeration
de tous les noms d�finis.
R�cup�re la valeur associ�e au nom sp�cifi�.
public String getValue ( String nom )
Cette m�thode fournit la correspondance entre les
noms
et les valeurs
envoy�es depuis un formulaire
HTML.
La cl� par laquelle les valeurs sont choisies.
Une String
contenant la valeur.
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.
main() // main() du programme
CGI
.
Fournit une m�thode main()
.
public static void main( String argv[] )
Il s'agit du point d'entr�e d'un programme CGI qui ne fait rien � part retourner la liste des couples nom/valeur.
Arguments pass�s au programme par le script
java.cgi
.
Non utilis� pour l'instant.
public class Email extends Text
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".
Email() // Constructeur send() // Envoie le message e-mail sendTo() // Ajoute une destination au message subject() // Initialise le champ Subject: du message
Email_Test, Text
.
Construit un objet qui contiendra un message �lectronique.
public Email()
Cr�e un message vide qui sera rempli par les m�thodes Email.
Text
.
Envoie le message e-mail.
public void send ()
Formatage et envoi du message. Si aucune adresse de destination n'a �t� pr�cis�e, ne fait rien.
Ajoute une destination pour ce message.
public String sendTo ( String adresse )
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.
Une destination � laquelle envoyer ce message.
Initialise le sujet du message.
public void subject ( String sujet )
Cette m�thode remplit le champ
Subject:
du message. Si elle est appel�e plusieurs fois,
le sujet utilis� sera le dernier demand�.
Le texte du champ Subject:
du message.
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.
main() // main() du programme
Email
.
Fournit une m�thode main()
.
public static void main( String argv[] )
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
.
Arguments pass�s au programme par le script
java.cgi
. Non utilis� pour l'instant.
public class HTML extends Text
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".
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.
HTML_Test, Text
.
Construit un objet qui contiendra un message HTML.
public HTML()
Cr�e un message vide qui sera rempli par les m�thodes HTML.
Text
.
Initialise le nom de l'auteur du document.
public void author ( String auteur )
Donne au document un nom d'auteur ayant pour
valeur author
.
Texte � utiliser en tant que nom d'auteur du message.
title()
.
Cr�e une liste de d�finitions.
public void definitionList ()
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.
definitionListTerm()
, endList()
,
listItem()
.
Ajoute un terme � la liste de d�finitions.
public void definitionListTerm ()
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.
definitionList()
, listItem()
.
Termine une liste.
public void endList ()
Cette m�thode permet de clore une liste. Notons que, pour le moment, les listes ne peuvent pas �tre imbriqu�es.
definitionList()
.
Ajoute une entr�e � une liste.
public void listItem ()
public void listItem ( String article )
public boolean listItem ( String terme, String article )
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.
Le texte de cette entr�e de liste de d�finitions.
Le texte de la partie terme de cette entr�e de liste de d�finitions.
definitionList()
,
definitionListTerm()
,
endList()
.
Envoie le message HTML.
public void send ()
Envoie le message HTML.
Donne une valeur au titre du document.
public void title ( String titre )
Initialise le texte du titre du document.
Le texte du titre de ce message.
author()
.
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.
main() // main() du programme.
HTML
.
Fournit une m�thode main()
.
public static void main( String argv[] )
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.
Arguments pass�s au programme par le script
java.cgi
Non utilis� pour l'instant.
public abstract class Text
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".
Text() // Constructeur. add() // Ajoute du texte a cet objet. addLineBreak() // Ajoute une rupture de ligne. addParagraph() // Ajoute une rupture de paragraphe.
Email
, HTML
.
Ajoute du texte � cet article
public void add ( char ajout )
public void add ( String ajout )
public void add ( StringBuffer ajout )
Ajoute le texte ajout
� la suite du
contenu de cet article.
Texte � ajouter.
addLineBreak()
, addParagraph()
.
Force une rupture de ligne � cet endroit dans le texte.
public void addLineBreak ()
Ins�re une rupture de ligne dans le texte, � l'endroit du point courant.
add()
, addParagraph()
.
D�bute un nouveau paragraphe.
public void add ()
D�bute un nouveau paragraphe � ce point du flot textuel.
add()
, addLineBreak()
.
Quand on conna�t � l'avance l'espace � allou� au message.
Ajoute une liste de destinations
principales (champ To:
) au message e-mail.
Ajoute une destination au champ
Cc:
(Carbon-Copy) du message e-mail.
Ajoute une liste de destinations
au champ Cc:
(Carbon-Copy) du message e-mail.
Ajoute une destination au champ
Bcc:
(Blind Carbon-Copy) du message e-mail.
Ajoute une liste de destinations
au champ Bcc:
(Blind Carbon-Copy) du message e-mail.
Quand on conna�t � l'avance l'espace � allou� au message.
D�marre une liste non ordonn�e.
D�marre une liste ordonn�e.
D�marre une liste de r�pertoires.
D�marre une liste de menu.
Sp�cifie une ancre.
Sp�cifie un lien.
Sp�cifie un lien applet.
Makefile
.Test
, qui permettrait d'utiliser toutes
les m�thodes de ce package.CGI_Test
,
Email_Test
et HTML_Test
se r�f�rent
mutuellement pour fournir des tests incr�mentaux facilitant le
d�bogage.
Orbits.net.*
, la classe de
support Text
se trouve dans Orbits.text.Text
.CGItest
devient CGI_Test
.Email_Test
.
CGI
et le script
java.cgi
durent �tre modifi�s.javacgitest.html
devient partie int�grante de
la distribution.make
lors de
l'installation sont fournis avec des noms termin�s par
-dist.