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.