[Gmod-apollo-cmts] CVS: apollo/src/java/apollo/gui/detailviewers/blixem BlixemRunner.java, 1.14, 1.15

[Jonathan C. <jcr...@us...>]

Update of /cvsroot/gmod/apollo/src/java/apollo/gui/detailviewers/blixem
In directory sc8-pr-cvs2.sourceforge.net:/tmp/cvs-serv32180/src/java/apollo/gui/detailviewers/blixem

Modified Files:
	BlixemRunner.java 
Log Message:
This commit is the first step in migrating Apollo to use Log4J
(http://logging.apache.org/log4j/docs/) instead of
System.out.print(ln) and System.err.print(ln), both for printing
informational and warning messages to the console (for "regular"
Apollo users), and also for printing more detailed debug and trace
messages (primarily for developers).  The advantages of using Log4J
over System.out.println are many and the Log4J site links to a number
of articles on this topic.  Given that it's a good idea to use a
logging package, one issue is whether to use Log4J or Java's built-in
logging classes (introduced in version 1.4).  I opted for Log4J 
because the consensus appears to be that it still has some advantages
over the built-in Java classes.  In addition, Apollo already includes
the Log4J jar file (version 1.2.6), for use by the Ensj adapter.

As noted in the previous commit, I've upgraded the Log4J jar file to
the latest stable version (1.2.14).  In _this_ commit I've begun 
converting Apollo to Log4J.  As a first step I've attempted to convert
any file that uses Config.DEBUG to decide whether to print debug
messages.  For each such file I've made the following changes:

1. Added org.apache.log4j.* to the list of imports.
2. Added a final static Logger variable, initialized to a Log4J
   logger named for the enclosing class, e.g.:

    protected final static Logger logger = LogManager.getLogger(Apollo.class);

3. Added comments (if not present) that distinguish the class's 
   class/static variables from its instance variables, and moved
   variable declarations around within the file if necessary 
   (so that all static vars appear together, and all instance/object
   vars appear together.)
4. Replaced every print or println with an appropriate log4j call.

In general the printlns were mapped to debug levels (trace,debug,info,
warn,error,fatal) using the following (approximate) rules:

o anything wrapped in "if (Config.DEBUG)": debug
o System.out.println: info, warn, debug, or error
o System.err.println: warn, debug, or error
o very detailed or commented-out printlns: debug or trace
o println followed by system exit: fatal

The following changes were also applied (uniformly, I hope):

o Calls to printStackTrace were removed in favor of passing the exception
  object to the log4j method (where the logger/appender can decide 
  whether to print the stack trace.)
o Removed most method and class names from the log messages; these can 
  be obtained from the logger name and/or context (if enabled.)
o Used isDebugEnabled() and/or isTraceEnabled() to avoid executing 
  expensive code in time-critical sections when logging is turned off.
o Removed any explicit printing of timing info., since Log4J can be 
  configured to record this if needed.
o Removed eye-catching formatting (e.g., "*** help, I'm trapped in a println ***");
  these effects can be emulated in Log4J by writing customized layout classes.

As a result of these changes almost all references to Config.DEBUG
have been removed.  This is a good thing, because references to this
variable were scattered throughout the Apollo code and there was
little consistency in how it was used.  All of the following were
observed at various places in the code:

o Direct references to Config.DEBUG
o Calls to Config.getDebug()
o Cached local copies of both of the above, initialized either:
  o in the constructor of the class ("pull")
  o by the Config.setDebug() method ("push")
o Additional class-specific DEBUG variables that didn't depend on Config.DEBUG.

Some additional notes:

o The apollo start script has two new options to support the Log4J logging:
  o -log4jdebug
    This option tells Log4J to print messages about its *own* operation (e.g.,
    parsing of Log4J config files).  Typically not used unless you're debugging
    a problem with the logger itself.
  o -log4j l4j.conf
    This option takes a single argument, the path to a Log4J configuration 
    file.  If this option is not specified then Apollo will use a default
    Log4J configuration file, conf/log4j-default.conf
o The Config.DEBUG variable has not been removed (yet), as a couple of Apollo
  classes use it to determine whether to enable certain experimental features
  (the IGB bridge appears to be one.)  It should at some point be replaced by
  more specific configuration variables.
o A number of classes (specifically those that support starting new Threads in
  Apollo) now call Apollo.setLog4JDiagnosticContext() and 
  Apollo.clearLog4JDiagnosticContext(), at the start and end of the thread's
  execution, respectively.  This allows us to set Log4J diagnostic context
  information that's the same across all threads.  I'm not really making use of
  this feature right now, but the idea is that you can add some session-specific
  information (e.g., the hostname and username) to every Log4J message, so that
  if Log4J is configured to log messages from several different Apollo processes
  into the same file then you'll be able to tell which messages come from which
  process/session.  However this idea is on hold for now because the default
  Apollo FileAppender does not appear to support having multiple Log4J processes
  writing to the same file.
o Added an optional LogDirectory parameter to ChadoInstance in chado-adapter.xml.
  If set to the path of a writable directory then JdbcChadoAdapter will configure
  Log4J to log all Apollo transactions and SQL statements to two files in this
  directory.  The names of the files will be based on the current time and the
  hostname and username of the machine and user running Apollo.  For example:

   2006-12-28_15:45:57:633_localhost_crabtree_w-sql.xml
   2006-12-28_15:45:57:633_localhost_crabtree_w-txn.xml

  Note that the Log4J XML output files can be viewed using a Java application
  called chainsaw (see http://logging.apache.org/log4j/docs/chainsaw.html)
o Added a oneLineSummary() method to the apollo.editor transaction classes; this
  method produces a (hopefully) more easily-readable string representation of a
  transaction suitable for logging to the -txn.xml file mentioned above.
o (Unrelated to logging.) Added TigrAnnotNameAdapterNewNameCommand to Config;
  this configuration parameter is used only by TigrAnnotNameAdapter and allows
  the user to specify an external script or program that should be used to 
  generate new chado uniquenames.
o The next step of the log4j migration will be to replace all remaining Apollo
  System.out and System.err.printlns with log4j calls.


Index: BlixemRunner.java
===================================================================
RCS file: /cvsroot/gmod/apollo/src/java/apollo/gui/detailviewers/blixem/BlixemRunner.java,v
retrieving revision 1.14
retrieving revision 1.15
diff -C2 -d -r1.14 -r1.15
*** BlixemRunner.java	20 Sep 2005 15:09:31 -0000	1.14
--- BlixemRunner.java	29 Dec 2006 16:39:03 -0000	1.15
***************
*** 6,9 ****
--- 6,10 ----
  import apollo.datamodel.*;
  
+ import apollo.main.Apollo;
  import apollo.seq.io.FastaFile;
  import apollo.config.Config;
***************
*** 34,38 ****
--- 35,41 ----
  
    public void run() {
+     Apollo.setLog4JDiagnosticContext();
      try {
+ 
        // Write temporary files (genomic sequence, features and genes)
        File exblxFile = File.createTempFile("blx",".exblx");
***************
*** 146,149 ****
--- 149,153 ----
        e.printStackTrace();
      }
+     Apollo.clearLog4JDiagnosticContext();
  }