Sophie Network: Vamp HQ - Luxor XUL - Ajax - Rachel - Lopica - The Saturn Times - The Richmond Post
Ajax Family: Apollo - Caramel - Cypress - Houston - Salsa
Houston Logo
Status and Logging Toolkit
Overview . Download . Source . Javadoc . Mailing List . Houston @ Sourceforge

Houston - Open Source Status and Logging Toolkit

What is Houston?

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: "downloading " + _source.toExternalForm() + "..." ); 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.

Roll Your Own Status Handler

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 );
Java 1.4 Logging Tips and Tricks

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 (*)

(*) also known as end-user

Configuring Loggers. By default the Java runtime picks up the logging settings from the 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:


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 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/" />
How does Houston differ from Apache Jakarta's commons-logging toolkit?

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.

Resources, Links

Apache log4j Logging Toolkit - Overview - Javadoc API Spec

Apache Commons Logging Toolkit - Project Page - Javadoc API Spec - Overview

Java's 1.4 built-in Logging Toolkit - Overview - Javadoc API Spec

More Quick Links: Batik SVG · Velocity · Python · Jython · JDOM · dom4j · Jaxen · Eclipse SWT · Mono · Gtk# · Qt# · Mozilla · Web Start · Skin L&F · Kunststoff L&F · Relax NG · XDoclet
SourceForge Logo Send your comments, suggestions, praise or poems to Copyright © 2001, 2002, 2003 Gerald Bauer