|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objecttylerhayes.tools.Log
public class Log
The Log Class defines an object that logs messages to a log file.
The user of the Log object can either specify their own file name and path,
or use the default file name given by the default Constructor
Log()
.
In addition, the user can switch over to a new file during the use of the
Log object, if, for example, the file is growing too large by using the
setFile(String)
method, or the setFileDefault()
method. The latter is if you want the
Log object to create the default file name for you (using the current
directory and current time).
enableStdoutForAll()
and
enableStdoutForErrorsOnly()
methods.
INDICATORS
The Log object writes its messages with indicators. These indicators
are two-character strings that prepend the logged messages to make it easier
to locate certain kinds of messages when reading the log file.
Here is an example of a log file with the message indicators:
CURRENT URL ID: 1347
__ Parsing page contents...
~~ WARNING: server was redirected.
## link found: "http://link"
** ERROR: could not save link in database.
!! FATAL ERROR: IOException caught
General messages: "__"
Error messages: "**"
Fatal error messages: "!!"
Warning messages: "~~"
Data value messages: "##"
Kill message: "XX"
The user can, however, set their own indicator values by calling any of the
set[indicator] methods, such as setDataIndicator(String)
.
The user also has the option of not using indicators at all, in which case
one would call disableIndicators()
. If the user wanted to turn the
use of indicators back on, a call to enableIndicators()
would set the indicators back to whatever they were
before the call to disableIndicators(). There is also the option
of resetting the indicators to their default values with a call to resetIndicators()
.
To use custom indicators, one would call the logGeneralMessageWithoutIndicator(String, int, boolean)
method and simply
include the indicator within the message being passed in.
For example, if one was logging a web crawler and wanted an indicator for
logging every link extracted from each web page, the above method could be
called like so: logObj.logGeneralMessageWithoutIndicator("-> Link
extracted: " + link, 2, true);
, where "-> " is the indicator.
Unfortunately, you will have to include that indicator every time you want
to use it.
Constructor Summary | |
---|---|
Log()
Creates a Log object that writes to a default log file. |
|
Log(java.lang.String fileName)
Creates a Log object that writes to the file given as the parameter, fileName. |
|
Log(java.lang.String fileName,
boolean append)
Creates a Log object that appends to the file given as the parameter, fileName. |
Method Summary | |
---|---|
void |
close()
Properly closes the resources used with the Log object--in this case just a private BufferedWriter object used to write to the specified file. |
void |
close(java.lang.String footerText)
This version of close() takes a String parameter that is passed to logFooter(String) so that a footer is
output to the file before closing. |
void |
disableIndicators()
Turns off the use of message indicators. |
void |
disableStdoutForAll()
Disables the directing of messages to stdout. |
void |
enableIndicators()
Turns the use of indicators back on (they are on by default). |
void |
enableStdoutForAll()
Enables the output of all logged messages (excluding header and footer) to be directed to stdout as well as the log file. |
void |
enableStdoutForErrorsOnly()
Enables the output of error messages to be directed to stdout as well as the log file. |
void |
logData(java.lang.String message,
int tabs,
boolean usingTime)
Logs a data message to the log file. |
void |
logError(java.lang.String message,
int tabs,
boolean usingTime)
Logs an error message to the log file. |
void |
logFatalError(java.lang.String message,
int tabs,
boolean usingTime)
Logs a fatal error message to the log file. |
void |
logFooter(java.lang.String footerText)
Outputs a formatted footer marking the end of a log session. |
void |
logGeneralMessage(java.lang.String message,
int tabs,
boolean usingTime)
Logs a general message to the log file. |
void |
logGeneralMessageWithoutIndicator(java.lang.String message,
int tabs,
boolean usingTime)
Logs a general message to the log file without an indicator. |
void |
logHeader(java.lang.String headerText)
Outputs a formatted header marking the beginning of the log session. |
void |
logKill(int tabs,
boolean usingTime)
Logs that the program has been killed. |
void |
logTimestamp(int tabs)
Logs the current timestamp to the log file. |
void |
logWarning(java.lang.String message,
int tabs,
boolean usingTime)
Logs a warning message to the log file. |
void |
resetIndicators()
Resets the indicator values to the default values: |
void |
setDataIndicator(java.lang.String indicator)
Sets the data message indicator. |
void |
setErrorIndicator(java.lang.String indicator)
Sets the error message indicator. |
void |
setFatalIndicator(java.lang.String indicator)
Sets the fatal error message indicator. |
void |
setFile(java.lang.String fileName)
Sets the Log object to write to the given file. |
void |
setFileAppend(java.lang.String fileName)
Sets the Log object to write to the given file for appending. |
void |
setFileDefault()
Sets the Log object to write to a log file with a default file name. |
void |
setGeneralIndicator(java.lang.String indicator)
Sets the general message indicator. |
void |
setKillIndicator(java.lang.String indicator)
Sets the kill message indicator. |
void |
setTabSize(int size)
Sets the tab size (number of spaces) for message indentation. |
void |
setWarningIndicator(java.lang.String indicator)
Sets the warning message indicator. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public Log()
Example: 8-20-2010_1282332840418.log for a log file created on August 20th, 2010, at around 12:34 pm.
By default, output will only be directed to the log file. If you would
like to also output the log messages to stdout (either all messages, or
only error messages), use the enableStdoutForAll()
or enableStdoutForErrorsOnly()
methods.
public Log(java.lang.String fileName)
If you wish to append to the given file, use the following Constructor,
Log(String, boolean)
.
By default, output will only be directed to the log file. If you would
like to also output the log messages to stdout (either all messages, or
only error messages), use the enableStdoutForAll()
or enableStdoutForErrorsOnly()
methods.
fileName
- A String for the path and filename of the log
file.
Windows example (forward slashes need escaping):
"C:\\dir\\program.log"
Unix/Linux example ('~' means home directory):
"~/logfiles/program.log"
To create the log file in the current directory, just give a name without the system-specific slashes, e.g. "filename.log".
public Log(java.lang.String fileName, boolean append)
By default, output will only be directed to the log file. If you would
like to also output the log messages to stdout (either all messages, or
only error messages), use the enableStdoutForAll()
or enableStdoutForErrorsOnly()
methods.
fileName
- A String for the path and filename of the log
file.append
- A boolean specifying whether or not to append to
the file given as fileName. This should always be true,
because if you do not want to append, then just use the previous
Constructor, Log(String)
.Method Detail |
---|
public void close()
public void close(java.lang.String footerText)
logFooter(String)
so that a footer is
output to the file before closing. This is just a shortcut for having to
call logFooter(String), followed by close()
footerText
- Text to be placed inside the footer block.public void setFile(java.lang.String fileName)
The purpose of these setFile methods is to give the caller the option of switching to a new file, if, for example, the file it was previously writing to was getting substantially large.
fileName
- A String representing the file to write the log
entries to.
NOTE: if the file already exists, the original file will be written over and lost, so be careful.
If you would like to append to a file use the setFileAppend(String)
method. There is also a Constructor to set up the
given file for appending: Log(String, boolean)
.
Log()
,
Log(String)
,
Log(String, boolean)
,
setFileAppend
,
setFileDefault
public void setFileAppend(java.lang.String fileName)
setFile(String)
is that this
method sets the BufferedWriter for appending rather than implicitly
writing over the file if it already exists. If you don't care about
writing over the file, you should just call setFile(String)
.
The purpose of these setFile methods is to give the caller the option of switching to a new file, if, for example, the file it was previously writing to was getting substantially large.
fileName
- A String representing the file to append the log
entries to.
NOTE: there is also a Constructor, Log(String, boolean)
,
that initializes the BufferedWriter for appending.
Log()
,
Log(String)
,
Log(String, boolean)
,
setFile
,
setFileDefault
public void setFileDefault()
Example: 8-20-2010_1282332840418.log for a log file created on August 20th, 2010, at around 12:34 pm.
This is usually only used when the Log object was first constructed with
the default Constructor, Log()
.
The purpose of these setFile methods is to give the caller the option of switching to a new file, if, for example, the file it was previously writing to was getting substantially large.
Log()
,
Log(String)
,
Log(String, boolean)
,
setFile
,
setFileAppend
public void setTabSize(int size)
NOTE: the constructors set the tab size to 4 as the default.
size
- The number of spaces to use for indenting.
NOTE: The tab size will be set to zero for any integer passed in that is less than or equal to zero. On the flip side, 25 is the maximum (although I can't imagine wanting a tab size bigger than 8 or possibly 12), so the tab size will be set to 25 for any integer passed in that is greater than or equal to 25.
public void setGeneralIndicator(java.lang.String indicator)
indicator
- A String representing the message indicator.public void setDataIndicator(java.lang.String indicator)
indicator
- A String representing the message indicator.public void setWarningIndicator(java.lang.String indicator)
indicator
- A String representing the message indicator.public void setErrorIndicator(java.lang.String indicator)
indicator
- A String representing the message indicator.public void setFatalIndicator(java.lang.String indicator)
indicator
- A String representing the message indicator.public void setKillIndicator(java.lang.String indicator)
indicator
- A String representing the message indicator.public void logHeader(java.lang.String headerText)
The header looks like this:
================================================================================
==
{headerText centered}
==
================================================================================
headerText
- Text to be placed inside the header block.logFooter
public void logFooter(java.lang.String footerText)
This is a wrapper for logHeader
.
The footer looks like this:
================================================================================
==
{footerText centered}
==
================================================================================
footerText
- Text to be placed inside the footer block.logHeader
public void logGeneralMessage(java.lang.String message, int tabs, boolean usingTime)
The given message will be prepended by the general message indicator
(indicators are described in the opening description of the Log
Class). If you do not want the indicator to be logged with the
message, you can set it to the empty string ("") by calling
setGeneralIndicator(String)
, disabling all indicators by calling
disableIndicators()
, or, in this case, calling logGeneralMessageWithoutIndicator(String, int, boolean)
.
By default, the indicator for this type of message is "__".
All of these log methods require the number of tabs to indent and whether or not to prepend the entry with a timestamp (in addition to the message itself).
message
- The message to log (following the indicator).tabs
- The number of tabs to indent the message. The indentation
begins after the timestamp if a timestamp is to be included.usingTime
- true will cause a timestamp to be output before
the message, and false will not.public void logGeneralMessageWithoutIndicator(java.lang.String message, int tabs, boolean usingTime)
All of these log methods require the number of tabs to indent and whether or not to prepend the entry with a timestamp (in addition to the message itself).
message
- The message to log.tabs
- The number of tabs to indent the message. The indentation
begins after the timestamp if a timestamp is to be included.usingTime
- true will cause a timestamp to be output before
the message, and false will not.public void logData(java.lang.String message, int tabs, boolean usingTime)
The given message will be prepended by the data message indicator
(indicators are described in the opening description of the Log
Class). If you do not want the indicator to be logged with the
message, you can set it to the empty string ("") by calling
setDataIndicator(String)
, or disabling all indicators by calling
disableIndicators()
.
By default, the indicator for this type of message is "##".
All of these log methods require the number of tabs to indent and whether or not to prepend the entry with a timestamp (in addition to the message itself).
message
- The message to log (following the indicator).tabs
- The number of tabs to indent the message. The indentation
begins after the timestamp if a timestamp is to be included.usingTime
- true will cause a timestamp to be output before
the message, and false will not.public void logWarning(java.lang.String message, int tabs, boolean usingTime)
The given message will be prepended by the warning message indicator
(indicators are described in the opening description of the Log
Class). If you do not want the indicator to be logged with the
message, you can set it to the empty string ("") by calling
setWarningIndicator(String)
, or disabling all indicators by
calling disableIndicators()
.
By default, the indicator for this type of message is "~~".
All of these log methods require the number of tabs to indent and whether or not to prepend the entry with a timestamp (in addition to the message itself).
message
- The message to log (following the indicator).tabs
- The number of tabs to indent the message. The indentation
begins after the timestamp if a timestamp is to be included.usingTime
- true will cause a timestamp to be output before
the message, and false will not.public void logError(java.lang.String message, int tabs, boolean usingTime)
The given message will be prepended by the error message indicator
(indicators are described in the opening description of the Log
Class). If you do not want the indicator to be logged with the
message, you can set it to the empty string ("") by calling
setErrorIndicator(String)
, or disabling all indicators by calling
disableIndicators()
.
By default, the indicator for this type of message is "**".
All of these log methods require the number of tabs to indent and whether or not to prepend the entry with a timestamp (in addition to the message itself).
message
- The message to log (following the indicator).tabs
- The number of tabs to indent the message. The indentation
begins after the timestamp if a timestamp is to be included.usingTime
- true will cause a timestamp to be output before
the message, and false will not.public void logFatalError(java.lang.String message, int tabs, boolean usingTime)
The given message will be prepended by the fatal error message indicator
(indicators are described in the opening description of the
Log Class). If you do not want the indicator to be logged with the
message, you can set it to the empty string ("") by calling
setFatalIndicator(String)
, or disabling all indicators by calling
disableIndicators()
.
By default, the indicator for this type of message is "!!".
All of these log methods require the number of tabs to indent and whether or not to prepend the entry with a timestamp (in addition to the message itself).
message
- The message to log (following the indicator).tabs
- The number of tabs to indent the message. The indentation
begins after the timestamp if a timestamp is to be included.usingTime
- true will cause a timestamp to be output before
the message, and false will not.public void logTimestamp(int tabs)
tabs
- The number of tabs to indent before logging the timestamp.public void logKill(int tabs, boolean usingTime)
Unlike most of the other log methods, this one does not take a String as an argument for a caller-defined message. The kill message is always:
Program has been killed.
and the default indicator is "XX".
tabs
- The number of tabs to indent before logging the kill message.usingTime
- true will cause a timestamp to be output before
the message, and false will not.public void disableIndicators()
enableIndicators
public void enableIndicators()
disableIndicators()
. A call to this before without ever calling
disableIndicators() does nothing (but waste cycles).
public void resetIndicators()
General messages: "__"
Error messages: "**"
Fatal error messages: "!!"
Warning messages: "~~"
Data value messages: "##"
Kill message: "XX"
public void enableStdoutForAll()
NOTE: a client may accidentally enable stdout for both all messages
and error messages by calling both this method and enableStdoutForErrorsOnly()
. Log
does not prevent this from happening. However, doing so does not output
error messages twice--it only has the same effect of this method.
public void enableStdoutForErrorsOnly()
NOTE: a client may accidentally enable stdout for both all messages
and error messages by calling both this method and enableStdoutForAll()
. Log does not prevent
this from happening. However, doing so does not output error messages
twice--it only has the same effect of enableStdoutForAll()
.
public void disableStdoutForAll()
enableStdoutForErrorsOnly()
will do
the job.
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |