|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--grace.log.Log
This implements a logging facility to allow the user to log programmatic context and data to various log devices such as System.out, a file, a GUI, etc. Each entry in the log is called an event. An event captures various data items such as the time, an event type, the program's position, a message, an object, or a Java Exception. The different event types handled by this logging facility are:
Errors are problems that have been detected in the code that are not accompanied by an exception, or exceptions that have occurred and the program has interpreted the exception and has translated it to a higher level error message, or exceptions that have occurred that the programmer does not know how to handle. Errors should be situations where the program is confident that if the problem is not solved, the program may not continue to run. The programmer may indicate an error message as follows:
if (dog == null) Log.error("Unexpected null dog");or,
try { dog.bark(); } catch (SickDogException e) { Log.error(e); }
The programmer may also indicate an object as part of the notification, as follows:
dog.bark(); if (!dog.isBarking()) Log.error("dog won't bark", dog);
Warnings are similar to errors but do not have the same level of severity. They indicate a problem in the system but one that will not affect the immediate health of the program.
if (!dog.isBarking()) { dog.bark(); Log.warning("dog wasn't barking but now he is");
Notices are events that the programmer would like to be logged but that are not warnings or errors and are merely for informational purposes only.
dog = new Dog(); Log.notice("created new dog");
Traces are events used for debugging. They can be eliminated at run time by filtering. Like all other events types, the trace facility fills in the current function and line number in the code so the caller should not provide this in his message.
Log.trace("current dog", dog);
User Defined are events in which the programmer can specify his own event type. There is no difference between the programmer defined types and the defined ones (errors, warnings, notices, traces).
Log.log("statistics", "number-of-dogs=" + numDogs);
Currently, there are only four handlers:
To install a custom handler, one must derive from
grace.log.Handler and install an instance of the Handler using
the addHandler(...)
function.
Various system properties (settable on the command line using the -D option) control the behavior of the logging functions:
log = true|false log.format = event-format log.rc = filename to load instead of local .logrc file log.errors = true|false log.warnings = true|false log.notices = true|false log.traces = true|false log.time.format = short | medium | long | full | 24 | SimpleDateFormat log.time.relative = "clock | days | hours | minutes | seconds" log.time.zone = GMT etc. log.thread.format = thread-format log.message.format = message-format log.exception.format = message-format log.object.format = object-format log.handler.name.url = file://abs | file:rel | rmi:///name | jdbc:protocol:name log.handler.name.class = FileHandler|StandardOutHandler|... log.handler.name.events = error|warnings|... log.handler.name.file = filename (for FileHandler only) log.handler.name.maxsize = 12M | 2K | ... (for FileHandler only) log.function.exclude = "grace.log..* grace.util..*" log.function.include = "grace.log..* grace.util..*" log.event.include = "error warn.*" log.event.exclude = "trace.* notice.*"
log.functions.exclude
are applied against the results of the inclusion filters
likelog.functions.include
.
Field Summary | |
static java.lang.String |
ERROR
Can be passed to log(type, ...) or to enableEvent(type) functions. |
static java.lang.String |
NOTICE
Can be passed to log(type, ...) or to enableEvent(type) functions. |
static java.lang.String |
rcsid
|
static java.lang.String |
TRACE
Can be passed to log(type, ...) or to enableEvent(type) functions. |
static java.lang.String |
WARNING
Can be passed to log(type, ...) or to enableEvent(type) functions. |
Constructor Summary | |
Log()
Logs are constructed internally and usually should not be constructed by the normal user. |
Method Summary | |
void |
addHandler(Handler handler)
Add the given handler into this log such that all subsequent messages will be dispatched to this and all previously installed Handlers. |
void |
addHandler(Handler handler,
java.lang.String event)
Add the given handler into this log such that all subsequent messages of the given event will be dispatched to this and all previously installed Handlers of the given event. |
protected void |
addHandler(java.lang.String name)
Given the name of a handler, this looks up the properties to instantiate and install the correct handler. |
protected void |
addLocalHandler(java.lang.String name,
java.lang.Class defaultHandlerClass)
|
protected void |
addRemoteObject(java.lang.String name,
java.lang.String url)
This is called when a handler is specified as remote using the log.handler property. |
protected void |
addToEventHandlers(Handler handler,
java.lang.String handlerName,
java.lang.String events)
This adds a handler for each event given in the space separated list of events. |
protected void |
checkAndBindDistributer()
This binds the Distributer in the RMI registry if the property is set. |
protected void |
checkAndBindHandler(java.lang.String name,
Handler handler)
This checks to see if the Handler needs to be bound in the RMI registry as a server. |
protected void |
dispatch(Handler handler,
Event event)
This function calls the handler.handle(Event) function. |
void |
distribute(Event event)
This is the heart of the logging. |
static void |
enableErrors(boolean enabled)
Enables or disables the logging of errors. |
void |
enableEventType(java.lang.String eventType,
boolean enabled)
|
static void |
enableNotices(boolean enabled)
Enables or disables the logging of notices. |
static void |
enableTraces(boolean enabled)
Enables or disables the logging of traces. |
static void |
enableWarnings(boolean enabled)
Enables or disables the logging of warnings. |
static void |
error(java.lang.Exception exception)
This function simply logs the given exception to the log device. |
static void |
error(java.lang.String message)
This logs the indicated error message text to the configured log device. |
static void |
error(java.lang.String message,
java.lang.Exception exception)
This logs the given message along with the given exception. |
static void |
error(java.lang.String message,
java.lang.Object object)
This logs the error message and then logs the given object. |
static boolean |
errorsEnabled()
|
protected boolean |
eventFieldIsInteresting(java.lang.String text,
java.util.Vector includeFilter,
java.util.Vector excludeFilter)
This applies the filters against the given text. |
protected boolean |
eventIsInteresting(Event event)
Indicates that the given event should be included in the log based on whether the function from which the event was generated matches the filters. |
boolean |
eventTypeEnabled(java.lang.String type)
Indicates that the given event type should be included in the log. |
static Log |
getInstance()
Used to staticly access the singleton log instance. |
java.lang.String |
getName()
This returns the name of this log/distributer. |
Properties |
getProperties()
Returns the properties list that is statically maintained by this class. |
protected void |
initialize()
Initializes all of the elements of a Log/Distributer object. |
void |
initializeFilters()
This loads the properties and sets up the filters for including and excluding functions and event types. |
static void |
internal(java.lang.Exception e)
This function is a very simple way to output a log exceptions without using any of the log dispatching or handling. |
static void |
internal(java.lang.String message)
This function is a very simple way to output a log message without using any of the log dispatching or handling. |
void |
loadProperties(java.util.Properties extraProperties)
Loads the given set of extraProperties without affecting the System properties or the original properties maintained by this Log. |
static void |
log(java.lang.String eventType,
java.lang.Object object)
Logs the given object marked with the given eventType. |
static void |
log(java.lang.String eventType,
java.lang.String message)
Logs the given message marked with the given event type. |
static void |
log(java.lang.String eventType,
java.lang.String message,
java.lang.Object object)
Logs the given message and object marked with the given eventType. |
protected void |
lookupFilterAndAddHandler(Handler handler,
java.lang.String name)
This takes the given handler and handler name and looks up a list of events to which this handler should respond and then installs the handler. |
static void |
main(java.lang.String[] args)
This main acts as a little test program to test many of the features of the Log. |
static void |
notice(java.lang.String message)
This logs the indicated notice message text to the configured log device. |
static void |
notice(java.lang.String message,
java.lang.Object object)
This logs the indicated notice message text and the given object to the configured log device. |
static boolean |
noticesEnabled()
|
protected void |
removeHandler(Handler toRemove)
This removes the given handler from all of the handlers - allHandlers and eventHandlers. |
protected void |
removeObjectFrom(java.util.Hashtable table,
java.lang.Object toRemove)
This removes an object from a hashtable. |
protected static java.lang.String |
replaceBadPunctuation(java.lang.String source)
This returns a copy of the given string with all puntuation that is offensive to rmi URLs replaced by dots. |
void |
setEventTypesToExclude(java.lang.String filters)
Sets the given space separated list of regular expressions that will act as filters to exclude event types in the logging output. |
void |
setEventTypesToInclude(java.lang.String filters)
Sets the given space separated list of regular expressions that will act as filters to include event types in the logging output. |
void |
setFunctionNamesToExclude(java.lang.String filters)
Sets the given space separated list of regular expressions that will act as filters to exclude functions in the logging output. |
void |
setFunctionNamesToInclude(java.lang.String filters)
Sets the given space separated list of regular expressions that will act as filters to include functions in the logging output. |
void |
setName(java.lang.String name)
This overrides the default use of the VMID and sets the name of this log. |
static void |
trace()
This function makes an entry in the log device that indicates the programtic position of the caller. |
static void |
trace(java.lang.Object object)
This function writes the given object in the log device and makes an entry in the log device that indicates the programtic position of the caller. |
static void |
trace(java.lang.String message)
This function writes the given message in the log device and makes an entry in the log device that indicates the programtic position of the caller. |
static void |
trace(java.lang.String message,
java.lang.Object object)
This function writes the given message and object in the log device and makes an entry in the log device that indicates the programtic position of the caller. |
static boolean |
tracesEnabled()
|
protected java.lang.String |
virtualMachineId()
Returns the virtual machine id as determined by java.rmi.dgc.VMID but with all of the colons replaced by dots. |
static void |
warning(java.lang.String message)
This logs the indicated warning message text to the configured log device. |
static void |
warning(java.lang.String message,
java.lang.Exception exception)
This logs the indicated warning message text and give exception to the configured log device. |
static void |
warning(java.lang.String message,
java.lang.Object object)
This logs the indicated warning message text and object to the configured log device. |
static boolean |
warningsEnabled()
|
Methods inherited from class java.lang.Object |
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait |
Field Detail |
public static final java.lang.String rcsid
public static final java.lang.String ERROR
public static final java.lang.String WARNING
public static final java.lang.String NOTICE
public static final java.lang.String TRACE
Constructor Detail |
public Log()
Method Detail |
public static Log getInstance()
public static void log(java.lang.String eventType, java.lang.String message)
eventType
- user defined classification of log messagemessage
- free form user message to logpublic static void log(java.lang.String eventType, java.lang.Object object)
eventType
- user defined classification of log messageobject
- object to logpublic static void log(java.lang.String eventType, java.lang.String message, java.lang.Object object)
eventType
- user defined classification of log messagemessage
- free form user message to logobject
- object to logpublic static void error(java.lang.String message)
Error messages should indicate a grave condition in which the programmer can not anticipate the integrity of the running system.
message
- to be logged to the log devicepublic static void error(java.lang.String message, java.lang.Object object)
Error messages should indicate a grave condition in which the programmer can not anticipate the integrity of the running system.
message
- to be logged to the log deviceobject
- to be logged to log device in implementation
specific manner.public static void error(java.lang.Exception exception)
Error messages should indicate a grave condition in which the programmer can not anticipate the integrity of the running system.
object
- to be logged to log device in implementation
specific manner.public static void error(java.lang.String message, java.lang.Exception exception)
Error messages should indicate a grave condition in which the programmer can not anticipate the integrity of the running system.
public static void warning(java.lang.String message)
Warning messages should indicate a problem in the system but one which the programmer expects will not affect the immediate integrity of the running system.
message
- to logpublic static void warning(java.lang.String message, java.lang.Object object)
Warning messages should indicate a problem in the system but one which the programmer expects will not affect the immediate integrity of the running system.
message
- to logpublic static void warning(java.lang.String message, java.lang.Exception exception)
Warning messages should indicate a problem in the system but one which the programmer expects will not affect the immediate integrity of the running system.
message
- to be loggedexception
- to be loggedpublic static void notice(java.lang.String message)
Notices messages should be used to communicate situations that have developed that are part of the normal operation of the system. This is equivalent to calling the log function with "notice" as the event type.
message
- to logpublic static void notice(java.lang.String message, java.lang.Object object)
Notices messages should be used to communicate situations that have developed that are part of the normal operation of the system.
message
- to logobject
- to log in implementation specific formatpublic static void trace()
public static void trace(java.lang.String message)
message
- to logpublic static void trace(java.lang.Object object)
object
- to log in implementation specific mannerpublic static void trace(java.lang.String message, java.lang.Object object)
message
- to logobject
- to log in implementation specific mannerpublic static void internal(java.lang.String message)
public static void internal(java.lang.Exception e)
public java.lang.String getName()
The property log.name can be used to override the use of the VMID and use the user supplied name as a prefix with the sequence number.
public void setName(java.lang.String name)
protected java.lang.String virtualMachineId()
protected static java.lang.String replaceBadPunctuation(java.lang.String source)
protected void dispatch(Handler handler, Event event)
handler
- to call the handle function for the eventevent
- to pass to the handle functionprotected void removeHandler(Handler toRemove)
protected void removeObjectFrom(java.util.Hashtable table, java.lang.Object toRemove)
public void distribute(Event event)
event
- to logprotected boolean eventIsInteresting(Event event)
protected boolean eventFieldIsInteresting(java.lang.String text, java.util.Vector includeFilter, java.util.Vector excludeFilter)
text
- to include/exclude using filtersincludeFilter
- VectorexcludeFilter
- Vectorpublic static void enableErrors(boolean enabled)
public static boolean errorsEnabled()
public static void enableWarnings(boolean enabled)
public static boolean warningsEnabled()
public static void enableNotices(boolean enabled)
public static boolean noticesEnabled()
public static void enableTraces(boolean enabled)
public static boolean tracesEnabled()
public void enableEventType(java.lang.String eventType, boolean enabled)
public boolean eventTypeEnabled(java.lang.String type)
public void addHandler(Handler handler)
public void addHandler(Handler handler, java.lang.String event)
protected void addToEventHandlers(Handler handler, java.lang.String handlerName, java.lang.String events)
protected void addHandler(java.lang.String name)
protected void addLocalHandler(java.lang.String name, java.lang.Class defaultHandlerClass)
protected void checkAndBindHandler(java.lang.String name, Handler handler)
property log.handler.name.server true|false false
installs the named handler in the RMI registry with the key
"log.handler.name.vmid".
name
- name of handler to bindhandler
- to bind
protected void checkAndBindDistributer()
protected void addRemoteObject(java.lang.String name, java.lang.String url)
protected void lookupFilterAndAddHandler(Handler handler, java.lang.String name)
public void setFunctionNamesToInclude(java.lang.String filters)
Calling this function overrides any values specified in the property "log.function.include".
Note, the include list is processed before the exclude list. This means any event included by this filter can be subsequently excluded by the exclude list.
Some useful expressions are:
filters
- space separated list of regular expressionspublic void setFunctionNamesToExclude(java.lang.String filters)
Calling this function overrides any values specified in the property "log.function.exclude".
Note, the exclude list is processed after the include list. This means that this filter has the utlitimate decision of whether the event is distributed.
Some useful expressions are:
filters
- space separated list of regular expressionspublic void setEventTypesToInclude(java.lang.String filters)
Calling this function overrides any values specified in the property "log.event.include".
Note, the include list is processed before the exclude list. This means any event included by this filter can be subsequently excluded by the exclude list.
Some useful expressions are:
filters
- space separated list of regular expressionspublic void setEventTypesToExclude(java.lang.String filters)
Calling this function overrides any values specified in the property "log.event.exclude".
Note, the exclude list is processed after the include list. This means that this filter has the utlitimate decision of whether the event is distributed.
filters
- space separated list of regular expressionspublic Properties getProperties()
public void loadProperties(java.util.Properties extraProperties)
extraProperties
- to merge into the current setpublic void initializeFilters()
protected void initialize()
public static void main(java.lang.String[] args)
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |