bb.util.logging
Class HandlerGui

java.lang.Object
  extended by java.util.logging.Handler
      extended by bb.util.logging.HandlerAbstract
          extended by bb.util.logging.HandlerGui

public class HandlerGui
extends HandlerAbstract

Logs to a GUI window.

This class obviously differs from HandlerConsole in that it uses a GUI instead of a console. Furthermore, it also differs in that data updates are completely controlled by the user. In particular, if the user is looking at a snapshot of LogRecords in the GUI, and new LogRecords are received by this instance (via publish), then those new LogRecords are stored in an internal BufferFixed field and the GUI is merely updated to notify the user that new data is present. But it is always up to the user to decide when to replace the currently displayed information with the newest.

This class can be used as a GUI alternative to the UNIX tail command. It can be useful to attach an instance to the root Logger, and have it publish serious logs.

If the GUI window is closed by the user, then it will be recreated if a new LogRecord arrives. However, if the GUI window is closed by a call to close, then it will be permanently closed.

It is unclear whether or not this class is multithread safe. There may be issues with its superclass; see HandlerAbstract for more discussion. Concerning the state added by this class, every non-GUI method is synchronized, while the GUI methods are ensured to only be called by EventQueue's dispatch thread.

Author:
Brent Boyer

Nested Class Summary
static class HandlerGui.UnitTest
          See the Overview page of the project's javadocs for a general description of this unit test class.
 
Field Summary
private  BufferFixed<LogRecord> bufferFixed
          Accumulates the next snapshot of LogRecords that is to be displayed in the GUI.
private  FrameLog frameLog
          The GUI window where logs get displayed.
 
Constructor Summary
HandlerGui()
          Convenience constructor.
HandlerGui(int sizeMax)
          Fundamental constructor.
 
Method Summary
 void close()
          First call releases all resources used by this instance, including permanently closing the GUI window.
 void flush()
          Implementation here does nothing, since the user has total control over when the GUI gets updated.
protected  Formatter getFormatterDefault()
          Implementation here returns a new FormatterFull instance.
(package private)  String getLogRecords()
           
private  void initGuiIfNeeded()
           
 void publish(LogRecord record)
          If isAlive or isLoggable(record) returns false, then immediately returns.
(package private)  void releaseGui()
           
 
Methods inherited from class bb.util.logging.HandlerAbstract
configure, getEncodingDefault, getFilterDefault, getFilterProperty, getFormatterProperty, getIntProperty, getLevelDefault, getLevelProperty, getStringProperty, isAlive, isLoggable, setAlive
 
Methods inherited from class java.util.logging.Handler
getEncoding, getErrorManager, getFilter, getFormatter, getLevel, reportError, setEncoding, setErrorManager, setFilter, setFormatter, setLevel
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

bufferFixed

private BufferFixed<LogRecord> bufferFixed
Accumulates the next snapshot of LogRecords that is to be displayed in the GUI.

Contract: is never null after construction, but is nulled out once and for all when close is first called.


frameLog

private FrameLog frameLog
The GUI window where logs get displayed.

Contract: is null until lazy initialized by publish, then is nulled out once and for all when close is first called.

Constructor Detail

HandlerGui

public HandlerGui()
Convenience constructor.

All this instance's initial configuration comes from the LogManager properties described in HandlerAbstract.configure, except for the BufferFixed.sizeMax field which is assigned from calling getIntProperty(getClass().getName() + ".sizeMax", 1000). In other words, BufferFixed.sizeMax is set to whatever is defined for it in the logging properties file, else it defaults to 1000 if not defined there.


HandlerGui

public HandlerGui(int sizeMax)
           throws IllegalArgumentException
Fundamental constructor.

All this instance's initial configuration comes from the LogManager properties described in HandlerAbstract.configure, except for the BufferFixed.sizeMax field which is assigned from the param.

Throws:
IllegalArgumentException - if sizeMax <= 0
Method Detail

close

public void close()
First call releases all resources used by this instance, including permanently closing the GUI window. All future calls to publish will be silently ignored.

Overrides:
close in class HandlerAbstract

flush

public void flush()
Implementation here does nothing, since the user has total control over when the GUI gets updated.

Specified by:
flush in class Handler

publish

public void publish(LogRecord record)
If isAlive or isLoggable(record) returns false, then immediately returns. Else adds record to bufferFixed and notifies the GUI that a new record has arrived.

Specified by:
publish in class Handler

getFormatterDefault

protected Formatter getFormatterDefault()
Implementation here returns a new FormatterFull instance.

Overrides:
getFormatterDefault in class HandlerAbstract

getLogRecords

String getLogRecords()

initGuiIfNeeded

private void initGuiIfNeeded()

releaseGui

void releaseGui()