...::: JLogger :: Manuel :::...

Installation

L'installation de JLogger est très simple. Il vous faut d'abord une plate-forme java version 1.4 ou supérieure. En fait, seul l'outil de configuration automatique utilise les APIs de la version 1.4, à savoir org.w3c.dom et les librairies XML. Il est possible d'obtenir ces APIs dans un fichier jar "indépendant", comme le fournit l'outil ant (dans le fichier nommé xml-apis.jar), et, dans ce cas, JLogger ne nécessite qu'une version 1.2 (c'est à dire swing) de java. Vous trouverez tout les jdk sur le site de sun.

Un fois votre jdk installé et votre archive JLogger decompressées (à télécharger ici), il vous faut suffit de placer le fichier JLogger.jar dans votre classpath.

Sous un UNIX (bash):
         export CLASSPATH=${CLASSPATH}:/usr/bin/java/jlogger/JLogger.jar
Sous un UNIX (csh):
         setenv CLASSPATH /usr/bin/java/jlogger/lib/JLogger.jar:.:${CLASSPATH}
Sous Windows:
         set CLASSPATH=C:\java\jlogger\lib\JLogger.jar;.;%CLASSPATH%

Voila, vous êtes prêt à utiliser JLogger.

Première utilisation

JLogger est correctement installé, et vous êtes maintenant prêt à découvrir son fonctionnement.

01: import net.directj.jlogger.*;
02:
03: public class JLoggerSample {
04:
05:     public static void main(String[] _args) {
06:
07:         JLogger logger = JLoggerFactory.getLogger(JLoggerSample.class.getName());
08:         LogManager manager = new ConsoleLogManager(JLogger.ALL);
09:         logger.addLogManager(manager);
10:
11:         logger.debug("debug");
12:         logger.info("info");
13:         logger.warning("warning");
14:         logger.error("error");
13:         logger.fatal("fatal");
14:         logger.debug("debug", new Exception("debug"));
15:         logger.info("info", new Exception("info"));
16:         logger.warning("warning", new Exception("warning"));
17:         logger.error("error", new Exception("error"));
18:         logger.fatal("fatal", new Exception("fatal"));
19:     }
20: }

Compilez et exécutez ce code. Vous obtiendrez sur la sortie standard les traces suivantes:

[JLoggerSample] DEBUG - debug #2 janv. 2003 15:42:10
[JLoggerSample] INFO - info #2 janv. 2003 15:42:10
[JLoggerSample] WARNING - warning #2 janv. 2003 15:42:10
[JLoggerSample] ERROR - error #2 janv. 2003 15:42:10
[JLoggerSample] FATAL - fatal #2 janv. 2003 15:42:10
[JLoggerSample] DEBUG - debug #2 janv. 2003 15:42:10
[JLoggerSample] DEBUG - a java.lang.Exception has been catched because: debug #2 janv. 2003 15:42:10
[JLoggerSample] DEBUG - exception from JLoggerSample.main at JLoggerSample.java:16 #2 janv. 2003 15:42:10
[JLoggerSample] INFO - info #2 janv. 2003 15:42:10
[JLoggerSample] INFO - a java.lang.Exception has been catched because: info #2 janv. 2003 15:42:10
[JLoggerSample] INFO - exception from JLoggerSample.main at JLoggerSample.java:17 #2 janv. 2003 15:42:10
[JLoggerSample] WARNING - warning #2 janv. 2003 15:42:11
[JLoggerSample] WARNING - a java.lang.Exception has been catched because: warning #2 janv. 2003 15:42:11
[JLoggerSample] WARNING - exception from JLoggerSample.main at JLoggerSample.java:18 #2 janv. 2003 15:42:11
[JLoggerSample] ERROR - error #2 janv. 2003 15:42:11
[JLoggerSample] ERROR - a java.lang.Exception has been catched because: error #2 janv. 2003 15:42:11
[JLoggerSample] ERROR - exception from JLoggerSample.main at JLoggerSample.java:19 #2 janv. 2003 15:42:11
[JLoggerSample] FATAL - fatal #2 janv. 2003 15:42:11
[JLoggerSample] FATAL - a java.lang.Exception has been catched because: fatal #2 janv. 2003 15:42:11
[JLoggerSample] FATAL - exception from JLoggerSample.main at JLoggerSample.java:20 #2 janv. 2003 15:42:11

La première étape est donc de créer un logger, ici à la ligne 7. Pour cela, vous devez demander à JLoggerFactory de vous le fournir, en précisant son nom. Nous avons utilisé le nom de la classe, mais n'importe quelle chaîne de caractère fera aussi bien l'affaire. Cette fonction (JLoggerFactory.getLogger()) retourne une référence sur le logger. Une fois ceci fait, vous devez spécifier une sortie pour votre logger (ligne 8 et 9). Vous créez donc un LogManager, qui est l'objet en charge du format et de la sortie. Il en existe différends types (Console, fichier, base de données voire réseau), et vous pouvez en spécifier plusieurs, mais le plus simple ici est encore ConsoleLogManager. Pour créer votre LogManager, vous devez donc au moins spécifier le niveau de sortie.

Le niveau de sortie correspond à une manière de trier les informations pertinentes des autres. En fait, chaque trace possède un niveau de sortie, qui dépend de la fonction appelée pour créer la trace. Ainsi, un appel a JLogger.info() créera une trace avec le niveau INFO. Si le niveau de la sortie est inférieur ou égal au niveau de l'information, alors l'information est imprimée. Par exemple, si votre sortie possède le niveau WARNING, seul les traces de niveau WARNING, ERROR ou FATAL seront imprimées, alors que les traces de niveau DEBUG ou INFO ne le seront pas. Il y en fait 5 niveaux dans JLogger, DEBUG < INFO < WARNING < ERROR < FATAL, plus deux niveaux dédiés aux sorties, ALL et OFF; le premier active l'ensemble l'impression de toutes les traces, alors que le second les desactive. L'un des gros avantages de cette méthode est que vous pouvez avoir plusieurs sortie, avec chacune un niveau différent. Par exemple, vous pouvez rediriger vers la console la totalité de vos traces et ne redirigez vers un fichier que les erreurs.

Concepts de base

JLoggerFactory:

JLoggerFactory sert à créer et obtenir un logger, en utilisant la méthode statique getLogger(String _name). Si le logger de nom '_name' existe déjà, alors la méthode renvoie une référence sur ce logger. Sinon, un nouveau logger de nom '_name' est créé et retourné. Vous pouvez ainsi créer un logger particulier, puis l'utiliser depuis n'importe quelle classe ou package en utilisant la méthode getLogger("nom_du_logger");. En fait, le logger est stocké par la JLoggerFactory, ce qui permet de centraliser les informations, mais aussi d'éviter de 'trimbaler' des références a ce logger dans toutes les classes où vous avez l'intention de l'utiliser, et d'éviter ainsi une surcharge inutile de votre code. De plus, JLoggerFactory est une classe totalement indépendante, qui se configure toute seule en utilisant un fichier XML. Nous verrons plus tard comment configurer par vous-même JLogger.

JLogger:

Le JLogger est la classe la plus importante du package. C'est celle que vous utiliserez pour créer vos traces. Il y a dans JLogger 7 méthodes pour écrire vos traces, mais seulement 5 sont essentielles. Elles correspondent en fait aux 5 niveaux de traces possibles: debug(), info(), warning(), error() et fatal(). Pour chacune d'elle, vous devez spécifier le message correspondant à la trace, sous forme de chaîne de caractère. Vous pouvez éventuellement rajouter un deuxième paramètre, de type exception (voir les lignes 16 à 20 de l'exemple). Les deux autres méthodes ne sont pas sensées être utilisées, mais elles sont néanmoins accessibles. Il s'agit de log(int _type, java.lang.String _msg) qui imprime un message (vous devez spécifier le niveau du message et le message), ainsi que de exception(int _lvl, java.lang.Throwable _excp) qui permet de gérer les exceptions (vous devez spécifier, ici aussi, le niveau de la trace, ainsi que l'exception). Ces deux méthodes sont à proscrire, a moins d'être sur de ce que vous faites, d'autant plus qu'il est prévu, dans un futur proche, de modifier les niveaux de trace qui seront implémentés sous forme d'objet et non plus d'entier; votre code, s'il utilise log ou exception, ne sera alors plus valide.

LogManager:

Les LogManager sont en charge du formatage et de l'impression des traces. Ce sont eux qui définissent si une information doit être imprimée ou non, qui formatent cette information en fonction du formateur qu'ils contiennent, et qui l'impriment ensuite sur leur sortie de référence. Il en existe différends, que vous utiliserez en fonction de vos besoins. Chacun correspond en fait à un Output et un Formater. Ainsi, XmlFormater écrit dans un fichier les traces au format Xml, FileLogManager écrit dans un fichier, mais en utilisant un format standard, JDBCLogManager lui écrit les informations dans une base de données. Pour mieux connaître les différends LogManager et ainsi utiliser ceux qui correspondent à vos besoins, le mieux est encore de les étudier par vous-même en utilisant la documentation Javadoc.

Chacun des LogManager possède un certain nombre de paramètre à spécifier lors de leur création, mais quelques-uns uns possède un paramètre spécial : le Pattern. Un pattern est un "format", qui vous permet de spécifier par vous-même et directement le format de la sortie. Cela ne marche pas pour les formats "spéciaux" comme Xml ou Html. En revanche, cela peut être important en ce qui concerne les LogManager normaux comme ConsoleLogManager ou FileLogManager. Pour spécifier un pattern, il vous suffit de passer en paramètre un objet String, répondant à certains critères. Par exemple, le pattern par défaut est "[$name] $type - $message #$time". $name sera remplacé par le nom du logger, $type par le niveau de trace, $message par le message lui-même et $time par la date et l'heure de publication de l'information. Ainsi, le pattern fournira en sortie les traces de l'exemple 2. A vous d'utiliser ces paramètres en fonction de vos besoins. Vous pouvez ainsi supprimer la date et l'heure si elles ne vous paraissent pas pertinentes. Vous pouvez même ne spécifier aucun des quatre éléments (même si ce n'est pas très utiles). Attention, les patterns sont susceptibles d'être modifiés, mais nous tenteront d'assurer une compatibilité avec ce format.

Concepts avancés

Configuration automatique par XML:

JLogger peut être configuré automatiquement par un document xml. Ainsi, vous n'avez même plus besoin de modifier votre code pour décider de ce que doit être imprimé et ou. Ce document doit suivre une dtd spécifique, que vous pouvez consulter à titre d'exemple dans le répertoire $JLOGGER_HOME$/src/net/directj/jlogger/jlogger.dtd. Il existe également un fichier de configuration de base, utilisé par JLogger pour ces propres besoins, ainsi qu'un fichier d'exemple situé à la base du répertoire src.

Voici un exemple simple:

01: <?xml version="1.0" ?>
02: <!DOCTYPE jlogger SYSTEM "jlogger.dtd" >
03: <jlogger xmlns:jl="http://www.jlogger-tool.sourceforge.net">
04:     <logger name="test1, test2">
05:         <manager level="ALL" class="net.directj.jlogger.XmlLogManager" param="C:\logs\log.xml, true" />
06:         <manager level="ERROR" />
07:     </logger>
08:     <logger name="test2">
09:         <manager level="ALL" class="net.directj.jlogger.FileLogManager" param="C:\logs\jlogger.log" />
10:     </logger>
11:     <logger name="test3">
12:         <manager level="ALL" >
13:             <formatter class="net.directj.jlogger.DefaultFormatter" />
14:             <output class="net.directj.jlogger.FileOutput" param="C:\logs\jlogger.log, true" />
15:         </manager>
16: </jlogger>

Placez ce code dans le même répertoire que le fichier JLogger.jar, et nommez le jlogger.xml. Lors de l'initialisation (au premier appel à JloggerFactory), ce fichier sera chargé et analysé, puis les logger et manager correspondant seront crées. Etudions donc un peu la syntaxe de ce fichier.

Le premier élément doit être "jlogger", et l'espace de nom "http://jlogger.directj.net"doit être spécifié. L'espace de nom est obligatoire, mais ne vous inquietez pas: le parser se charge lui même d'assigner au fichier la dtd qui y correspond. Ensuite, vous pouvez mettre un nombre quelconque d'élément "logger" (au moins un). L'élément "logger" ne possède qu'un seul attribut, "name", où doivent être listés les noms des logger, séparé par des virgules. Ainsi, pour cet exemple, deux logger sont crées : test1 et test2. Chacun de ces loggers sera accessible en appelant JloggerFactory.getLogger("test1"). Ensuite, il vous faut spécifier, pour chaque élément logger, un LogManager. Pour cela, il vous faut spécifier un nombre quelconque (au moins un) d'élément "manager". Cet élément possède trois paramètres, "class", "level" et "param". Class doit correspondre au nom d'une classe qui étend LogManager, level est le niveau du manager (OFF, DEBUG, INFO, WARNING, ERROR, FATAL ou OFF), et param est la liste des paramètres pour créer la classe. Seul level est requis. Si vous ne spécifiez pas "class", un LogManager par défaut est chargé, a priori ConsoleLogManager. Si vous ne précisez pas de paramètre, alors il n'y en aura pas! Sachez également que vous pouvez définir plusieurs fois le même logger, afin de spécifier différends logger. Enfin, plutôt que de spécifier le LogManager, vous pouvez en créer un et lui spécifier quel Formatter et Output utiliser, de la même manière que vous créiez les manager (ligne 11 à 15).

Etendre JLogger