|
Ce document propose quelques règles de façon à homogénéiser les développements de Portlets. |
| Dates de modification | ||
|---|---|---|
|
|
|
|
L'environnement de développement est sensiblement le même que celui d'un canal uPortal.
De façon à avoir des Portlets qui se compilent / déploient de façon identique, voici un fichier de configuration ANT pouvant servir de base commune à tous les développements :
Comme pour les canaux, il est composé de deux parties, l'une réservée au développeur, l'autre à la personne qui le déploie.
Voici les différentes propriétés à configurer pour l'administrateur système :
portal.lib : pour sa compilation, une Portlet nécessite des librairies fournies par le portail (quel que soit celui-ci), en particulier l'API Portlet (portlet-api.jar) et son implémentation (avec uPortal il s'agit de pluto.jar).
Exemple avec uPortal : /home/uportal/uPortal_5-2-1-quick-start/uPortal_rel-5.2.1/lib
tomcat.home : toujours pour sa compilation, une Portlet a besoin des librairies Tomcat (servlet.jar).
Exemple avec uPortal : /home/uportal/uPortal_5-2-1-quick-start/Tomcat_5-5-9
deploy.home : ce paramètre est utilisé si vous déployer votre Portlet directement dans Tomcat, sans passer par l'intermédiaire d'un fichier WAR et la tâche de déploiement spécifique au portail.
Exemple avec uPortal : /home/uportal/webapps
Voici les différentes propriétés à configurer pour le développeur :
application.name : le nom de l'application. Il est important de noter que ce nom devra obligatoirement être utilisé à d'autres moments, par exemple pour le contexte Tomcat de déploiement, le nom de l'application dans le fichier web.xml etc. Comme pour les canaux uPortal, on pourra préfixer ce nom avec l'établissement / projet / organisation auteur du développement et on indiquera qu'il s'agit d'une Portlet.
Exemples : esup-portlet-actus, univnancy2-portlet-doc
application.version : l'identifiant de version de la Portlet, qui sera utilisé dans la construction du package de distribution au format ZIP.
Exemple : 2.31-RC-4
Voici les propriétés utilisées pour la génération de la documentation de la Portlet au format DocBook :
url.xsl : l'adresse où se trouve la feuille de style XSL pour la transformation.
url.lib : l'adresse où peuvent être téléchargées les librairies nécessaires.
Ce fichier propose un ensemble de tâches ANT pouvant servir de base à n'importe quelle Portlet. Un développeur peut choisir d'étendre celles-ci afin d'avoir des options spécifiques. Par exemple avec Spring, il est parfois nécessaire d'effectuer des changements dans les fichiers de configuration au moment du déploiement ou de la construction du WAR.
Le seul paramètre à modifier dans ce fichier (hormis une personnalisation plus poussée) est le nom projet indiqué dans la première ligne.
Voici un bref descriptif des tâches ANT et de leur utilité :
prepare : permet de créer tous les dossiers utiles d'un projet en partant de zéro, la section 3 détaille ceux-ci.
compile : permet de compiler les sources Java dans un dossier temporaire afin de vérifier qu'il n'y a aucun problème à ce niveau.
deploy : permet de déployer directement la Portlet dans Tomcat, sans passer par un fichier WAR intermédiaire. Cette méthode n'est valable qu'avec Pluto et le développeur doit alors fournir un fichier de déploiement web-pluto.xml spécifique.
undeploy : supprime la portlet dans Tomcat, la suppression du contexte dans le fichier server.xml de celui-ci doit être réalisée à la main.
clean : supprime tous les fichiers temporaires créés lors des tâches précédentes.
all : effectue les tâches suivantes : undeploy, clean, deploy.
buildwar : construit un fichier WAR standard pouvant être déployé dans n'importe quel conteneur de Portlets (celui-ci ayant la charge d'effectuer les modifications nécessaires notemment au fichier web.xml).
buildzip : construit une archive ZIP destinées à la distribution de la Portlet avec ses sources, sa documentation etc.
docbook.html : génère la documentation DocBook au format HTML.
docbook.html.noindex : génère la documentation DocBook au format HTML sans index.
Pour commencer un nouveau projet, il suffit de placer les fichiers build.xml et build.properties, de les configurer et de lancer la tâche ANT prepare. Une arborescence est alors créée qui ressemble à quelques exceptions près à celle d'un canal uPortal.
Voici dans le détail les différents dossiers qui sont créés :
build : dossier temporaire où se déroulent l'ensemble des opérations avant de déployer. Dans un projet Eclipse, il faut indiquer comme répertoire de compilation build/WEB-INF/classes.
db : fichiers nécessaires à la création de la base de données de la Portlet (si il y en a une). Ces fichiers ne sont pas déployés.
dist : fichiers créés par les tâches ANT buildwar et buildzip.
docs : documentation de la Portlet.
docs/api : API Java
docs/docbook/pages/xml : fichiers XML permettant la génération de la documentation au format DocBook.
lib : les librairies nécessaires à la compilation / exécution de la portlets. Ces librairies sont systématiquement déployées, il convient donc de supprimer celles qui auraient été placées directement dans Tomcat.
properties : fichiers de configuration de la Portlet. Ces fichiers sont déployés à la racine du dossier WEB-INF/classes de façon à ce qu'ils soient inacessibles pour des utilisateurs. Par exemple, c'est l'endroit idéal pour mettre le fichier log4j.properties, des fichiers de configuration Ibatis ainsi que les fichiers pour Spring. De nombreux outils n'acceptent pas que leurs fichiers de configuration soient placés ailleurs qu'à la racine.
source : les sources Java. Il est important de respecter les règles habituelles de nommage en remplaçant 'channel' par 'portlet'.
Exemple : org.esupportail.portlet.maportlet.
webpages : les fichiers ayant un rapport avec le rendu graphique de la Portlet.
webpages/media : tous les fichiers statiques (images, CSS, JavaScript etc.).
Important
Tous les fichiers se trouvant dans ce répertoire sont déployés dans un dossier 'images' situé à la racine de l'application web. Les développeurs doivent respecter cette façon de faire afin qu'Apache puisse délivrer lui même ces contenus statiques. Le non respect de cette pratique obligerait les administrateurs à modifier la configuration Apache pour chacune des Portlets procédant autrement.
webpages/stylesheets : toutes les pages JSP de la Portlet.
Important
Tous les fichiers se trouvant dans ce répertoire sont déployés dans le dossier WEB-INF/jsp.
webpages/tags : les fichiers de description (TLD) des taglibs utilisées dans les pages JSP.
webpages/web.xml : le descripteur de déploiement 'standard' de la Portlet. Ce fichier est généralement modifié par le moteur de Portlet choisi.
webpages/web-pluto : le descripteur de déploiement déjà modifié pour Pluto, de façon à déployer la Portlet directement dans Tomcat sans passer par un outil spécifique.
webpages/portlet.xml : le descripteur de la Portlet.
Tout comme les canaux uPortal, les Portlets ont parfois besoin d'accéder à une base de données. Il est possible de laisser le soin à Tomcat de gérer un pool de connexions pour une Portlet de la même façon que pour le portail puisqu'une Portlet est un contexte Java à part entière. Toutefois, il est beaucoup plus intéressant de pouvoir partager ce pool entre les deux applications.
Voici comment est défini un pool dans le contexte du portail :
<Context path="/uPortal" docBase="/home/uPortal/webapps/uPortal" crossContext="true">
<Resource name="jdbc/MonPool" auth="Container" type="javax.sql.DataSource"
username="user" password="password"
driverClassName="com.mysql.jdbc.Driver" url="jdbc:mysql://mysql.univ.fr/mabase"
maxActive="100" maxIdle="30" maxWait="10000" />
...
</Context>
On va déplacer la définition de ce pool dans les déclarations globales JNDI et y faire référence à la fois depuis le contexte du portail et depuis le contexte de la Portlet :
<GlobalNamingResources>
...
<Resource name="MonPool" auth="Container" type="javax.sql.DataSource"
username="user" password="password"
driverClassName="com.mysql.jdbc.Driver" url="jdbc:mysql://mysql.univ.fr/mabase"
maxActive="100" maxIdle="30" maxWait="10000" />
...
</GlobalNamingResources>
...
<Context path="/uPortal" docBase="/home/uPortal/webapps/uPortal" crossContext="true">
<ResourceLink name="jdbc/MonPool" global="MonPool" type="javax.sql.DataSource" />
...
</Context>
...
<Context path="esup-portlet-test" docBase="/home/uPortal/webapps/esup-portlet-test" crossContext="true">
<ResourceLink name="jdbc/MonPool" global="MonPool" type="javax.sql.DataSource" />
</Context>
De cette façon, nos deux applications accèdent au même pool.
Comme dans le cas du portail (et de n'importe quelle application Java), il est recommandé de laisser le soin au frontal Apache de délivrer les contenus statiques. Voici un exemple de configuration avec mod_jk permettant de déclarer à la fois les ressources statiques du portail mais également celles de toutes les Portlets respectant la convention du dossier 'images'.
Extrait du fichier de configuration Apache, le contexte du portail étant accessible à la racine d'un VirtualHost : # On pointe à la racine du webapps où sont placés les contextes uPortal et les Portlets DocumentRoot "/home/uportal/webapps" ... <IfModule mod_jk.c> # On monte des alias automatiques à la racine de uPortal JkAutoAlias /home/uportal/webapps/uPortal # On envoie toutes les requêtes à Tomcat JkMount /* portal # On démonte les accès statiques, les auto-alias feront le reste : JkUnMount /media/* portal JkUnMount /dtd/* portal JkUnMount /static/* portal # On démonte les accès statiques aux Portlets le DocumentRoot se chargeant de trouver les fichiers JkUnMount /*/images/* portal </IfModule>
Imaginons une Portlet esup-portlet-test. De façon standard elle a été déployée dans le dossier /home/uportal/webapps/esup-portlet-test. De la même façon, elle est 'montée' dans un contexte du même nom et est accessibles par l'url http://portail.univ.fr/esup-portlet-test. L'accès à une image (ou à n'importe quel contenu statique) se fait au travers d'une URL du genre http://portail.univ.fr/esup-portlet-test/images/icon.gif. Ne trouvant aucun dossier appelé 'esup-portlet-test' à la racine du contexte uPortal pointé par la directive JkAutoAlias, Apache se tourne vers le DocumentRoot et le tour est joué.
A noter que tous les contenus statiques de Portlets se trouvant dans un dossier différent du dossier 'images' seront toujours délivrés par Tomcat, il est donc important d'avoir une règle commune à tous les développeurs (c'est ce qui est préconisé par Spring et déjà utilisé dans les Portlets d'exemple fournies avec uPortal).