org.erights.e.develop.trace
Class TraceLogDescriptor

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

All Implemented Interfaces:

Cloneable, TraceConstants

class TraceLogDescriptor

extends Object

implements Cloneable, TraceConstants

This class describes the file system interface to a log file. The standard format is ..txt. The standard backup filename format is then ...txt.

The entire format may be overridden, the tag may be changed, or the class can be instructed to use PrintStreamWriter.out().

This class is responsible for opening new files. Importantly, that includes renaming old versions.

Field Summary

static String[]	acceptorNames
static int	ADD
static int	DEBUG
static String	DEFAULT_NAME
private File	dir The directory in which the log lives.
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.
private static Date	initDate The date this trace system was initialized; used as part of the standard name format.
static int	IRRELEVANT
static int	LOG This identifies the TraceMessageAcceptor used for the on-disk log.
static String	LOG_EXTENSION
static int	MAX_THRESHOLD
static int	NUM_ACCEPTORS The number of different types of TraceMessageAcceptors.
static int	OVERWRITE
private String	personalFile The file being used for the log, if format chosen by user.
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
(package private) static TraceLogDescriptor	stdout This log descriptor always represents standard output.
PrintWriter	stream The stream open to the log.
private String	tag The 'tag' is the first component of the log filename.
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
private boolean	usePersonalFormat True if the user overrode the standard tag.date.txt format.
private boolean	useStdout Determine whether PrintStreamWriter.out() is used instead of a file.
static int	VERBOSE
static String	version
static int	WARNING
static int	WORLD

Constructor Summary

(package private)

TraceLogDescriptor()

Method Summary

boolean	alike(TraceLogDescriptor other) Two LogDescriptors are alike iff they refer to the same (canonical) file.
private File	backupFile(File file, int clashAction) Return the file to use as a backup.
(package private) void	describeFutureBackupAction(int clashAction) Say what renameToBackupFile will try to do when it's called by startUsing.
private File	desiredLogFile() Given the current state of this object's fields, construct the file the user wants.
(package private) Object	diverge() A diverge of a TraceLogDescriptor is one that, when startUsing() is called, will use the same descriptor, be it a file or PrintStreamWriter.out().
private boolean	inUse()
(package private) String	printName() Return a name of this descriptor, suitable for printing.
private boolean	renameToBackup(File file, int clashAction) Attempt to rename this file to a backup file with a version number.
(package private) void	setDir(String value) The user wishes to use a directory component different than the default.
(package private) void	setName(String value) If the argument is "-", standard output is used.
(package private) void	setTag(String value) The tag is the initial part of the standard filename.
(package private) void	startUsing(int clashAction) Enables this LogDescriptor for use.
(package private) void	stopUsing() Cease using this LogDescriptor.

Methods inherited from class java.lang.Object

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

Field Detail

initDate

private static final Date initDate

The date this trace system was initialized; used as part of the standard name format.

dir

private File dir

The directory in which the log lives.

tag

private String tag

The 'tag' is the first component of the log filename.

useStdout

private boolean useStdout

Determine whether PrintStreamWriter.out() is used instead of a file.

usePersonalFormat

private boolean usePersonalFormat

True if the user overrode the standard tag.date.txt format.

personalFile

private String personalFile

The file being used for the log, if format chosen by user.

stream

public PrintWriter stream

The stream open to the log. Clients print to this.

stdout

static final TraceLogDescriptor stdout

This log descriptor always represents standard output. It should never be modified. It starts out "not in use".

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

TraceLogDescriptor

TraceLogDescriptor()

Method Detail

backupFile

private File backupFile(File file,
                        int clashAction)

Return the file to use as a backup. Stdout is never backed up, so useStdout should be false.

Parameters:

clashAction - determines which name the backup file will have. ADD means a file with the next highest sequence number. OVERWRITE means a file with the smallest sequence number.

diverge

Object diverge()

A diverge of a TraceLogDescriptor is one that, when startUsing() is called, will use the same descriptor, be it a file or PrintStreamWriter.out(). The diverge is not inUse(), even if what it was cloned from was.

describeFutureBackupAction

void describeFutureBackupAction(int clashAction)

Say what renameToBackupFile will try to do when it's called by startUsing. This is used when the log file will be closed before the renaming is done. It's a way to get some information in the old log file.

desiredLogFile

private File desiredLogFile()

Given the current state of this object's fields, construct the file the user wants. It is a program error to call this routine if the user wants PrintStreamWriter.out(), not a file.

alike

public boolean alike(TraceLogDescriptor other)

Two LogDescriptors are alike iff they refer to the same (canonical) file.

inUse

private boolean inUse()

printName

String printName()

Return a name of this descriptor, suitable for printing. PrintStreamWriter.out() is named "standard output". Real files are named by their canonical pathname (surrounded by single quotes).

Note that the printname may be the absolute pathname if the canonical path could not be discovered (which could happen if the file does not exist.)

renameToBackup

private boolean renameToBackup(File file,
                               int clashAction)

Attempt to rename this file to a backup file with a version number. Returns true iff the rename succeeds. The name of the backup file is constructed by a TraceVersionName, using the current name of the file.

If the backup file does not exist (and can be written), all is fine. Otherwise:

Parameters:

clashAction - is ADD if a new backup file should be added, otherwise OVERWRITE if an existing one should be overwritten.

setDir

void setDir(String value)

The user wishes to use a directory component different than the default. The file used is unchanged.

setName

void setName(String value)

If the argument is "-", standard output is used. If the argument is something else, that becomes the complete filename, overriding the tag, eliminating use of the date/time field, and not using the default extension. It does not affect the directory the file is placed in.

setTag

void setTag(String value)

The tag is the initial part of the standard filename. Setting this implies that the date should be included in the filename.

startUsing

void startUsing(int clashAction)
          throws Exception

Enables this LogDescriptor for use. Most obvious effect is that 'stream' is initialized.

Parameters:

clashAction - determines what to do if the target logfile already exists. The two options are ADD (to add a new backup file) or OVERWRITE (to overwrite an existing one). IRRELEVANT should be used when the destination is known to be standard output, which never clashes.

Throws:

Exception - is thrown if a logfile could not be opened. The contents of the exception are irrelevant, as this method logs the problem.

stopUsing

void stopUsing()

Cease using this LogDescriptor. The most obvious effect is that 'stream' is now null. Behind the scenes, any open file is closed. You can alternate stopUsing() and startUsing() an arbitrary number of times.