Eclipse : JAR Deployment

Eclipse4.5_JAR_Deployment.docx HEIA-FR / Jacques BAPST 1
Jacques BAPST
2 juillet 2015
4.5
DÉPLOIEMENT D'APPLICATIONS JAVA
SOUS FORME DE FICHIERS JAR
FICHIERS JAR
Les fichiers JAR (Java Archive) permettent de rassembler dans une seule entité, toutes les ressources
nécessaires au fonctionnement d'un composant logiciel, d'une librairie ou d'une application (fichiers compilés
.class, images, sons, documentation, …). Ils permettent notamment de simplifier le déploiement des
applications Java qui peuvent être ainsi distribuées sous la forme d'un unique fichier (à l'exception
d'éventuelles librairies externes, elles-mêmes déployées sous forme de fichiers JAR).
Les fichiers JAR utilisent le même format que les fichiers ZIP et, comme eux, ils permettent de structurer le
contenu sous une forme arborescente (avec des dossiers et sous-dossiers) et de comprimer optionnellement
le contenu (réduire la taille du fichier).
Les fichiers JAR contiennent un fichier particulier, appelé Manifest File (MANIFEST.MF) qui se trouve dans un
dossier META-INF et qui donne des informations (méta-informations) sur le contenu du fichier JAR. Dans le cas
d'un programme exécutable, le Manifest File doit notamment indiquer le nom de la classe principale (celle qui
contient la méthode main()).
Remarque : L'imbrication de fichiers JAR n'est pas directement supportée par Java. Si l'application est
constituée de plusieurs fichiers JAR (si elle comporte des librairies externes par exemple), il est
conseillé de déployer les différents fichiers JAR dans les emplacements souhaités et de les
référencer dans le fichier Manifest du fichier JAR principal en utilisant le mot clé Class-Path (le
point "." représente le répertoire courant, un espace sépare les différents répertoires ou
fichiers JAR, le slash "/" sépare les niveaux des répertoires).
Exemple de contenu d'un fichier Manifest :
Manifest-Version: 1.0
Main-Class: basic.jardeployment.TestApplic
Class-Path: . lib/colorlib.jar lib/firebirdsql.jar
Dans ce cas, deux librairies externes sont enregistrées dans le sous-répertoire /lib du répertoire contenant
le fichier JAR principal. Le répertoire courant (".") fera également partie du Class-Path et sera pris en compte
lors de la recherche de ressources (mais si des fichiers JAR s'y trouvent, ils doivent être explicitement
mentionnés dans la liste).
Une documentation détaillée concernant les fichiers JAR et la syntaxe du fichier Manifest est disponible à
l'adresse :
http://download.oracle.com/javase/8/docs/technotes/guides/jar/

Eclipse4.5_JAR_Deployment.docx HEIA-FR / Jacques BAPST 2
CRÉATION D'UN FICHIER JAR AVEC ECLIPSE
Avec l'environnement de développement Eclipse, des assistants permettent de créer un fichier JAR de manière
plus conviviale qu'avec l'utilitaire jar qui fait partie intégrante du SDK (et qui fonctionne en mode ligne de
commandes).
Il existe deux manières (assez différentes) de créer un fichier JAR exécutable :
 Création automatique à partir d'une configuration d'exécution (Runnable JAR File)
 Création avec un assistant permettant de spécifier explicitement le contenu du fichier JAR
Création à partir d'une configuration d'exécution
Il est possible de créer un fichier JAR exécutable à partir d'une configuration d'exécution en passant par le
menu : File  Export  Java  Runnable JAR File.
Une configuration d'exécution est créée par Eclipse lors de l'exécution de l'application (Run). Pour voir la liste
des configurations d'exécution et éditer les informations : Run  Run Configurations...
Dans l'assistant de création du fichier JAR, il suffit de sélectionner la configuration d'exécution de l'application,
de définir la manière de traiter les librairies ainsi que l'emplacement et le nom du fichier JAR. Le fichier JAR qui
sera créé comprendra le fichier Manifest ainsi que l'ensemble des classes et des ressources du projet (avec
prise en compte du Build-Path). Cet assistant n'est donc pas adapté si l'on a plusieurs applications dans un
même projet (il y aura des éléments inutiles le fichier JAR). D'autre part, cet assistant ne permet pas d'inclure
les fichiers sources dans le fichier JAR.
Cette variante permet de déployer facilement une application comprenant des librairies externes (fichiers JAR)
sans avoir à éditer le fichier Manifest. Trois variantes sont proposées : 1) Intégration des librairies sous forme
de classes dans le JAR (extraction), 2) Intégration des librairies sous forme de JARs placés à l'intérieur du JAR
avec ajout des classes utilitaires nécessaires pour leur chargement, 3) Intégration des librairies en les
extrayant dans un sous-répertoire (avec référencement dans le fichier Manifest).
Création à l'aide de l'assistant
Pour lancer cet assistant, il faut passer par le menu : File  Export  Java  JAR File
Il suffit ensuite de sélectionner les ressources qui doivent y être placées, d'indiquer l'emplacement et le nom
du fichier JAR, de créer éventuellement un fichier de description (voir ci-dessous) et de demander de générer
(et év. d'enregistrer) le fichier Manifest en n'oubliant pas d'indiquer la classe principale de l'application (le
point d'entrée du programme, c'est-à-dire la classe contenant la méthode main()).
On peut choisir d'inclure les fichiers sources dans le fichier JAR en cochant la case  Export Java source
files and resources.
Les informations qui servent à générer le fichier JAR peuvent être mémorisées sous forme d'un fichier de type
"JAR Description" qui apparaîtra dans la vue Package Explorer et qui servira à re-générer une nouvelle version
du fichier JAR sans avoir à réutiliser l'assistant à chaque fois.

Eclipse4.5_JAR_Deployment.docx HEIA-FR / Jacques BAPST 3
OÙ PLACER LES RESSOURCES
Il est très fréquent, qu'en plus des fichiers .class, une application fasse appel à différentes ressources
additionnelles (utilisées en lecture par l'application), par exemple des images, des vidéos, des fichiers textes,
des fichiers de propriétés (resource bundle), des sons, etc.
Il y a différentes façons de procéder, mais une manière de faire est de créer avec Eclipse un dossier (avec
éventuellement des sous-dossiers) pour rassembler toutes les ressources additionnelles.
Pour créer un dossier, utiliser le menu : File  New  Folder.
Le dossier contenant les ressources peut être créé dans la branche contenant les fichiers sources ou à
l'extérieur. Les sections qui suivent décrivent les avantages et inconvénients des deux variantes.
Dossier de ressources dans la branche des sources (src)
Si l'on place le dossier de ressources comme sous-dossier de src, les ressources seront automatiquement
copiées (dupliquées) dans la branche bin lors du build du projet (typiquement lors de la compilation).
Par exemple : Project
|
+--- bin
|
+--- src
|
+--- model
|
+--- tools
|
+--- . . .
|
+--- resources (ce dossier se retrouvera également dans bin)
Cette manière de faire simplifie le déploiement des applications car les ressources se retrouvent dans les
dossiers de sortie d'Eclipse (output folders) qui sont automatiquement pris en considération par les outils qui
génèrent les fichiers JAR (dossier intégré dans le classpath).
Les ressources seront placées dans ce dossier, par copier/coller ou glisser/déposer dans le Package Explorer
d'Eclipse. Si l'on place des ressources dans le répertoire associé à ce dossier sans utiliser Eclipse, il est parfois
nécessaire d'activer ensuite l'option Refresh du menu contextuel d'Eclipse sur le dossier concerné pour qu'il
synchronise ses informations avec celles du répertoire.
Dossier de ressources en dehors de la branche des sources
Si l'on a des ressources lourdes et que l'on veut éviter leur duplication (src  bin), il faut placer le dossier des
ressources en dehors de la branche où se trouvent les fichiers sources (src) et de celle contenant les fichiers
compilés (bin).
Par exemple : Project
|
+--- bin
|
+--- src
|
+--- resources
Les ressources seront placées dans ce dossier, par copier/coller ou glisser/déposer dans le Package Explorer
d'Eclipse. Si l'on place des ressources dans le répertoire associé à ce dossier sans utiliser Eclipse, il est parfois
nécessaire d'activer ensuite l'option Refresh du menu contextuel d'Eclipse sur le dossier concerné pour qu'il
synchronise ses informations avec celles du répertoire.
Pour que ce dossier soit pris en compte lorsqu'on lance l'application depuis Eclipse, il faut ajouter son
répertoire parent (le répertoire du projet) au classpath de l'application en modifiant la configuration
d'exécution du programme (à créer si nécessaire).
Pour définir le classpath, passer par le menu Run  Run Configurations... puis, dans l'onglet Classpath,
sélectionner User Entries et cliquer sur le bouton Advanced... puis Add Folders  Ok et sélectionner le
projet parent du dossier créé (et non pas le dossier lui-même !)  Ok et confirmer si nécessaire
l'enregistrement des changements  Yes.
Ce dossier sera également à inclure dans les ressources à placer dans le fichier JAR (à sélectionner en utilisant
l'assistant, voir section précédente).

Eclipse4.5_JAR_Deployment.docx HEIA-FR / Jacques BAPST 4
ADAPTATION DU FICHIER MANIFEST
Si l'on souhaite adapter le fichier Manifest (pour ajouter ou modifier le classpath par exemple), il faut
demander à Eclipse de l'enregistrer dans le Workspace (par défaut, il ne se trouvera que dans le JAR).
Cela se fait durant la dernière étape de l'assistant de création du fichier JAR (décrit précédemment). Il suffit
de cocher la case  Save the manifest in the workspace, de choisir un nom de fichier (par exemple
manifest.mf) et un emplacement dans le Workspace.
Pour que le contenu de ce fichier Manifest soit pris en compte lors de chaque génération du fichier JAR, il faut
également cocher la case  Reuse and save the manifest in the workspace.
Après exécution de l'assistant, le fichier Manifest sera créé à l'emplacement choisi et apparaitra dans le
Package explorer. Ce fichier pourra ensuite être édité par Eclipse (double-clic sur le fichier) et sauvegardé.
Attention, il ne sera pris en compte que lors de la prochaine génération du fichier JAR !
ACCÈS AUX RESSOURCES DANS UN FICHIER JAR
Si l'on place des ressources (images, logos, sons, etc.) dans un fichier JAR, l'extraction de ces ressources
s'effectue en utilisant la méthode getResource() de la classe Class qui renvoie l'URL de la ressource ou en
utilisant la méthode getResourceAsStream() qui renvoie l'InputStream de la ressource ou en utilisant un
constructeur ou une méthode spécifique à la ressource. C'est généralement le Class Loader qui se chargera de
localiser la ressource demandée sur la base du classpath.
Exemple : URL fUrl = getClass().getResource("/resources/Logo.gif");
Image skyImg = new Image("/resources/bluesky.png");
ou, dans une méthode statique :
URL fUrl = MyClass.class.getResource("/resources/Logo.gif");
Cette technique fonctionne si la ressource se trouve
 dans un sous-répertoire qui fait partie d'une des branches du classpath
(c'est-à-dire dont le répertoire parent figure dans le classpath)
 dans le fichier JAR (qui peut également être structuré de manière arborescente,
avec des sous-répertoires, comme tout fichier ZIP).
Si une partie des ressources se trouvent à l'extérieur du fichier JAR, ne pas oublier à mettre à jour le classpath
dans le fichier Manifest en ajoutant la ligne Class-Path: p1 p2 p3 ... (liste des répertoires ou fichiers JAR externes,
séparés par un espace).
Attention : la recherche de ressources dans le JAR est sensible à la casse (minuscules/majuscules).
Un exemple plus complet d'accès aux ressources figure à la fin de ce document.
LANCEMENT DE L'APPLICATION SUR LA MACHINE CIBLE
Une application déployée sous forme de fichier JAR nécessite (comme pour toute application Java) qu'une
machine virtuelle Java ait été préalablement installée sur la machine cible.
Si c'est le cas, le lancement de l'application s'effectuera (cela dépend de l'association de l'extension de fichier
.jar avec le lancement de la machine virtuelle Java) :
 simplement par un double-clic sur le fichier JAR (cas normal)
ou, si ça ne fonctionne pas,
 en ouvrant une fenêtre de commande (Command Prompt) et en lançant la commande :
C:\Temp> java -jar Fichier.jar
ou, si ça ne fonctionne toujours pas,
 en ouvrant une fenêtre de commande (Command Prompt) et en se plaçant dans le répertoire d'installation
de la machine virtuelle (par exemple : C:\Program Files\Java\jre1.8.0_45\bin\) et en lançant la
commande : C:\Program Files\Java\jre1.8.0_45\bin> java -jar Fichier.jar
Remarque : Il est naturellement possible d'adapter la variable d'environnement PATH et/ou de créer un fichier
de commandes permettant de lancer l'application ou de rétablir l'association entre l'extension
.jar et la machine virtuelle Java (...\bin\javaw.exe).

Eclipse4.5_JAR_Deployment.docx HEIA-FR / Jacques BAPST 5
TEST D'UNE APPLICATION DÉPLOYÉE SOUS FORME DE FICHIER JAR
Lorsqu'on lance une application contenue dans un fichier JAR il n'y a pas de console pour afficher les messages
et notamment les messages d'erreur en cas d'exceptions non traitées.
Pour identifier les éventuels problèmes de déploiement lorsqu'une application ne démarre pas ou se termine
abruptement il est utile d'écrire un petit fichier de commande (.bat ou .cmd).
Le plus simple est de créer un fichier texte dans le répertoire où se trouve le fichier JAR.
Ce fichier peut être facilement créé par un clic-droit dans le dossier où se trouve le fichier JAR et en choisissant
l'option Nouveau  Fichier texte. Donner un nom de fichier avec l'extension .cmd ou .bat (et non pas .txt
qui est l'extension par défaut).
Ce fichier contiendra les commandes suivantes (avec le nom de votre fichier JAR).
java -jar Fichier.jar
pause
Un simple double-clic sur ce fichier de commande ouvrira une fenêtre dans laquelle s'afficheront les éventuels
messages destinés à la console (System.out et System.err) et notamment les affichages de la Stack-Trace si
une exception non traitée survient. L'erreur pourra ainsi être identifiée et localisée dans le code (grâce aux
noms de classes/méthodes et aux numéros de lignes).
DÉPLOIEMENT D'UNE APPLICATION SOUS-FORME DE FICHIER EXE
Il est également possible de déployer une application Java en créant un fichier natif exécutable (en réalité, ces
fichiers embarquent la machine virtuelle Java, l'installent automatiquement ou utilisent celle qui est déjà
installée). Différents utilitaires (Java Executable Wrapper) existent pour créer ces fichiers exécutables (.exe),
comme par exemple Launch4J qui est téléchargeable sur SourceForge (launch4j.sourceforge.net).
Il en existe beaucoup d'autres qui sont, soit gratuits (JSmooth, JavaExe, ...), soit payants avec parfois des
versions utilisables avec restrictions ou sur une durée limitée (JExeCreator, Exe4J, ...).
Pour les applications Java et JavaFX, un outil de déploiement nommé javapackager (javapackager.exe) est
disponible dans la branche /bin de la plateforme Java. Cet utilitaire, à lancer en ligne de commandes, offre
de nombreuses possibilités de paramétrage et permet, entre autre, de créer un fichier exécutable qui intègre
la machine virtuelle Java.
La documentation de javapackager est disponible sur
http://docs.oracle.com/javase/8/docs/technotes/tools/windows/javapackager.html
INSTALLEURS
Des installeurs peuvent également être utilisés pour faciliter le déploiement des applications Java.
Parmi les installeurs gratuits, Inno Setup est fréquemment utilisé (www.jrsoftware.org/isinfo.php).