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.