com.cisco.services.tracing
Class LogFileTraceWriter

java.lang.Object
  extended by com.cisco.services.tracing.BaseTraceWriter
      extended by com.cisco.services.tracing.LogFileTraceWriter
All Implemented Interfaces:
TraceWriter

public final class LogFileTraceWriter
extends BaseTraceWriter

Introduction

This class extends the BaseTraceWriter class to implement a TraceWriter that writes to a set of log files, rotating among them as each becomes filled to a specified capacity and stores them in a specified directory.

Each of the log files is named according to a pattern controlled by three properties, CurrentFile, FileNameBase, and FileExtension. The CurrentFile property determines which log file, by ordinal number, is being written at present, the FileNameBase property determines the prefix of each log file name, and the FileExtension property determines the suffix, e.g. "txt". From these properties, log files are named FileNameBase LeadingZeroPadding CurrentFile.FileExtension. The CurrentFile property takes on a value from 1 to the value of the MaxFiles property. Note that the CurrentFile property, when converted to a String, is padded with leading zeroes depending on the values of the MaxFiles and CurrentFile properties. An index file tracks the index of the last file written. If the logFileWriter is recreated (for example if an application is restarted) new files will continue from the last written index.

Where the log files are stored is determined by the path, dirNameBase, useSameDir. If a path is not specified, the current path is used as default. If a dirNameBase is not specified, it write log files in the path. Depending upon whether useSameDir is true or false, files are written to the same directory or a new directory, each time an instance of LogFileTraceWriter is created. In case new directories are being made each time, the directory name will consist of the dirNameBase and a number, seperated by an '_'. The number is one more than the greatest number associated with directories with the same dirNameBame in the path. While specifying the path, you may use either a "/" or "\\", but not "\"

The LogFileTraceWriter keeps track of how many bytes have been written to the current log file. When that number grows within approximately LogFileTraceWriter.ROLLOVER_THRESHOLD bytes, tracing continues to the next file, which is either CurrentFile + 1 if CurrentFile is not equal to MaxFiles, or 1 if CurrentFile is equal to MaxFiles.

Note: All properties of this class are specified in the constructor; there is no way to change them dynamically. Caveat: If two instances of LogFileTraceWriter are created with the same path and dirNameBase, and useSameDir is true, they may write to the same file.

Example

The following code instantiates a LogFileTraceWriter that will create log files called "MyLog01.log" through "MyLog12.log". Each file will grow to approximately 100K bytes in size before the next file is created:

LogFileTraceWriter out = new LogFileTraceWriter ( "MyLog", "log", 12, 100 * 1024 ); will create a log file TraceWriter which will rotate traces to 12 files from Mylog01.log and Mylog12.log with a file size of 100 KBytes. By default the tracing is set to the HIGHEST_LEVEL

Example

The following code constructs a LogFileTraceWriter which stores the log files in the path "c:/LogFiles" in a sub directory, "Run". The files will be named MyLogXX.log. The number of rotating files will be 12 with a size of 100 KB. The same directory is used for each instance of the application.

LogFileTraceWriter out = new LogFileTraceWriter ( "c:/logFiles", "Run", "MyLog", "log", 12, 100*1024, true );

See Also:
Trace

Field Summary
static java.lang.String DEFAULT_FILE_NAME_BASE
           
static java.lang.String DEFAULT_FILE_NAME_EXTENSION
           
static char DIR_BASE_NAME_NUM_SEPERATOR
           
static int MIN_FILE_SIZE
           
static int MIN_FILES
           
static int ROLLOVER_THRESHOLD
           
 
Constructor Summary
LogFileTraceWriter(java.lang.String fileNameBase, java.lang.String fileNameExtension, int maxFiles, int maxFileSize)
          Default constructor for LogFileTraceWriter that rotates among an arbitrary number of files with tracing for all levels.
LogFileTraceWriter(java.lang.String path, java.lang.String dirNameBase, java.lang.String fileNameBase, java.lang.String fileNameExtension, int maxFiles, int maxFileSize, boolean useSameDir)
          Default constructor for LogFileTraceWriter that rotates among an arbitrary number of files with tracing for all levels.
LogFileTraceWriter(java.lang.String path, java.lang.String dirNameBase, java.lang.String fileNameBase, java.lang.String fileNameExtension, int maxFiles, int maxFileSize, int maxTraceLevel, boolean useSameDir)
          Constructs a LogFileTraceWriter that rotates among an arbitrary number of files storing them in a specified directory.
 
Method Summary
protected  void doClose()
          Closes this OutputStream.
protected  void doFlush()
           
protected  void doPrintln(java.lang.String message, int messageNumber)
          Must be implemented by the various TraceWriters extending BaseTraceWriter to provide the specific tracing functionality
 int getCurrentFile()
          Returns the CurrentFile property
 java.lang.String getFileExtension()
          Returns the FileExtension property
 java.lang.String getFileNameBase()
          Returns the FileNameBase property
 java.lang.String getHeader()
          Get the header string that will be written at the beginning of each log file.
 int getMaxFiles()
          Returns the MaxFiles property
 int getMaxFileSize()
          Returns the MaxFileSize property
 void setHeader(java.lang.String header)
          Set the constant header string that will be written at the beginning of every file, trace writing continues from the next line after the header is written.
 void setMaxFiles(int num)
           
 void setMaxFileSize(int size)
           
 
Methods inherited from class com.cisco.services.tracing.BaseTraceWriter
close, flush, getDescription, getEnabled, getName, getTraceLevels, println, setTraceLevels, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

ROLLOVER_THRESHOLD

public static final int ROLLOVER_THRESHOLD
See Also:
Constant Field Values

MIN_FILES

public static final int MIN_FILES
See Also:
Constant Field Values

MIN_FILE_SIZE

public static final int MIN_FILE_SIZE
See Also:
Constant Field Values

DIR_BASE_NAME_NUM_SEPERATOR

public static final char DIR_BASE_NAME_NUM_SEPERATOR
See Also:
Constant Field Values

DEFAULT_FILE_NAME_BASE

public static final java.lang.String DEFAULT_FILE_NAME_BASE
See Also:
Constant Field Values

DEFAULT_FILE_NAME_EXTENSION

public static final java.lang.String DEFAULT_FILE_NAME_EXTENSION
See Also:
Constant Field Values
Constructor Detail

LogFileTraceWriter

public LogFileTraceWriter(java.lang.String fileNameBase,
                          java.lang.String fileNameExtension,
                          int maxFiles,
                          int maxFileSize)
                   throws java.io.IOException
Default constructor for LogFileTraceWriter that rotates among an arbitrary number of files with tracing for all levels. Since a path and Directory Base name is not specified, it writes the files to the current directory without any sub directories.

Parameters:
fileNameBase -
fileNameExtension -
maxFiles -
maxFileSize -
Throws:
java.io.IOException

LogFileTraceWriter

public LogFileTraceWriter(java.lang.String path,
                          java.lang.String dirNameBase,
                          java.lang.String fileNameBase,
                          java.lang.String fileNameExtension,
                          int maxFiles,
                          int maxFileSize,
                          boolean useSameDir)
                   throws java.io.IOException
Default constructor for LogFileTraceWriter that rotates among an arbitrary number of files with tracing for all levels.

Parameters:
path -
dirNameBase -
fileNameBase -
fileNameExtension -
maxFiles -
maxFileSize -
useSameDir -
Throws:
java.io.IOException

LogFileTraceWriter

public LogFileTraceWriter(java.lang.String path,
                          java.lang.String dirNameBase,
                          java.lang.String fileNameBase,
                          java.lang.String fileNameExtension,
                          int maxFiles,
                          int maxFileSize,
                          int maxTraceLevel,
                          boolean useSameDir)
                   throws java.io.IOException
Constructs a LogFileTraceWriter that rotates among an arbitrary number of files storing them in a specified directory.

Parameters:
path -
dirNameBase -
fileNameBase -
fileNameExtension -
maxFiles -
maxFileSize -
maxTraceLevel -
useSameDir -
Throws:
java.io.IOException
Method Detail

doClose

protected void doClose()
Closes this OutputStream. Any log file that is currently open will be closed as well.

Overrides:
doClose in class BaseTraceWriter

doFlush

protected void doFlush()
Overrides:
doFlush in class BaseTraceWriter

doPrintln

protected void doPrintln(java.lang.String message,
                         int messageNumber)
Description copied from class: BaseTraceWriter
Must be implemented by the various TraceWriters extending BaseTraceWriter to provide the specific tracing functionality

Specified by:
doPrintln in class BaseTraceWriter

getFileNameBase

public java.lang.String getFileNameBase()
Returns the FileNameBase property

Returns:
the FileNameBase property

getFileExtension

public java.lang.String getFileExtension()
Returns the FileExtension property

Returns:
the FileExtension property

getMaxFiles

public int getMaxFiles()
Returns the MaxFiles property

Returns:
the MaxFiles property

setMaxFiles

public void setMaxFiles(int num)

getMaxFileSize

public int getMaxFileSize()
Returns the MaxFileSize property

Returns:
the MaxFileSize property

setMaxFileSize

public void setMaxFileSize(int size)

getCurrentFile

public int getCurrentFile()
Returns the CurrentFile property

Returns:
the CurrentFile property

setHeader

public void setHeader(java.lang.String header)
Set the constant header string that will be written at the beginning of every file, trace writing continues from the next line after the header is written. If setHeader is called after a file output has started, it will take effect from the next file to be written. Usage:
 tm = TraceManagerFactory.registerModule(this);
 tw = new LogFileTraceWriter("trace", "log", 10, 1024 * 1024);
 tw.setHeader(header);
 tm.getTraceWriterManager().addTraceWriter(tw);
 

Parameters:
header -

getHeader

public java.lang.String getHeader()
Get the header string that will be written at the beginning of each log file.

Returns:
the Header Property