cox.jmatt.java.MathTools.util
Class CCLogHandler

java.lang.Object
  extended by java.util.logging.Handler
      extended by cox.jmatt.java.MathTools.util.CCLogHandler

public class CCLogHandler
extends java.util.logging.Handler

This class allows the java.util.logging framework to be attached to the MathTools logging methods. It is intended to allow third-party logging frameworks to take advantage of MathTools logging. Since most such packages make provision for the Java logging package it allows for easy integration.

Each java.util.logging.Level constant is mapped to one of the MathPrinter log levels. This is done numerically to allow custom Java levels to map appropriately. If the int value of the Level is greater than or equal to WARNING the message is logged at Error level. If it between INFO (inclusive) and WARNING (exclusive) it goes to Info level and anything less than INFO goes to Debug.

This Handler logs messages naively. The publish() method does not check to see whether or not its Logger accepts a particular Level so the Logger must do this manually if it is desired. The only concession made is in the isLoggable() method. If no Global Printer is set that method returns false. Likewise, publish() returns immediately no printer exists.

To use this class:

  1. Create or obtain a java.util.logging.Logger instance.
  2. Create an instance of this class.
  3. If desired, set a java.util.logging.Formatter to format the logged output. The default is a SimpleFormatter.
  4. Add this instance to the Logger.

To use CapCom logging with a third-party package follow the steps above but modified for the desired package. Most logging packages provide adapters for java.util.logging that fit it, hence CapCom, into themselves.

Error Management

This concerns errors generated by the logging system and not the application. These errors are, by default, reported at CapCom Error level along with a failure code, exception and optional message. The reportError() method exactly mirrors the error() method in the CCLogErrorManager class.

The CCLogErrorManager can be used with this class but doing so would be redundant. It is designed to allow other Handler classes access to CapCom logging. All of its behavior is mirrored internally here and enabled by default.


Constructor Summary
CCLogHandler()
          This constructor creates an instance and determines whether or not a Global MathPrinter is set.
 
Method Summary
 void close()
          This method removes all internal Formatters.
 void flush()
          Empty method.
 boolean isLoggable(java.util.logging.LogRecord pLogRec)
          This method ANDs super.isLoggable() with the presence of a Global Printer.
 void publish(java.util.logging.LogRecord pLogRec)
          Send CapCom a logging call.
protected  void reportError(java.lang.String pMesg, java.lang.Exception pErr, int pCode)
          This method is overridden to use CapCom.
 void setLogAlways(boolean pEnable)
          By default only the first log system error message is displayed; use this method to change that.
 void setUseErrorManager(boolean pEnable)
          Use this method to enable an external ErrorManager.
 
Methods inherited from class java.util.logging.Handler
getEncoding, getErrorManager, getFilter, getFormatter, getLevel, setEncoding, setErrorManager, setFilter, setFormatter, setLevel
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CCLogHandler

public CCLogHandler()
This constructor creates an instance and determines whether or not a Global MathPrinter is set. If so, logging messages will be printed. If not, not.

Method Detail

flush

public void flush()
Empty method. No buffering occurs.

Specified by:
flush in class java.util.logging.Handler

close

public void close()
This method removes all internal Formatters. Calling publish() after this method returns will result in a NullPointerException.

Specified by:
close in class java.util.logging.Handler

publish

public void publish(java.util.logging.LogRecord pLogRec)

Send CapCom a logging call. If no Formatter is set a SimpleFormatter is used. If 'pLogRec' is null or if its Level is null this method returns silently and no logging takes place. If logging does occur, the java.util.logging package levels are mapped numerically to CapCom as follows: SEVERE and WARNING map to Error level; INFO maps to Info level and anything less maps to Debug.

This method publishes records naively. It does not check loggability; rather, it publishes any non-null record with a non-null Level that is passed in. Logger instances requiring discrimination of log levels should implement it manually. It does check to see if a MathPrinter is set (or was set when this instance was created). If not it returns silently.

Specified by:
publish in class java.util.logging.Handler

isLoggable

public boolean isLoggable(java.util.logging.LogRecord pLogRec)

This method ANDs super.isLoggable() with the presence of a Global Printer. The latter depends on whether or not a printer was set when this instance was created. If no printer was set this method returns false. Period.

Overrides:
isLoggable in class java.util.logging.Handler

reportError

protected void reportError(java.lang.String pMesg,
                           java.lang.Exception pErr,
                           int pCode)

This method is overridden to use CapCom. If an ErrorManager should be used set one and call 'setUseErrorManager(true)'.

Unless 'logAlways' is set true this method ignores any calls after the first. If no Global Printer is set then no CapCom logging occurs but if an external manager is set it will still be called.

Overrides:
reportError in class java.util.logging.Handler

setLogAlways

public void setLogAlways(boolean pEnable)

By default only the first log system error message is displayed; use this method to change that. Calling this method with 'true' causes all log system messages to be displayed. Any such appear at Error level.


setUseErrorManager

public void setUseErrorManager(boolean pEnable)
Use this method to enable an external ErrorManager. By default this method reports all errors generated by the logging system to CapCom. Calling this method with 'true' causes the external manager to be used instead.