org.erights.e.develop.trace
Class TraceSubsystemMediator

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

All Implemented Interfaces:

TraceConstants

class TraceSubsystemMediator

extends Object

implements TraceConstants

This class mediates between the Trace objects that send messages and the TraceMessageAcceptors that accept them. It has two key roles:

Determining which of the acceptors should get a particular message.

Setting the thresholds used to answer the above question.

Field Summary

static String[]	acceptorNames
static int	ADD
static int	DEBUG
static String	DEFAULT_NAME
(package private) boolean[]	deferToDefaultThreshold True if this subsystem's threshold is whatever "default"'s is.
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 TraceMessageAcceptor[][]	myAcceptors The acceptors all mediators communicate with.
private Vector	myCaches Specific Trace objects act as caches.
private String	mySubsystem The subsystem that uses this mediator.
private int[]	myThresholds The threshold to use.
private boolean[]	myTimingBooleans Whether timing has been turned on for a particular acceptor.
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
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

(package private)

TraceSubsystemMediator(String aSubsystem, int[] someThresholds, TraceMessageAcceptor[][] someAcceptors) Create a TraceSubsystemMediator.

Method Summary

void	accept(TraceMessage message) Accept a message and distribute it to all the acceptors who accept messages of that level.
private int	commonThreshold() The common threshold is the most detailed (lowest).
private boolean	commonTiming() The common timing is true if any acceptor times.
(package private) void	newCache(Trace newCache) This routine is called when a new Trace object is to be added to this mediator.
(package private) void	setOneThreshold(int acceptorIndex, int newValue, int reason) Set a particular acceptor's threshold, either to track the default or to have its own particular value.
(package private) void	setTiming(int acceptorIndex, boolean newValue) Set a particular acceptor's timing value.
private void	updateOneThresholdCache(Trace tr, int commonThreshold) Update tracing thresholds.
private void	updateOneTimingCache(Trace tr, boolean commonTiming) Update timing thresholds.

Methods inherited from class java.lang.Object

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

Field Detail

mySubsystem

private final String mySubsystem

The subsystem that uses this mediator.

deferToDefaultThreshold

final boolean[] deferToDefaultThreshold

True if this subsystem's threshold is whatever "default"'s is. False if the user specified a specific threshold. There are NUM_ACCEPTORS elements.

Note that this variable can be accessed outside this class.

Having knowledge of who's tracking the default be shared between this class and TraceController is kind of slimy, but there's not enough of a gain in fiddling with it.

myThresholds

private int[] myThresholds

The threshold to use. Either defined by the user or set from the default. There are NUM_ACCEPTORS elements. This is initially a copy of the default thresholds from TraceController. After that, the elements may change independently, including going back to tracking the default.

myTimingBooleans

private final boolean[] myTimingBooleans

Whether timing has been turned on for a particular acceptor. NUM_ACCEPTORS elements. The initial value is false. There is no system-wide default, because that doesn't seem particularly useful.

myAcceptors

private final TraceMessageAcceptor[][] myAcceptors

The acceptors all mediators communicate with. (Could be static, as it is always identical to those stored in TraceController.)

myCaches

private final Vector myCaches

Specific Trace objects act as caches. There may be multiple trace objects for one subsystem.

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

TraceSubsystemMediator

TraceSubsystemMediator(String aSubsystem,
                       int[] someThresholds,
                       TraceMessageAcceptor[][] someAcceptors)

Create a TraceSubsystemMediator. It tracks the default priority thresholds.

Parameters:

aSubsystem - the subsystem this mediates.

Method Detail

accept

public void accept(TraceMessage message)

Accept a message and distribute it to all the acceptors who accept messages of that level.

This method represents the second level of filtering by priority. The first level is by the original user code, which uses the Trace object booleans to do its own filtering. TraceMessageAcceptors don't do any filtering.

Note: This method represents the transition from inside the vat to outside the vat. Therefore the message's timestamp is added here.

commonThreshold

private int commonThreshold()

The common threshold is the most detailed (lowest).

commonTiming

private boolean commonTiming()

The common timing is true if any acceptor times.

newCache

void newCache(Trace newCache)

This routine is called when a new Trace object is to be added to this mediator. We update the cache's state to reflect the state of this mediator. (Note that we reach into the object and twiddle its fields. That's because its an in-vat object and not allowed to set its own fields. Since it's a static object, such would allow a covert channel.

setOneThreshold

void setOneThreshold(int acceptorIndex,
                     int newValue,
                     int reason)

Set a particular acceptor's threshold, either to track the default or to have its own particular value.

Parameters:

acceptorIndex - which acceptor to change

newValue - to what value. Note that default values are no different from specific values.

setTiming

void setTiming(int acceptorIndex,
               boolean newValue)

Set a particular acceptor's timing value. Unlike setOneThreshold, there's no notion of tracking a default.

Parameters:

acceptorIndex - which acceptor to change

newValue - to what value.

updateOneThresholdCache

private void updateOneThresholdCache(Trace tr,
                                     int commonThreshold)

Update tracing thresholds.

A trace object is used as a cache for quick checking of tracing thresholds. This routine updates that cache.

Why, you ask, does this method rudely bash on variables within the Trace object, instead of calling a method to set them? It's because the Trace object is inside the vat, and no object inside the vat is allowed to change those values, because they are reachable through static state.

Parameters:

tr - the trace object itself.

commonThreshold - the lowest threshold of all the acceptors.

updateOneTimingCache

private void updateOneTimingCache(Trace tr,
                                  boolean commonTiming)

Update timing thresholds. See updateOneThresholdCache.

Parameters:

tr - the trace object itself.

commonTiming - the value to set.