docs/devel/logging.md

   1 # The JPF Logging API #
   2 There is one simple rule: do not use `System.out` or `System.err` for any permanent logging
   3
   4
   5 Of course we all do this temporarily during debugging, but it really shouldn't stay in the code. The logging infrastructure is quite easy to use. Just declare a static `Logger` instance with an appropriate id (either package or logging topic) at the top of your class, and then use the `Logger` API to create output:
   6
   7 ~~~~~~~~ {.java}
   8 ...
   9 import java.util.logging.Level;
  10 import java.util.logging.Logger;
  11
  12 package x.y.z;
  13
  14 class MyClass .. {
  15   static Logger log = JPF.getLogger("x.y.z");
  16   ...
  17     log.severe("there was an error");
  18   ...
  19     log.warning("there was a problem");
  20   ...
  21     log.info("something FYI");
  22   ...
  23     if (log.isLoggable(Level.FINE)){    // (1) don't create garbage
  24         log.fine("this is some detailed info about: " + something);
  25     }
  26   ...
  27 }
  28 ~~~~~~~~
  29
  30 Note that there is only one instance for each `Logger` ID, i.e. you can have a corresponding static field in all your relevant classes, and don't have to share the fields. Another aspect that is mostly important for the lower log levels (e.g. `FINE`) is that you should't concatenate log messages in operations that occur frequently, since the corresponding `StringBuilder` instances can cause performance degradations even if the log level is not set (the arguments still get evaluated). In this case, encapsulate the logging in `log.isLoggable(level){..}` blocks.
  31