---

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.

---

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

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.

$

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:

---

---