Houston - Open Source Status and Logging Toolkit

Houston is an open-source, light-weight status and logging toolkit offering a plug-in architecture to let you choose the underlying, industry-strength logging toolkit such as Apache log4j or Java 1.4's built-in java.util.logging toolkit.

Architecture. Houston uses the publish/subscribe model and sends reported errors, warnings, infos, hints, and so on to subscribed status handlers. Status handler for command-line apps usually display incoming messages in plain text on the console, while classic desktop apps display incoming messages in the status bar or in a message box using styled text in various colors (e.g red for errors, orange for warnings, etc) with icons and other visual gimmicks.

To report errors, warnings, infos, hints, and so on use one of the static methods in houston.Status. Example:

Status.info( "downloading " + _source.toExternalForm() + "..." );

Status.info( 3, carFile + " successfully created" );

Status.warning( "*** skipping unsupported file type:" + internalPath );

Status.error( "*** failed to startup web service: " + ioex.toString() );

Status.error( "*** source path for jar " + jar.getHref() + " required" );

To make sure that your reported messages get noticed and end up on the user's screen, you need to register status handlers. Use houston.Status.addListener( StatusListener ) to tell Houston who's in the loop and gets the latest updates. Example:

Status.addListener( new StatusConsole() );
Status.addListener( new StatusPanel() );
Status.addListener( new StatusBarPanel() );

Houston ships with three pre-built status handlers.

• houston.StatusConsole - sends messages to the console using System.out as well as to the underlying logging toolkit such as Apache log4j
• houston.swing.StatusBarPanel - displays messages in the status bar using color coding; the latest message overwrites the previous one
• houston.swing.StatusPanel - displays messages in a text box using color coding; no messages get purged

To create your own status handler, implement the interface houston.StatusListener. Example:

public class StatusConsole implements StatusListener
{
  public void hint(String msg)    { System.out.println( msg ); }
  public void info(String msg)    { System.out.println( msg ); }
  public void warning(String msg) { System.out.println( msg ); }
  public void fatal(String msg)   { System.out.println( msg ); }
  public void error(String msg)   { System.out.println( msg ); }

  public void info( int level, String msg )
  {
    System.out.println( "[" + level +"] " + msg );
  }
}

Houston uses a thin wrapper around Java's 1.4 built-in java.util.logging.Logger class. By default Java's runtime spits out all log messages on the console ranking as INFO or higher. To let the runtime spit out more or less log messages or to let it send log messages to a file or to a socket use Java's standard java.util.logging.* properties.

Houston uses the log message types below, ranked from highest to lowest. Houston's types differ slightly from Java's built-in logging types: Instead of SEVERE for all errors Houston uses FATAL and ERROR. Houston adds DEBUG as an alias for FINE and adds the new message type HINT one notch below INFO and one above CONFIG/DEBUG.

Houston	java.util.logging	Audience	Comment
FATAL	SEVERE	Grandma (*)
ERROR	SEVERE	Grandma
WARNING	WARNING	Grandma
INFO	INFO	Grandma
HINT	INFO	Grandma
CONFIG	CONFIG	Sys Admin
DEBUG/FINE	FINE	Developer
FINER	FINER	Developer
FINEST	FINEST	Developer

(*) also known as end-user

Configuring Loggers. By default the Java runtime picks up the logging settings from the logging.properties config file in its lib directory (e.g. jre/v14/lib). Note, that if you installed a dev kit (aka JDK) you likely have two copies of the Java runtime on your machine. To find out which Java runtime Web Start picks up to fire off your app peek into javaws.cfg, Web Start's config file residing in its home directory (e.g. java/jws/v1.01-2). The snippet below reveals my box'es settings:

   
javaws.cfg.jre.1.product=1.4.0
javaws.cfg.jre.1.platform=1.4
javaws.cfg.jre.1.location=http\://java.sun.com/products/autodl/j2se
javaws.cfg.jre.1.path=c\:\\java\\jre\\v14\\bin\\javaw.exe

As an alternative you can kick start Sysinfo app (part of the Ramses Luxor Example suite) and switch over to the system info page. Under the directories heading you'll find the nugget you are looking for. Example:

User Home: c:\windows
Temp Directory: c:\windows\temp
Java Home: c:\java\jre\v14
Web Start Home: c:\java\jws\v1.01-2

By default the Java runtime uses the settings below to spit out all log message ranked as INFO and above to the console (aka command line shell, dos box):

# "handlers" specifies a comma separated list of log Handler classes.
handlers= java.util.logging.ConsoleHandler

# Default global logging level.
.level= INFO

# Limit the message that are printed on the console to INFO and above.
java.util.logging.ConsoleHandler.level = INFO
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

To dump the log messages to a file in the user's home directory as well as to the console append a FileHandler and configure it. Example:

handlers= java.util.logging.ConsoleHandler, java.util.logging.FileHandler

# default file output is in user's home directory.
java.util.logging.FileHandler.pattern = %h/java%u.log
java.util.logging.FileHandler.level = FINE
java.util.logging.FileHandler.limit = 10000
java.util.logging.FileHandler.count = 1
java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter

Note, refrain from using the prelisted java.util.logging.XMLFormatter unless you have time to kill (as your app won't pop up in an instant).

As an alternative you can sidestep the factory-shipped jre/v1.4/lib/logging.properties logging config file and preserve it untouched and direct the Java Runtime to use your very own config file instead. Add a property tag for java.util.logging.config.file pointing to your config file to your app's JNLP startup file. Example:

<property name="java.util.logging.config.file" value="c:/sandbox/etc/logging.properties" />

Houston is similar to Apache's commons logging toolkit because it's not a logging toolkit itself but a wrapper sporting a plug-in architecture that lets you pick and choose the underlying toolkit.

Houston differs from Apache's commons logging toolkit by focusing on classic desktop apps sporting status bars, message windows, progess meters and more instead of window-less, 24x7x365 server apps.

Apache log4j Logging Toolkit
http://jakarta.apache.org/log4j/ - Overview
http://jakarta.apache.org/log4j/docs/api/ - Javadoc API Spec

Apache Commons Logging Toolkit
http://jakarta.apache.org/commons/logging.html - Project Page
http://jakarta.apache.org/commons/logging/api/ - Javadoc API Spec
http://jakarta.apache.org/commons/logging/api/org/apache/commons/logging/package-summary.html - Overview

Java's 1.4 built-in Logging Toolkit
http://java.sun.com/j2se/1.4/docs/guide/util/logging/overview.html - Overview
http://java.sun.com/j2se/1.4/docs/api/java/util/logging/package-summary.html - Javadoc API Spec