org.erights.e.develop.trace
Class Trace

java.lang.Object
  |
  +--org.erights.e.develop.trace.Trace

All Implemented Interfaces:

TraceConstants

public final class Trace

extends Object

implements TraceConstants

Untamed: This might better be called TraceCache, but the name is retained for backward compatibility. The major purpose of this class is to hold a cache of a relevant trace priority threshold, so that a user of the trace code can quickly decide whether to call a trace method. Methods on this object communicate with the master TraceController, which does the real work of tracing.

Secondarily, this class holds some miscellaneous functions useful in tracing.

Field Summary

static String[]	acceptorNames
static int	ADD
static Trace	captp Enabled:
static Trace	causality Enabled:
static Trace	comm Enabled: comm systems
static Trace	console Enabled:
boolean	debug Enabled: Debug messages provide more detail for people who want to delve into what's going on, probably to figure out a bug.
static int	DEBUG
static String	DEFAULT_NAME
static Trace	dgc Enabled: Distributed garbage collector.
static Trace	entropy Enabled:
boolean	error Enabled: Error messages report on some internal error.
static int	ERROR The different trace thresholds.
static Trace	eruntime Enabled: The E runtime
boolean	event Enabled: Event messages describe the major actions the system takes in response to user actions.
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
(package private) TraceSubsystemMediator	myMediator This is the mediator that actually disposes of a message.
private String	mySubsystem The subsystem is the group of classes this Trace object applies to.
static int	NUM_ACCEPTORS The number of different types of TraceMessageAcceptors.
static boolean	ON Enabled: Set this to false to compile out all tracing.
static int	OVERWRITE
static Trace	pumpkin Enabled:
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
static Trace	startup Enabled: Classes involved in starting up the world.
private static Object	synchronizationObject Synchronized static methods are prone to deadlocks in Sun's JVM.
static Trace	timers Enabled:
boolean	timing Enabled: Timing messages are for performance tuning.
static int	TIMING As a late addition, there's a "timing" boolean that can be set orthogonally from the thresholds.
static Trace	trace Enabled:
static int	TRACE This identifies the TraceMessageAcceptor used for the in-core trace and its associated window.
static Trace	tunnel Enabled:
static String	UNLIMITED_NAME
boolean	usage Enabled: Usage messages are used to answer the question "who did what up to the point the bug appeared?" ("Spock entered Azturf.
static int	USAGE
boolean	verbose Enabled: Verbose messages provide even more detail than debug.
static int	VERBOSE
static String	version
boolean	warning Enabled: Warning messages are not as serious as errors, but they're signs of something odd.
static int	WARNING
static Trace	wire Enabled:
boolean	world Enabled: World messages track the state of the world as a whole.
static int	WORLD

Constructor Summary

Trace(String subsystem)
Enabled: Initialize a Trace object for the given subsystem.

Method Summary

void	$(String message) Enabled:
static String	arrayToString(Object[] a, String name, String pre, String sep, String post) Enabled: Convert an array to a string.
void	debugm(String message) Enabled:
void	debugm(String message, Object o) Enabled:
void	errorm(String message) Enabled:
void	errorm(String message, int bugNumber) Enabled:
void	errorm(String message, Object o) Enabled:
void	errorm(String message, Object o, int bugNumber) Enabled:
void	eventm(String message) Enabled:
void	eventm(String message, Object o) Enabled:
void	fatalError(String message) Enabled: Exit reporting a fatal error.
void	notifyFatal() Enabled: Notify a user that a fatal error has happened.
void	notifyOptional() Enabled: If the user wants to hear about nonfatal bugs, notify her.
private void	recordTraceMessageXyzzY(String message, int level, Object o, boolean noNotify) The peculiar name is because the code that finds the line number a trace call was made from searches for this method.
void	setTraceMode(String mode) Enabled: It is no longer legal for anyone other than the TraceController to set the trace mode.
void	shred(Throwable ex, String reason) Enabled: To ensure that exceptional conditions are only being ignored for good reason, we adopt the discipline that a caught exception should
void	timingm(String message) Enabled: Public interface methods that accept classes are the names of the boolean fields, with 'm' appended (to denote 'method').
void	timingm(String message, Object o) Enabled: These methods take an Object in addition to a string.
(package private) static void	touch() Invoking this method causes this class to be loaded, which causes all the static trace objects to be defined.
void	usagem(String message) Enabled:
void	usagem(String message, Object o) Enabled:
void	verbosem(String message) Enabled:
void	verbosem(String message, Object o) Enabled:
void	warningm(String message) Enabled:
void	warningm(String message, Object o) Enabled:
void	worldm(String message) Enabled:
void	worldm(String message, Object o) Enabled:

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ON

public static final boolean ON

Enabled: Set this to false to compile out all tracing. This also has to be set in TraceDummies.java

error

public boolean error

Enabled: Error messages report on some internal error. They don't necessarily lead to the system stopping, but they might. Error messages are always logged.

warning

public boolean warning

Enabled: Warning messages are not as serious as errors, but they're signs of something odd.

world

public boolean world

Enabled: World messages track the state of the world as a whole. They are the sort of things world operators ask for specifically, such as "can you tell me when someone connects." They should appear only occasionally, much less often than once per second. This is probably the level used for the on-disk log in the shipped version.

usage

public boolean usage

Enabled: Usage messages are used to answer the question "who did what up to the point the bug appeared?" ("Spock entered Azturf. Spock started trading with Kyra. Kyra gave Spock a diamond in exchange for a lump of coal. Kyra spoke.") They are also used to collect higher-level usability information. This is the level probably used for the transient log in the shipped version; during development, we can set the on-disk log to this level.

event

public boolean event

Enabled: Event messages describe the major actions the system takes in response to user actions. The distinction between this category and debug is fuzzy, especially since debug is already used for many messages of this type. However, it can be used to log specific user gestures for usability testing, and to log information for testers.

debug

public boolean debug

Enabled: Debug messages provide more detail for people who want to delve into what's going on, probably to figure out a bug.

verbose

public boolean verbose

Enabled: Verbose messages provide even more detail than debug. They're probably mainly used when first getting the code to work.

timing

public boolean timing

Enabled: Timing messages are for performance tuning. Whether timing messages are logged is independent of the values of all the other trace variables.

comm

public static final Trace comm

Enabled: comm systems

captp

public static final Trace captp

Enabled:

wire

public static final Trace wire

Enabled:

tunnel

public static final Trace tunnel

Enabled:

dgc

public static final Trace dgc

Enabled: Distributed garbage collector.

pumpkin

public static final Trace pumpkin

Enabled:

eruntime

public static final Trace eruntime

Enabled: The E runtime

causality

public static final Trace causality

Enabled:

startup

public static final Trace startup

Enabled: Classes involved in starting up the world.

entropy

public static final Trace entropy

Enabled:

timers

public static final Trace timers

Enabled:

trace

public static final Trace trace

Enabled:

console

public static final Trace console

Enabled:

myMediator

TraceSubsystemMediator myMediator

This is the mediator that actually disposes of a message. Multiple Trace objects may share the same mediator.

mySubsystem

private final String mySubsystem

The subsystem is the group of classes this Trace object applies to. This exists for encoding/decoding; it duplicates information available in the Mediator.

synchronizationObject

private static final Object synchronizationObject

Synchronized static methods are prone to deadlocks in Sun's JVM. This avoids the problem.

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

Trace

public Trace(String subsystem)

Enabled: Initialize a Trace object for the given subsystem. It is legal for the subsystem to contain blanks. Things will become confused if it contains a colon, but the code does not check for that.

Method Detail

$

public void $(String message)

Enabled:

arrayToString

public static String arrayToString(Object[] a,
                                   String name,
                                   String pre,
                                   String sep,
                                   String post)

Enabled: Convert an array to a string.

Parameters:

a - the string.

name - string to prepend to the array.

pre - string to prepend to an element.

sep - string to separate elements.

post - string to append to an element.

debugm

public void debugm(String message)

Enabled:

debugm

public void debugm(String message,
                   Object o)

Enabled:

errorm

public void errorm(String message)

Enabled:

errorm

public void errorm(String message,
                   int bugNumber)

Enabled:

errorm

public void errorm(String message,
                   Object o)

Enabled:

errorm

public void errorm(String message,
                   Object o,
                   int bugNumber)

Enabled:

eventm

public void eventm(String message)

Enabled:

eventm

public void eventm(String message,
                   Object o)

Enabled:

fatalError

public void fatalError(String message)

Enabled: Exit reporting a fatal error.

Parameters:

message - The error message to die with

notifyFatal

public void notifyFatal()

Enabled: Notify a user that a fatal error has happened. Tell her how to report the bug. Does not return.

The work is done by the TraceController static object. This method is a convenience for code that doesn't import TraceController.

notifyOptional

public void notifyOptional()

Enabled: If the user wants to hear about nonfatal bugs, notify her. Does return.

The work is done by the TraceController static object. This method is a convenience for code that doesn't import TraceController.

recordTraceMessageXyzzY

private void recordTraceMessageXyzzY(String message,
                                     int level,
                                     Object o,
                                     boolean noNotify)

The peculiar name is because the code that finds the line number a trace call was made from searches for this method. So it should have a name unlikely to be accidentally duplicated.

setTraceMode

public void setTraceMode(String mode)

Enabled: It is no longer legal for anyone other than the TraceController to set the trace mode.

shred

public void shred(Throwable ex,
                  String reason)

Enabled: To ensure that exceptional conditions are only being ignored for good reason, we adopt the discipline that a caught exception should

1) be rethrown

2) cause another exception to be thrown instead

3) be ignored, in a traceable way, for some stated reason

Only by making #3 explicit can we distinguish it from accidentally ignoring the exception. An exception should, therefore, only be ignored by asking a Trace object to shred it. This request carries a string that justifies allowing the program to continue normally following this event. As shredded exceptions will likely be symptoms of bugs, one will be able to have them traced.

The reason for the shredding is logged at verbose level.

timingm

public void timingm(String message)

Enabled: Public interface methods that accept classes are the names of the boolean fields, with 'm' appended (to denote 'method').

timingm

public void timingm(String message,
                    Object o)

Enabled: These methods take an Object in addition to a string. Note that logging a null object is the same thing as logging no object at all. (Fix this if anyone complains.)

touch

static void touch()

Invoking this method causes this class to be loaded, which causes all the static trace objects to be defined. In particular, Trace.trace becomes defined. That's convenient, in that it allows more tracing of the tracing startup itself.

usagem

public void usagem(String message)

Enabled:

usagem

public void usagem(String message,
                   Object o)

Enabled:

verbosem

public void verbosem(String message)

Enabled:

verbosem

public void verbosem(String message,
                     Object o)

Enabled:

warningm

public void warningm(String message)

Enabled:

warningm

public void warningm(String message,
                     Object o)

Enabled:

worldm

public void worldm(String message)

Enabled:

worldm

public void worldm(String message,
                   Object o)

Enabled: