org.erights.e.develop.trace
Class TraceController

java.lang.Object
  |
  +--org.erights.e.develop.trace.TraceController
All Implemented Interfaces:
TraceConstants

public class TraceController
extends Object
implements TraceConstants

Untamed: The single trace controller manages all the trace classes. Most notably, it has one TraceSubsystemMediator for each subsystem being traced. A TraceSubsystemMediator may mediate several Trace objects. Messages sent to those trace objects are forwarded to the mediator. The mediator, under the control of the TraceController, sends the message on to TraceMessageAcceptors that are ready to accept messages. The two current TraceMessageAcceptors are the TraceLog and the TraceBuffer. Once upon a time, there was a third, the TraceDisplay, which would echo to the screen the contents of the TraceBuffer. However, that proved impractical in the current build environment.


Field Summary
static String[] acceptorNames
           
static int ADD
           
static int DEBUG
           
(package private) static boolean debugTraceCaller
          Set if stack parsing is to be debugged.
static String DEFAULT_NAME
           
static int ERROR
          The different trace thresholds.
static int EVENT
           
static int FOR_SUBSYSTEM
           
static int FROM_DEFAULT
          When referring to thresholds, are we talking about those from the default thresholds, or ones specific to a subsystem? XXX These could be interned strings, but interning didn't work right in 1.0.4.
static int IRRELEVANT
           
static int LOG
          This identifies the TraceMessageAcceptor used for the on-disk log.
static String LOG_EXTENSION
           
static int MAX_THRESHOLD
           
private static TraceMessageAcceptor[][] myAcceptors
          The complete list of acceptors, for use by mediators.
private static TraceBuffer myBuffer
          The in-core trace buffer.
private static int[] myDefaultThresholds
          Trace thresholds that apply to subsystems that haven't been given specific values.
private static TraceLog myLog
          The on-disk log.
private static boolean myStarted
          Have we already been initialized?
private static TraceErrorWatcher myTraceErrorWatcher
          This object, if non-null, is informed when notifyFatal or notifyOptional is called.
private static Hashtable myTraceMediators
          The list of TraceSubsystemMediators for the subsystems being traced.
static int NUM_ACCEPTORS
          The number of different types of TraceMessageAcceptors.
static int OVERWRITE
           
static String[] reasonNames
           
static long SMALLEST_LOG_SIZE_THRESHOLD
           
static int STARTING_LOG_BACKUP_ACTION
           
static File STARTING_LOG_DIR
           
static long STARTING_LOG_SIZE_THRESHOLD
           
static String STARTING_LOG_TAG
           
static int STARTING_LOG_THRESHOLD
           
static boolean STARTING_LOG_WRITE
           
static int STARTING_TRACE_BUFFER_SIZE
           
static int STARTING_TRACE_THRESHOLD
           
private static Object synchronizationObject
          Synchronized static methods are prone to deadlocks in Sun's JVM.
static int TIMING
          As a late addition, there's a "timing" boolean that can be set orthogonally from the thresholds.
static int TRACE
          This identifies the TraceMessageAcceptor used for the in-core trace and its associated window.
static String UNLIMITED_NAME
           
static int USAGE
           
static int VERBOSE
           
static String version
           
static int WARNING
           
static int WORLD
           
 
Constructor Summary
TraceController()
          Enabled:
 
Method Summary
static void changeDisplay(boolean showIt)
          Enabled: Request that the trace buffer be visible in a window.
private static void changeOneDefault(int acceptorIndex, int newThreshold)
          Change the default threshold for some TraceMessageAcceptor.
private static void changeOneSubsystem(int acceptorIndex, String subsystem, String value)
          Change a specific TraceMessageMediator to have its own trace priority threshold OR change it to resume tracking the default.
static void debugTraceCaller()
          Enabled: For debugging purposes, dump each java runtime stack as it's parsed.
static void dumpBufferToLog()
          Enabled: Take the contents of the internal trace buffer and add them to the on-disk log.
static void errorWatcher(TraceErrorWatcher aTraceErrorWatcher, boolean add)
          Enabled: Register or unregister as a TraceErrorWatcher.
private static TraceSubsystemMediator findOrCreateMediator(String name)
          Find a TraceSubsystemMediator matching the given name.
static void mayUseUI()
          Enabled: Invoke this to tell the TraceController that a display is ready to use.
(package private) static void newTrace(Trace requester, String subsystem)
          This is called by a Trace constructor to inform the Trace Controller that it exists.
static void notifyFatal()
          Enabled: Notify a user that a fatal error has happened.
static void notifyOptional()
          Enabled: If the user wants to hear about nonfatal bugs, notify her.
static void setProperties(Properties p)
          Enabled: This method updates a trace controller from a given set of properties.
static void setProperty(String key, String value)
          Enabled: If the given Key names a tracing property, process its value.
private static void setTiming(int acceptorIndex, String afterFirstUnderbar, String value)
          Set the timing value of a given subsystem's acceptor.
static void start()
          Enabled: Use this constructor when you have no launch-time properties.
static void start(Properties p)
          Enabled: This routine is used to start the Trace Controller.
private static boolean timingProperty(String afterFirstUnderbar)
          Is this a timing control statement like "TraceBuffer_ui_timing=true"?
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

myTraceMediators

private static final Hashtable myTraceMediators
The list of TraceSubsystemMediators for the subsystems being traced. Indexed by subsystem name.


myDefaultThresholds

private static final int[] myDefaultThresholds
Trace thresholds that apply to subsystems that haven't been given specific values. NUM_ACCEPTORS elements.


myLog

private static final TraceLog myLog
The on-disk log.


debugTraceCaller

static boolean debugTraceCaller
Set if stack parsing is to be debugged.


myBuffer

private static final TraceBuffer myBuffer
The in-core trace buffer.


myStarted

private static boolean myStarted
Have we already been initialized?


myAcceptors

private static final TraceMessageAcceptor[][] myAcceptors
The complete list of acceptors, for use by mediators. The fact that there's a fixed set of acceptors that can't be changed without recompiling is probably the major rigidity of the code. There are currently two acceptors: on-disk logs and in-core buffers. The in-core buffer has two "variants": the buffer proper and a GUI window into the buffer.


myTraceErrorWatcher

private static TraceErrorWatcher myTraceErrorWatcher
This object, if non-null, is informed when notifyFatal or notifyOptional is called. There is at most one such object, because it may exit.


synchronizationObject

private static final Object synchronizationObject
Synchronized static methods are prone to deadlocks in Sun's JVM. This avoids the problem. Initialized in the class initializer to make sure it's available before the first trace object is used.


version

public static final String version

LOG

public static final int LOG
This identifies the TraceMessageAcceptor used for the on-disk log.


TRACE

public static final int TRACE
This identifies the TraceMessageAcceptor used for the in-core trace and its associated window.


NUM_ACCEPTORS

public static final int NUM_ACCEPTORS
The number of different types of TraceMessageAcceptors.


acceptorNames

public static final String[] acceptorNames

ERROR

public static final int ERROR
The different trace thresholds. See the Trace class for documentation. There is space between the levels for expansion. If you add or delete a level, you must change Trace.java to add new methods and variables.


WARNING

public static final int WARNING

WORLD

public static final int WORLD

USAGE

public static final int USAGE

EVENT

public static final int EVENT

DEBUG

public static final int DEBUG

VERBOSE

public static final int VERBOSE

MAX_THRESHOLD

public static final int MAX_THRESHOLD

TIMING

public static final int TIMING
As a late addition, there's a "timing" boolean that can be set orthogonally from the thresholds. The above values are overloaded: thresholds, but also identifiers for the original message (was it sent with errorm(), etc.). The TIMING "level" is added for the latter purpose, but it has nothing to do with thresholds. To avoid confusion, it's set negative, thus below the minimum threshold.


FROM_DEFAULT

public static final int FROM_DEFAULT
When referring to thresholds, are we talking about those from the default thresholds, or ones specific to a subsystem? XXX These could be interned strings, but interning didn't work right in 1.0.4. That is, two "default" strings weren't eq.


FOR_SUBSYSTEM

public static final int FOR_SUBSYSTEM

reasonNames

public static final String[] reasonNames

STARTING_TRACE_BUFFER_SIZE

public static final int STARTING_TRACE_BUFFER_SIZE

STARTING_TRACE_THRESHOLD

public static final int STARTING_TRACE_THRESHOLD

STARTING_LOG_SIZE_THRESHOLD

public static final long STARTING_LOG_SIZE_THRESHOLD

SMALLEST_LOG_SIZE_THRESHOLD

public static final long SMALLEST_LOG_SIZE_THRESHOLD

STARTING_LOG_THRESHOLD

public static final int STARTING_LOG_THRESHOLD

STARTING_LOG_WRITE

public static final boolean STARTING_LOG_WRITE

IRRELEVANT

public static final int IRRELEVANT

ADD

public static final int ADD

OVERWRITE

public static final int OVERWRITE

STARTING_LOG_BACKUP_ACTION

public static final int STARTING_LOG_BACKUP_ACTION

STARTING_LOG_DIR

public static final File STARTING_LOG_DIR

STARTING_LOG_TAG

public static final String STARTING_LOG_TAG

LOG_EXTENSION

public static final String LOG_EXTENSION

DEFAULT_NAME

public static final String DEFAULT_NAME

UNLIMITED_NAME

public static final String UNLIMITED_NAME
Constructor Detail

TraceController

public TraceController()
Enabled:

Method Detail

changeDisplay

public static void changeDisplay(boolean showIt)
Enabled: Request that the trace buffer be visible in a window. XXX This cannot be made to work given the current layering of the system / build environment. It should probably be thrown out.


changeOneDefault

private static void changeOneDefault(int acceptorIndex,
                                     int newThreshold)
Change the default threshold for some TraceMessageAcceptor. The change must propagate to all subsystems that track that acceptor's default.


changeOneSubsystem

private static void changeOneSubsystem(int acceptorIndex,
                                       String subsystem,
                                       String value)
Change a specific TraceMessageMediator to have its own trace priority threshold OR change it to resume tracking the default.


dumpBufferToLog

public static void dumpBufferToLog()
Enabled: Take the contents of the internal trace buffer and add them to the on-disk log.


debugTraceCaller

public static void debugTraceCaller()
Enabled: For debugging purposes, dump each java runtime stack as it's parsed.


errorWatcher

public static void errorWatcher(TraceErrorWatcher aTraceErrorWatcher,
                                boolean add)
Enabled: Register or unregister as a TraceErrorWatcher.

This is kind of a stupid interface. I didn't think it through before "publishing" it.

Parameters:
aTraceErrorWatcher - the object to be informed of an error.
add - true if the object is to be added, false if it's to be removed. It's not an error to add without first removing, or to remove without first adding, but it does provoke a warning.

findOrCreateMediator

private static TraceSubsystemMediator findOrCreateMediator(String name)
Find a TraceSubsystemMediator matching the given name. Create one if it does not exist. The new mediator initially contains copies of myDefaultThresholds and a pointer to myAcceptors.


mayUseUI

public static void mayUseUI()
Enabled: Invoke this to tell the TraceController that a display is ready to use.


newTrace

static void newTrace(Trace requester,
                     String subsystem)
This is called by a Trace constructor to inform the Trace Controller that it exists. The end result of this call is that a TraceSubsystemMediator exists for the Trace object's subsystem, and the Trace object has been initialized with the values it caches.


notifyFatal

public static void notifyFatal()
Enabled: Notify a user that a fatal error has happened. Tell her how to report the bug. Normally does not return.

If this method is called before a TraceErrorWatcher has registered, it's not clear what the best thing to do is. For the moment, we log that as an error and return, in the hopes that the system will hobble along a bit further to the point where a watcher registers and a later notifyFatal causes the user to be notified.


notifyOptional

public static void notifyOptional()
Enabled: If the user wants to hear about nonfatal bugs, notify her. Does return.

It is a (non-fatal) error if no object has registered as a TraceErrorWatcher.


setProperties

public static void setProperties(Properties p)
Enabled: This method updates a trace controller from a given set of properties.

IMPORTANT: The properties are processed in an unpredictable order.


setProperty

public static void setProperty(String key,
                               String value)
Enabled: If the given Key names a tracing property, process its value. It is not an error for the key to have nothing to do with tracing; in that case, it's ignored.

It is an error for the value to be null.


setTiming

private static void setTiming(int acceptorIndex,
                              String afterFirstUnderbar,
                              String value)
Set the timing value of a given subsystem's acceptor.

Parameters:
acceptorIndex - the acceptor.
afterFirstUnderbar - is of the form _timing, else an assertion fails.
value - is "on", "off", "true", or "false".

start

public static void start(Properties p)
Enabled: This routine is used to start the Trace Controller. Prior to this call, Trace objects may be obtained and messages may be sent to them. However, the messages will be queued up until this routine is called. (Note that the messages will be governed by the default thresholds.)

Note: This routine may be called before the user interface is available. This allows on-disk logging to be useful in the case the system fails before the UI is initialized.

Parameters:
p - the initial set of properties provided by the user. They override the defaults. They may be changed later.

start

public static void start()
Enabled: Use this constructor when you have no launch-time properties.


timingProperty

private static boolean timingProperty(String afterFirstUnderbar)
Is this a timing control statement like "TraceBuffer_ui_timing=true"?

Parameters:
afterFirstUnderbar - text after first underbar.


comments?