Développons en Java
v 2.40   Copyright (C) 1999-2023 .   
Partie 14 : Les outils pour le développement 97. JavaDoc Imprimer Index Index avec sommaire Télécharger le PDF

 

96. Les outils du J.D.K.

 

chapitre    9 6

 

Niveau : niveau 2 Elémentaire 

 

Le JDK de Sun/Oracle fournit un ensemble d'outils qui permettent de réaliser des applications. Ces outils sont peu ergonomiques car ils s'utilisent en ligne de commandes mais, en contrepartie, ils peuvent toujours être utilisés.

Ce chapitre contient plusieurs sections :

 

96.1. Le compilateur javac

Cet outil est le compilateur : il utilise un fichier source Java fourni en paramètre pour créer un ou plusieurs fichiers contenant le bytecode Java correspondant. Pour chaque fichier source, un fichier portant le même nom avec l'extension .class est créé si la compilation se déroule bien. Il est possible qu'un ou plusieurs autres fichiers .class soient générés lors de la compilation de la classe si celle-ci contient des classes internes. Dans ce cas, le nom du fichier des classes internes est de la forme classe$classe_interne.class. Un fichier .class supplémentaire est créé pour chaque classe interne.

 

96.1.1. La syntaxe de javac

La syntaxe est la suivante :

javac [options] [fichiers] [@fichiers]

Cet outil est disponible depuis le JDK 1.0

La commande attend au moins un nom de fichier contenant du code source Java. Il peut y en avoir plusieurs, en les précisant un par un, séparés par des caractères espace ou en utilisant les jokers du système d'exploitation. Tous les fichiers indiqués doivent obligatoirement posséder l'extension .java qui doit être précisée sur la ligne de commandes.

Exemple : pour compiler le fichier MaClasse.

javac MaClasse.java


Exemple : pour compiler tous les fichiers sources du répertoire

javac *.java

Le nom du fichier doit correspondre au nom de la classe contenue dans le fichier source. Il est obligatoire de respecter la casse du nom de la classe même sur des systèmes qui ne sont pas sensibles à la casse comme Windows.

Depuis le JDK 1.2, il est aussi possible de fournir un ou plusieurs fichiers qui contiennent une liste des fichiers à compiler. Chacun des fichiers à compiler doit être sur une ligne distincte. Sur la ligne de commandes, les fichiers qui contiennent une liste doivent être précédés d'un caractère @

Exemple :

javac @liste

Contenu du fichier liste :
test1.java
test2.java

 

96.1.2. Les options de javac

Les principales options sont :

Option Rôle
-classpath path permet de préciser le chemin de recherche des classes nécessaires à la compilation
-d répertoire les fichiers sont créés dans le répertoire indiqué. Par défaut, les fichiers sont créés dans le même répertoire que leurs sources.
-g génère des informations de débogage
-nowarn le compilateur n'émet aucun message d'avertissement
-O le compilateur procède à quelques optimisations. La taille du fichier généré peut augmenter. Il ne faut pas utiliser cette option avec l'option -g
-verbose le compilateur affiche des informations sur les fichiers sources traités et les classes chargées
-deprecation donne des informations sur les méthodes dépréciées qui sont utilisées

 

96.1.3. Les principales erreurs de compilation

';' expected

Chaque instruction doit se terminer par un caractère ;. Cette erreur indique généralement qu'un caractère ; est manquant.

Exemple de code :
public class Test {
  int i
}

Résultat de la compilation :
javac Test.java
Test.java:3:
  ';' expected
  int i
       ^
1 error

'(' or '[' expected
Exemple de code :
public class Test {
  String[] chaines = new String {"aa","bb","cc"};
}

Résultat de la compilation :
C:\tmp>javac Test.java
Test.java:3:
  '(' or '[' expected
  String[] chaines = new String {"aa","bb","cc"};
                                ^
1 error

Cannot resolve symbol
Exemple de code :
import java.util;
public class Test {
}

Résultat de la compilation :
C:\tmp>javac Test.java
Test.java:1:
  cannot resolve symbol
symbol  : class util
location:
  package java
import java.util;
            ^
1 error

'else' without 'if'
Exemple de code :
public class Test {
  int i = 1;
  public void traitement() {
    if (i==0) {
      i =1;
      else i = 0;
    }
  }
}

Résultat de la compilation :
C:\tmp>javac Test.java
Test.java:8:
  'else' without 'if'
    else i = 0;
    ^
Test.java:11:
  '}' expected
}
 ^
2 errors

'}' expected
Exemple de code :
public class Test {
  int i = 1;
  public void traitement() {
    if (i==0) {
      i =1;
  }
}

Résultat de compilation :
C:\tmp>javac Test.java
Test.java:9: '}' expected
}
 ^
1 error

Variable is already defined

Une variable est définie deux fois dans la même portée.

Exemple de code :
public class Test {
  int i = 1;
  int i = 0;
}

Résultat de la compilation :
C:\tmp>javac Test.java
Test.java:4: i is already defined in Test
  int i = 0;
      ^
1 error

Class is already defined in a single-type import
Exemple de code :
import java.util.List;
import java.awt.List;
public class Test {
  List liste = null;
}

Résultat de la compilation :
C:\tmp>javac Test.java
Test.java:2: java.util.List is already defined in a single-type
  import
import java.awt.List;
^
1 error

Reference to Class is ambiguous
Exemple de code :
import java.util.*;
import java.awt.*;
public
  class Test {
  List liste = null;
}

Résultat de la compilation :
C:\tmp>javac Test.java
Test.java:5:
  reference to List is ambiguous, both class java.awt.List in java.aw
t and
  class java.util.List in java.util match
  List liste = null;
  ^
1 error

Variable might not have been initialized
Exemple de code :
public class Test {
  public void traitement() {
    String chaine;
    System.out.println(chaine);
  }
}

Résultat de la compilation :
C:\tmp>javac Test.java
Test.java:6:
  variable chaine might not have been initialized
    System.out.println(chaine);
                       ^
1 error

Class is abstract; cannot be instantiated

Il n'est pas possible d'instancier une classe abstraite.

Exemple :
public abstract class Test {
  public static void main(String[] argv) {
    Test test = new Test();
  }
}

Résultat de la compilation :
C:\tmp>javac Test.java
Test.java:5:
  Test is abstract; cannot be instantiated
    Test test = new Test();
                ^
1 error

Non-static variable cannot be referenced from a static context
Exemple :
public class Test {
  int i = 0;
  public static void main(String[] argv) {
    System.out.println(i);
  }
}

Résultat de la compilation :
C:\tmp>javac Test.java
Test.java:6:
  non-static variable i cannot be referenced from a
  static context
    System.out.println(i);
                       ^
1 error

Cannot resolve symbol
Exemple :
public class Test {
  public static void main(String[] argv) {
    System.out.println(i);
  }
}

Résultat de la compilation :
C:\tmp>javac Test.java
Test.java:5:
  cannot resolve symbol
symbol  : variable i
location:
  class Test
    System.out.println(i);
                       ^
1 error

Class Classe is public, should be declared in a file named Classe.java
Exemple :
public class Test {
}
public class TestBis {
}

Résultat de la compilation :
C:\tmp>javac Test.java
Test.java:6:
  class TestBis is public, should be declared in a
  file named TestBis
.java
public class TestBis {
       ^
1 error

'class' or 'interface' expected
Exemple :
public Test {
}

Résultat de la compilation :
C:\tmp>javac Test.java
Test.java:2:
  'class' or 'interface' expected
public Test {
       ^
1 error

Méthode is already defined in Test
Exemple :
public class Test {
  public int additionner(int a, int b) {
    return a+b;
  }
  public float additionner(int a, int b) {
    return (float)a+b;
  }
}

Résultat de la compilation :
C:\tmp>javac Test.java
Test.java:8: additionner(int,int) is
  already defined in Test
  public float additionner(int a, int b) {
               ^
1 error

Invalid method declaration; return type required
Exemple :
public class Test {
  public additionner(int a, int b) {
    return a+b;
  }
}

Résultat de la compilation :
C:\tmp>javac Test.java
Test.java:4:
  invalid method declaration; return type required
  public additionner(int a, int b) {
         ^
1 error

Possible loss of precision
Exemple :
public class Test {
  public byte traitement(int a) {
    byte b = a;
    return b;
  }
}

Résultat de la compilation :
C:\tmp>javac Test.java
Test.java:5:
  possible loss of precision
found   : int
required:
  byte
    byte b = a;
             ^
1 error

Missing method body, or declare abstract
Exemple :
public class Test {
  public int additionner(int a, int b); {
    return a+b;
  }
}

Résultat de la compilation :
C:\tmp>javac Test.java
Test.java:4:
  missing method body, or declare abstract
  public int additionner(int a, int b); {
             ^
Test.java:5:
  return outside method
    return a+b;
    ^
2 errors

Operator || cannot be applied to int,int
Exemple :
public class Test {
  int i;
  public void Test(int a, int b, int c , int d) {
    if ( a = b || c = d) {
      System.out.println("test");
    }
  }
}

Résultat de la compilation :
C:\tmp>javac Test.java
Test.java:6:
  incompatible types
found   : int
required: boolean
    if ( a = b || c = d) {
         ^
Test.java:6:
  operator || cannot be applied to int,int
    if ( a = b || c = d) {
               ^
2 errors

Incompatible types
Exemple :
public class Test {
  int i;
  public void Test(int a, int b) {
    if ( a = b ) {
      System.out.println("test");
    }
  }        
}

Résultat de la compilation :
C:\tmp>javac Test.java
Test.java:6:
  incompatible types
found   : int
required: boolean
    if ( a = b ) {
         ^
1 error

Missing return statement
Exemple :
public class Test {
  int a;
  public int traitement(int b) {
    a = b;
  }
}

Résultat de la compilation :
C:\tmp>javac Test.java
Test.java:7:
  missing return statement
  }
  ^
1 error

Modifier private not allowed here
Exemple :
private class Test {
}

Résultat de la compilation :
C:\tmp>javac Test.java
Test.java:2:
  modifier private not allowed here
private class Test {
        ^
1 error

 

96.2. L'interpréteur java/javaw

Ces deux outils sont les interpréteurs de bytecode : ils lancent le JRE, chargent les classes nécessaires et exécutent la méthode main de la classe passée en paramètre.

java ouvre une console pour recevoir les messages de l'application alors que javaw n'en ouvre pas.

 

96.2.1. La syntaxe de l'outil java

java [ options ] classe [ argument ... ]
java [ options ] -jar fichier.jar [ argument ... ]
javaw [ options ] classe [ argument ... ]
javaw [ options ] -jar fichier.jar [ argument ... ]

Le paramètre classe doit être un fichier .class dont il ne faut pas préciser l'extension. La classe contenue dans ce fichier doit obligatoirement contenir une méthode main(). La casse du nom du fichier doit être respectée.

Cet outil est disponible depuis la version 1.0 du JDK.

Exemple:

java MaClasse

Il est possible de fournir des arguments à l'application.

 

96.2.2. Les options de l'outil java

Les principales options sont :

Option Rôle
-jar archive Permet d'exécuter une application contenue dans un fichier .jar. Dans ce cas, le fichier manifest de l'archive doit préciser la classe qui contient la méthode main(). Depuis le JDK 1.2
-Dpropriete=valeur Permet de définir une propriété système sous la forme propriete=valeur. propriété représente le nom de la propriété et valeur représente sa valeur. Il ne doit pas y avoir d'espace entre l'option et la définition ni même dans la définition. Il faut utiliser autant d'option -D que de propriétés à définir. Depuis le JDK 1.1

-classpath chemins

ou -cp chemins

permet d'indiquer les chemins de recherche des classes nécessaires à l'exécution. Chaque répertoire doit être séparé avec un point virgule. Cette option annule l'utilisation de la variable système CLASSPATH
-classic

Permet de préciser que c'est la machine virtuelle classique qui doit être utilisée. Par défaut, c'est la machine virtuelle utilisant la technologie HotSpot qui est utilisée. Depuis le JDK 1.3

-version Affiche des informations sur l'interpréteur
-verbose ou -v Permet d'afficher chaque classe chargée par l'interpréteur
-X Permet de préciser des paramètres particuliers à l'interpréteur. Depuis le JDK 1.2

 

96.3. L'outil jar

JAR est le diminutif de Java ARchive. C'est un format de fichier qui permet de regrouper des fichiers contenant du bytecode Java (fichier .class) ou des données utilisées en tant que ressources (images, son, ...). Ce format est compatible avec le format ZIP : les fichiers contenus dans un jar sont compressés de façon indépendante du système d'exploitation.

Les jar sont utilisables depuis la version 1.1 du JDK.

 

96.3.1. L'intérêt du format jar

Son utilisation est particulièrement pertinente avec les applets, les beans et même les applications. En fait, le format jar est le format de diffusion des composants Java.

Les fichiers jar sont compressés par défaut ce qui est particulièrement intéressant quelque soit leurs utilisations.

Pour une applet, le browser n'effectue plus qu'une requête pour obtenir l'applet et ses ressources au lieu de plusieurs pour obtenir tous les fichiers nécessaires (fichiers .class, images, sons ...).

Un jar peut être signé ce qui permet d'assouplir et d'élargir le modèle de sécurité, notamment celui des applets qui ont des droits restreints par défaut.

Les beans doivent obligatoirement être diffusés sous ce format.

Les applications sous forme de jar peuvent être exécutées automatiquement.

Une archive jar contient un fichier manifest qui permet de préciser le contenu du jar et de fournir des informations sur celui-ci (classe principale, type de composants, signature ...).

 

96.3.2. La syntaxe de l'outil jar

Le JDK fourni l'outil jar pour créer des archives jar. C'est un outil utilisable avec la ligne de commandes comme tous les outils du JDK.

La syntaxe est la suivante :

jar [option [jar [manifest [fichier

Cet outil est disponible depuis la version 1.1 du JDK.

Les options sont :

Option Rôle
c Création d'une nouvelle archive
t Affiche le contenu de l'archive sur la sortie standard
x Extraction du contenu de l'archive
u Mise à jour ou ajout de fichiers à l'archive : à partir de Java 1.2
f Indique que le nom du fichier contenant l'archive est fourni en paramètre
m Indique que le fichier manifest est fourni en paramètre
v Mode verbeux pour avoir des informations complémentaires
0 (zéro) Empêche la compression à la création
M Empêche la création automatique du fichier manifest

Pour fournir des options à l'outil jar, il faut les saisir sans '-' et les accoler les unes aux autres. Leur ordre n'a pas d'importance.

Une restriction importante concerne l'utilisation simultanée du paramètre 'm' et 'f' qui nécessitent respectivement le nom du fichier manifest et le nom du fichier archive en paramètre de la commande. L'ordre de ces deux paramètres doit être identique à l'ordre des paramètres 'm' et 'f' sinon une exception est levée lors de l'exécution de la commande

Exemple :
C:\jm\Java\xagbuilder>jar cmf test.jar manif.mf *.class
java.io.IOException: invalid header field
        at java.util.jar.Attributes.read(Attributes.java:354)
        at java.util.jar.Manifest.read(Manifest.java:161)
        at java.util.jar.Manifest.<init>(Manifest.java:56)
        at sun.tools.jar.Main.run(Main.java:125)
        at sun.tools.jar.Main.main(Main.java:904)

Voici quelques exemples de l'utilisation courante de l'outil jar :

 

96.3.3. La création d'une archive jar

L'option 'c' permet de créer une archive jar. Par défaut, le fichier créé est envoyé sur la sortie standard sauf si l'option 'f' est utilisée. Elle précise que le nom du fichier est fourni en paramètre. Par convention, ce fichier a pour extension .jar.

Si le fichier manifest n'est pas fourni, un fichier est créé par défaut dans l'archive jar dans le répertoire META-INF sous le nom MANIFEST.MF

Exemple ( code Java 1.1 ) : Création d'un jar avec un fichier manifest créé automatiquement contenant tous les fichiers .class du répertoire courant
jar cf test.jar *.class

Il est possible d'ajouter des fichiers contenus dans des sous-répertoires du répertoire courant : dans ce cas, l'arborescence des fichiers est conservée dans l'archive.

Exemple ( code Java 1.1 ) : Création d'un jar avec un fichier manifest fourni contenant tous les fichiers .class du répertoire courant et tous les fichiers du répertoire images
jar cfm test.jar manifest.mf .class images

Exemple ( code Java 1.1 ) : Création d'un jar avec un fichier manifest fourni contenant tous les fichiers .class du répertoire courant et tous les fichiers .gif du répertoire images
jar cfm test.jar manifest.mf *.class images/*.gif

 

96.3.4. Lister le contenu d'une archive jar

L'option 't' permet de donner le contenu d'une archive jar.

Exemple ( code Java 1.1 ) : lister le contenu d'une archive jar
jar tf test.jar

Le séparateur des chemins des fichiers est toujours un slash quelle que soit la plate-forme car le format jar est indépendant de toute plate-forme. Les chemins sont toujours donnés dans un format relatif et non pas absolu : le chemin est donné par rapport au répertoire courant. Il faut en tenir compte lors d'une extraction.

Exemple :
C:\jm\bin\test\java>jar tvf test.jar
  2156 Thu Mar 30 18:10:34 CEST 2000 META-INF/MANIFEST.MF
   678 Thu Mar 23 12:30:00 CET 2000   BDD_confirm$1.class
   678 Thu Mar 23 12:30:00 CET 2000   BDD_confirm$2.class
  4635 Thu Mar 23 12:30:00 CET 2000   BDD_confirm.class
   658 Thu Mar 23 13:18:00 CET 2000   BDD_demande$1.class
   657 Thu Mar 23 13:18:00 CET 2000   BDD_demande$2.class
   662 Thu Mar 23 13:18:00 CET 2000   BDD_demande$3.class
   658 Thu Mar 23 13:18:00 CET 2000   BDD_demande$4.class
  5238 Thu Mar 23 13:18:00 CET 2000   BDD_demande.class
   649 Thu Mar 23 12:31:28 CET 2000   BDD_resultat$1.class
  4138 Thu Mar 23 12:31:28 CET 2000   BDD_resultat.class
   533 Thu Mar 23 13:38:28 CET 2000   Frame1$1.class
   569 Thu Mar 23 13:38:28 CET 2000   Frame1$2.class
   569 Thu Mar 23 13:38:28 CET 2000   Frame1$3.class
  2150 Thu Mar 23 13:38:28 CET 2000   Frame1.class
   919 Thu Mar 23 12:29:56 CET 2000   Test2.class

 

96.3.5. L'extraction du contenu d'une archive jar

L'option 'x' permet d'extraire par défaut tous les fichiers contenus dans l'archive dans le répertoire courant en respectant l'arborescence de l'archive. Pour n'extraire que certains fichiers de l'archive, il suffit de les préciser en tant que paramètres de l'outil jar en les séparant par un espace. Pour une extraction totale ou partielle de l'archive, les fichiers sont extraits en conservant la hiérarchie des répertoires qui les contiennent.

Exemple ( code Java 1.1 ) : Extraire le contenu d'une archive
jar xf test.jar

Exemple ( code Java 1.1 ) : Extraire les fichiers test1.class et test2.class d'une archive
jar xf test.jar test1.class test2.class

stop Attention : lors de l'extraction, l'outil jar écrase tous les fichiers existants sans demander de confirmation.

 

96.3.6. L'utilisation des archives jar

Dans une page HTML, pour utiliser une applet fournie sous forme de jar, il faut utiliser l'option archive du tag applet. Cette option attend en paramètre le fichier jar et son chemin relatif au répertoire contenant le fichier HTML.

Exemple : le fichier HTML et le fichier MonApplet.jar sont dans le même répertoire
<applet code=>em<MonApplet.class>/em<
        archive=">em<MonApplet.jar>/em<"
        width=>em<300>/em< height=>em<200>/em<>
</applet>

Avec Java 1.1, l'exécution d'une application sous forme de jar se fait grâce au JRE. Il faut fournir dans ce cas le nom du fichier jar et le nom de la classe principale.

Exemple :
jre -cp MonApplication.jar ClassePrincipale

Avec Java 1.2, l'exécution d'une application sous forme de jar impose de définir la classe principale (celle qui contient la méthode main) dans l'option Main-Class du fichier manifest. A cette condition l'option -jar de la commande java permet d'exécuter l'application.

Exemple (Java 1.2) :
java -jar MonApplication.jar

 

96.3.7. Le fichier manifest

Le fichier manifest contient de nombreuses informations sur l'archive et son contenu. Ce fichier est le support de toutes les fonctionnalités particulières qui peuvent être mises en oeuvre avec une archive jar.

Dans une archive jar, il ne peut y avoir qu'un seul fichier manifest nommé MANIFEST dans le répertoire META-INF de l'archive.

Le format de ce fichier est de la forme clé/valeur. Il faut mettre un ':' et un espace entre la clé et la valeur.

Exemple :
C:\jm\bin\test\java>jar xf test.jar META-INF/MANIFEST.MF

Cela crée un répertoire META-INF dans le répertoire courant contenant le fichier MANIFEST.MF :

Exemple :
Manifest-Version: 1.0
Name: BDD_confirm$1.class
Digest-Algorithms: SHA MD5
SHA-Digest: ntbIs5E5YNilE4mf570JoIF9akU=
MD5-Digest: R3zH0+m9lTFq+BlQvfQdHA==
Name: BDD_confirm$2.class
Digest-Algorithms: SHA MD5 
SHA-Digest: 3QEF8/zmiTAP7MHFPU5wZyg9uxc=
MD5-Digest: swBXXptrLLwPMw/bpt6F0Q==
Name: BDD_confirm.class
Digest-Algorithms: SHA MD5
SHA-Digest: pZBT/o8YeDG4q+XrHRgrB08k4HY=
MD5-Digest: VFvY4sGRfjV1ciM9C+QIdg==

Dans le fichier manifest créé automatiquement avec le JDK 1.1, chaque fichier possède au moins une entrée de type 'Name' et des informations la concernant.

Entre les données de deux fichiers, il y a une ligne blanche.

Dans le fichier manifest créé automatiquement avec le JDK 1.2, il n'y a plus d'entrée pour chaque fichier.

Exemple :
Manifest-Version: 1.0
Created-By: 1.3.0 (Sun Microsystems Inc.)

Le fichier manifest généré automatiquement convient parfaitement si l'archive est utilisée uniquement pour regrouper les fichiers. Pour une utilisation plus spécifique, il faut modifier ce fichier pour ajouter les informations utiles.

Par exemple, pour une application exécutable (à partir de Java 1.2) il faut ajouter une clé Main-Class en lui associant le nom de la classe dans l'archive qui contient la méthode main.

 

96.3.8. La signature d'une archive jar

La signature d'une archive jar joue un rôle important dans les processus de sécurité de Java. La signature d'une archive permet à celui qui utilise cette archive de lui donner des droits étendus une fois que la signature a été reconnue.

Avec Java 1.1 une archive signée possède tous les droits.

Avec Java 1.2 une archive signée peut se voir attribuer des droits particuliers définis dans un fichier policy.

 

96.4. L'outil appletviewer pour tester des applets

L'intérêt de cet outil est qu'il permet de tester une applet avec la version courante du JDK. Un navigateur classique nécessite un plug-in pour utiliser une version particulière du JRE. Cet outil est disponible depuis la version 1.0 du JDK.

En contrepartie, l'appletviewer n'est pas prévu pour tester les pages HTML. Il charge une page HTML fournie en paramètre, l'analyse, charge l'applet qu'elle contient et exécute cette applet.

La syntaxe est la suivante : appletviewer [option] fichier

L'appletview recherche le tag HTML <APPLET>. A partir du JDK 1.2, il recherche aussi les tags HTML <EMBED> et <OBJECT>.

Il possède plusieurs options dont les principales sont :

Option Rôle
-J Permet de passer un paramètre à la JVM. Pour passer plusieurs paramètres, il faut utiliser plusieurs options -J. Depuis le JDK 1.1
-encoding Permet de préciser le jeu de caractères de la page HTML

L'appletviewer ouvre une fenêtre qui possède un menu avec les options suivantes :

Option de menu Rôle
Restart Permet d'arrêter et de redémarrer l'applet
Reload Permet d'arrêter et de recharger l'applet
Stop Permet d'arrêter l'exécution de l'applet. Depuis le JDK 1.1
Save Permet de sauvegarder l'applet en la sérialisant dans un fichier applet.ser. Il est nécessaire d'arrêter l'applet avant d'utiliser cet option. Depuis le JDK 1.1
Start Permet de démarrer l'applet. Depuis le JDK 1.1
Info Permet d'afficher les informations de l'applet dans une boîte de dialogue. Ces informations sont obtenues par les méthodes getAppletInfo() et getParameterInfo() de l'applet.
Print Permet d'imprimer l'applet. Depuis le JDK 1.1
Close Permet de fermer la fenêtre courante
Quit Permet de fermer toutes les fenêtres ouvertes par l'appletviewer

 

96.5. L'outil javadoc pour générer la documentation technique

Cet outil permet de générer une documentation à partir des données insérées dans le code source. Cet outil est disponible depuis le JDK 1.0

La syntaxe de la commande est la suivante :

javadoc  [  options ] [ nom_packages ] [ fichiers_source ] [ -sous_packages   pkg1:pkg2:...  ] [  @fichiers_arguments ]

L'ordre des arguments n'a pas d'importance :

Il faut fournir en paramètres de l'outil javadoc un nom de package ou un ensemble de fichiers sources Java.

Les principales options utilisables sont :

Option

Rôle

-classpath chemin

Classpath dans lequel l'outil va rechercher les fichiers sources et .class

Cette option permet de remplacer le classpath standard par celui fourni.

-encoding name

Précise le jeu de caractères utilisés dans les fichiers sources

-J flag

Permet de passer un argument à la JVM dans laquelle s'exécute l'outil javadoc

Exemple : -J-Xmx32m -J-Xms32m

-sourcepath chemins

Chemins dans lequel l'outil va rechercher les fichiers sources à documenter. Plusieurs chemins peuvent être précisés en utilisant le caractère ; comme séparateur. Par défaut, si ce paramètre n'est pas précisé, c'est le classpath qui est utilisé.

-verbose

Affiche des informations sur la génération en cours

-help

Affiche un résumé des options de la commande

-doclet classe

Permet de préciser un doclet personnalisé (la classe fournie en paramètre doit être pleinement qualifiée).

-docletpath

Permet de préciser le chemin du doclet personnalisé

-exclude packages

Permet de préciser une liste de packages qui ne seront pas pris en compte par l'outil. Le caractère : est utilisé comme séparateur entre chaque package

-package

Inclut seulement les membres et classes package-private, protected et public

-private

Inclut tous les membres et classes

-protected

Inclut seulement les membres et classes protected et public

-public

Inclut seulement les membres et classes public

-overview fichier

Utilise le fichier précisé comme fichier overview-summary.html dans la documentation générée

-source version

Permet de préciser la version de Java utilisée par le code source. Les valeurs possibles sont 1.3, 1.4 et 1.5. Par défaut, c'est la version du JDK qui est utilisée

-subpackages packages

Permet de préciser les packages qui seront pris en compte. Le caractère : est utilisé comme séparateur entre chaque package


L'outil javadoc utilise un doclet pour réaliser le rendu de la documentation générée : il utilise un doclet par défaut si aucun autre doclet n'est spécifié avec l'option -doclet.

Les principales options utilisables du doclet standard sont :

Option

Rôle

-author

Permet de demander la prise en compte des tags @author dans la documentation générée

-bottom

Permet d'insérer du code HTML dans le pied de chaque page

-charset nom

Permet de préciser le jeu de caractères des fichiers HTML générés

-d repertoire

Précise le répertoire dans lequel la documentation va être générée. Par défaut, c'est le répertoire courant qui est utilisé

-docencoding nom

Précise le jeu de caractères utilisés dans les fichiers générés

-doctitle titre

Permet de préciser le titre de la page index (il est possible d'utiliser du code HTML : dans ce cas entourer le titre avec des caractères " ...")

-footer

Permet d'insérer du code HTML à droite du footer par défaut

-help fichier

Permet d'utiliser un fichier d'aide personnalisé. Le fichier doit être au format HTML

-header

Permet d'insérer du code HTML à droite du header par défaut

-link url

Permet de générer des liens vers une documentation (par exemple celle du JDK). L'url peut être relative ou absolue.

Exemple : -link http://java.sun.com/j2se/1.5.0/docs/api

-linksource

Permet d'inclure dans la documentation le code source au format HTML avec une numérotation des lignes

-nodecprecatedlist

Permet de ne pas générer le fichier deprecated-list.html

-nodeprecated

Permet de ne pas intégrer les tags @deprecated dans la documentation

-nohelp

Permet de ne pas générer le lien "Help"

-noindex

Permet de ne pas générer la page index des packages

-nonavbar

Permet de ne pas générer la barre de navigation

-nosince

Permet de ne pas intégrer les tags @since dans la documentation

-notree

Permet de ne pas générer la hiérarchie des classes

-splitindex

Permet de générer l'index sous la forme d'un fichier par lettre

-stylesheetfile fichier

Permet de préciser la feuille de style utilisée dans la documentation

-use

Permet de demander la génération des pages d'utilisation des classes et packages

-version

Permet de demander la prise en compte des tags @version dans la documentation générée

-windowtitle titre

Permet de préciser le titre des pages


Il est possible de préciser les paramètres de l'outil javadoc (sauf l'option -J) dans un ou plusieurs fichiers en passant leurs noms précédés des caractères @. Dans un tel fichier les paramètres peuvent être séparés par un espace ou un retour chariot.

Il n'est pas possible d'utiliser le caractère joker * dans les noms de fichiers ni de faire une référence à un autre fichier de paramètres avec le caractère @.

Exemple :

C:>javadoc @javadocparam

Exemple : le fichier javadocparam
-d documentation -use -splitindex

Remarque : l'outil javadoc ne sait pas travailler de façon incrémentale : toute la documentation est à regénérer à chaque fois.

Des informations supplémentaires sur les éléments à inclure dans le code source sont fournies dans le chapitre «JavaDoc».

 

96.6. L'outil Java Check Update pour mettre à jour Java

Jucheck (Java Update Check) est un outil proposé pour permettre une mise à jour automatique de l'environnement d'exécution Java.

L'outil jusched.exe est installé par défaut et configuré pour une exécution automatique depuis la version 1.4.2 du J2SE.

Pour lancer manuellement la mise à jour, il suffit d'exécuter le programme jucheck.exe dans le répertoire bin du JRE.

Si aucune mise à jour n'est disponible, un message est affiché :

Sinon une bulle d'aide informe que des mises à jour peuvent être téléchargées.

En laissant le curseur de la souris sur l'icône du programme de mise à jour, une bulle d'aide est affichée.

Pour télécharger les mises à jour, il suffit d'utiliser l'option " Télécharger " du menu contextuel associé à l'icône.

Une boîte de dialogue permet de demander le téléchargement des éléments dont la version est indiquée.

Cliquez sur le bouton " Téléchargement ".

Une fois le téléchargement terminé, une bulle est affichée.

En laissant le curseur de la souris sur l'icône du programme de mise à jour, une bulle d'aide est affichée.

Pour installer les mises à jour, il suffit d'utiliser l'option " Installer " du menu contextuel associé à l'icône.

Cliquez sur le bouton " Installer ".

L'assistant se lance pour diriger les différentes étapes.

L'option " Propriétés " permet d'ouvrir une boîte de dialogue pour gérer les paramètres des mises à jour dans l'onglet " Mettre à jour ".

Le bouton " Avancé " permet de définir les paramètres de recherche automatique.

 

96.7. La base de données Java DB

Java SE 6 intègre une base de données : Java DB. C'est en fait la base de données open source Apache Derby écrite entièrement en Java. C'est une base de données légère (2 Mb) qui propose cependant des fonctionnalités intéressantes (gestion des transactions et des accès concurrents, support des triggers et des procédures stockées, ...)

Java DB est donc le nom sous lequel Sun/Oracle propose la base de données open source Derby du groupe Apache dans certains de ses outils notamment le JDK depuis sa version 6.0.

stop

Attention : à partir des version 9 et 8u181, Java DB n'est plus fourni dans le JDK.


Java DB est stockée dans le sous-répertoire db du répertoire d'installation d'un JDK. Avec le JDK 6.0 c'est la version 10.2 de Java DB qui est fournie.

Remarque : dans cette section Java DB peut être remplacée par Derby et vice versa.

L'ajout de Java DB dans le JDK permet de rapidement écrire des applications qui utilisent une base de données et les fonctionnalités proposées par la version 4.0 de JDBC.

Java DB est idéale dans un environnement de développement car elle est riche en fonctionnalités, facile à utiliser, multiplate-forme puisqu'écrite en Java et peut être mise en oeuvre sur une simple machine de développement.

Java DB peut fonctionner selon deux modes :

Java DB peut être intégrée dans une application (mode Embedded) ce qui évite d'avoir à installer et configurer une base de données lors du déploiement de l'application.

Java DB propose plusieurs outils pour assurer sa gestion.

L'outil ij permet d'exécuter des scripts sur une base de données.

Le lancement de l'outil ij peut se faire de deux façons :

Exemple :
C:\Program Files\Java\jdk1.6.0\db>java -jar lib\derbyrun.jar ij
version ij 10.2
ij>

ou

Exemple :
C:\Program Files\Java\jdk1.6.0\db>java -cp .\lib\derbytools.jar org.apache.derby
.tools.ij
ij version 10.2
ij>

La création d'une base de données nommée MaBaseDeTest et la connexion à cette nouvelle base se font en utilisant l'outil ij.

Exemple :
ij> CONNECT 'jdbc:derby:MaBaseDeTest;create=true';

Remarque : l'outil ij peut être utilisé avec n'importe quel pilote JDBC.

Exemple : Création de la table Personne
ij> CREATE TABLE PERSONNE (ID INT PRIMARY KEY, NOM VARCHAR(50), PRENOM VARCHAR(5
0));
0 lignes insérés/mises à jour/supprimées

ij> select * from PERSONNE;
ID         |NOM                                               |PRENOM

--------------------------------------------------------------------------------
---------------------------------

0 lignes sélectionnées

Exemple : Ajout d'occurrences dans la table Personne
ij> INSERT INTO PERSONNE VALUES (1,'nom1','prenom1'), (2,'nom2','prenom2'), (3,'
nom3','prenom3');
3 lignes insérées/mises à jour/supprimées
ij> select * from PERSONNE;
ID         |NOM                                               |PRENOM

--------------------------------------------------------------------------------
---------------------------------
1          |nom1                                              |prenom1

2          |nom2                                              |prenom2

3          |nom3                                              |prenom3


3 lignes sélectionnées

La commande exit; permet de quitter l'outil ij.

Une fois la base de données créée, il est possible d'utiliser par exemple l'API JDBC pour s'y connecter et effectuer des opérations sur ses données.

Exemple : utilisation de Java DB en mode embedded
package fr.jmdoudoux.dej.jpa;

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.Statement;

public class TestDerby {

  private static String dbURL = 
    "jdbc:derby:C:/Program Files/Java/jdk1.6.0/db/MaBaseDeTest;user=APP";

  public static void main(String[] args) {

    try {
      Connection conn = null;
      Statement stmt = null;
      
      Class.forName("org.apache.derby.jdbc.EmbeddedDriver").newInstance();
      conn = DriverManager.getConnection(dbURL);

      stmt = conn.createStatement();
      ResultSet results = stmt.executeQuery("select * from personne");
      ResultSetMetaData rsmd = results.getMetaData();
      int nbColonnes = rsmd.getColumnCount();
      for (int i = 1; i <= nbColonnes; i++) {
        System.out.print(rsmd.getColumnLabel(i) + "\t\t");
      }

      System.out.println("\n-------------------------------------------------");

      while (results.next()) {
        System.out.println(results.getInt(1) + "\t\t" 
          + results.getString(2) + "\t\t" + results.getString(3));
      }
      results.close();
      stmt.close();
      if (conn != null) {
        conn.close();
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }

}

Remarque : par défaut dans le mode embeded, les tables sont créées dans le schéma APP.

Pour utiliser Java DB en mode client/serveur, il suffit de remplacer le pilote JDBC par org.apache.derby.jdbc.ClientDriver et de changer dans l'url le chemin local pour l'url de la base de données.

L'outil dblook permet de générer le DDL d'une base de données.

Exemple :
C:\Program Files\Java\jdk1.6.0\db>java -jar lib\derbyrun.jar dblook -d jdbc:derb
y:MaBaseDeTest
-- Horodatage : 2007-06-28 15:42:21.613
-- La base de données source est : MaBaseDeTest
-- L'URL de connexion est : jdbc:derby:MaBaseDeTest
-- appendLogs: false

-- ----------------------------------------------
-- Instructions DDL pour tables
-- ----------------------------------------------

CREATE TABLE "APP"."ADRESSE" ("ID_ADRESSE" INTEGER NOT NULL, "RUE" VARCHAR(250)
NOT NULL, "CODEPOSTAL" VARCHAR(7) NOT NULL, "VILLE" VARCHAR(250) NOT NULL);

CREATE TABLE "APP"."PERSONNE" ("ID" INTEGER NOT NULL, "NOM" VARCHAR(50), "PRENOM
" VARCHAR(50));

-- ----------------------------------------------
-- Instructions DDL pour clés
-- ----------------------------------------------

-- primaire/unique
ALTER TABLE "APP"."ADRESSE" ADD CONSTRAINT "SQL070628114148710" PRIMARY KEY ("ID
_ADRESSE");

ALTER TABLE "APP"."PERSONNE" ADD CONSTRAINT "SQL070627114331220" PRIMARY KEY ("I
D");

L'outil sysinfo permet d'obtenir des informations sur l'environnement et sur la base de données.

Exemple :
C:\Program Files\Java\jdk1.6.0\db>java -cp .\lib\derbytools.jar org.apache.derby
.tools.ij
ij version 10.2
ij> exit;

C:\Program Files\Java\jdk1.6.0\db>java -jar lib\derbyrun.jar sysinfo
------------------ Informations Java  ------------------
Version Java :    1.6.0_01
Fournisseur Java :     Sun Microsystems Inc.
Répertoire principal Java :       C:\Program Files\Java\jre1.6.0_01
Chemin de classes Java :  lib\derbyrun.jar
Nom du système d'exploitation :         Windows XP
Architecture du système d'exploitation :         x86
Version du système d'exploitation :         5.1
Nom d'utilisateur Java :  JMD
Répertoire principal utilisateur Java :  C:\Documents and Settings\jmd
Répertoire utilisateur Java :   C:\Program Files\Java\jdk1.6.0\db
java.specification.name: Java Platform API Specification
java.specification.version: 1.6
--------- Informations Derby --------
JRE - JDBC: Java SE 6 - JDBC 4.0
[C:\Program Files\Java\jdk1.6.0\db\lib\derby.jar] 10.2.1.7 - (453926)
[C:\Program Files\Java\jdk1.6.0\db\lib\derbytools.jar] 10.2.1.7 - (453926)
[C:\Program Files\Java\jdk1.6.0\db\lib\derbynet.jar] 10.2.1.7 - (453926)
[C:\Program Files\Java\jdk1.6.0\db\lib\derbyclient.jar] 10.2.1.7 - (453926)
------------------------------------------------------
----------------- Informations sur lenvironnement local -----------------
Environnement local actuel :  [français/Luxembourg [fr_LU]]
La prise en charge de cet environnement local a été trouvée : [de_DE]
         version : 10.2.1.7 - (453926)
La prise en charge de cet environnement local a été trouvée : [es]
         version : 10.2.1.7 - (453926)
La prise en charge de cet environnement local a été trouvée : [fr]
         version : 10.2.1.7 - (453926)
La prise en charge de cet environnement local a été trouvée : [it]
         version : 10.2.1.7 - (453926)
La prise en charge de cet environnement local a été trouvée : [pt_BR]
         version : 10.2.1.7 - (453926)
------------------------------------------------------

Pour démarrer JavaDB en mode client-server, il faut exécuter l'application org.apache.derby.drda.NetworkServerControl.

Exemple :
C:\Program Files\Java\jdk1.6.0\db>java -cp .\lib\derbyrun.jar org.apache.derby.d
rda.NetworkServerControl start -h localhost
Le serveur est prêt à accepter les connexions au port 1527.

L'option -h permet de préciser le serveur.
L'option - p permet de préciser le port à utiliser si le port 1527 utilisé par défaut ne convient pas.

 

96.8. L'outil JConsole

Depuis Java SE 5.0, le JDK propose l'outil JConsole qui est une interface de monitoring et de management utilisant JMX. JConsole est une application graphique qui est un client JMX permettant de mettre en oeuvre la plupart des fonctionnalités de JMX.

JConsole est dans le sous-répertoire bin du répertoire d'installation du JDK.

Remarque : Il n'est pas recommandé d'utiliser JConsole en production car son utilisation consomme beaucoup de ressources. Si son utilisation est nécessaire, il est recommandé d'exécuter JConsole sur un système distant de celui de la JVM à surveiller.

Pour utiliser JConsole , il suffit d'exécuter jconsole dans une nouvelle boîte de commande.

Remarque : sous Windows, JMX ne fonctionne correctement que si la partition du système est formatée en NTFS.

Une fenêtre de connexion permet de préciser quel sera le processus d'une JVM à utiliser. Pour une JVM locale, il suffit de sélectionner « Local Process », la JVM parmi celles proposées, et de cliquer sur « Connect ».

Pour une connexion distante, il faut saisir l'url de connexion et éventuellement le user et le mot de passe si l'authentification est activée. Une fois la connexion établie, une fenêtre contenant plusieurs onglets permet d'avoir des informations sur l'état de différentes fonctionnalités.

L'onglet « Overview » fournit un résumé graphique sur quatre données : l'usage du tas (heap) et du processeur (CPU), le nombre de threads et de classes chargées.

L'onglet « Memory » permet d'avoir des informations précises sur la mémoire.

Le contenu du graphique principal et des détails peuvent être sélectionnés dans la liste déroulante chart : Heap Memory Usage, Non-Heap Memory Usage, Eden Space, Survivor Space, Tenured Space, Code Cache, Perm Gen, Perm Gen shared-rw et Perm Gen shared-ro. Ceci permet d'avoir une vue précise sur chaque partie de la mémoire de la JVM.

Le bouton « Perform GC » permet de demander l'exécution du ramasse-miettes.

L'onglet « Threads » permet d'avoir des informations sur les threads en cours d'exécution.

Pour avoir des informations précises sur un thread, il suffit de le sélectionner.

L'onglet « Classes » permet de connaître le nombre de classes chargées.

l'onglet classe

L'onglet « VM Summary » affiche de nombreuses informations sur l'état de la JVM. Celles-ci sont rafraîchies toutes les 5 secondes.

l'onglet VM Summary

L'onglet « MBean » permet de gérer les MBeans de l'API JMX qui sont accessibles dans la JVM.

 


Partie 14 : Les outils pour le développement 97. JavaDoc Imprimer Index Index avec sommaire Télécharger le PDF    
Développons en Java
v 2.40   Copyright (C) 1999-2023 .