|
Log4j 1.1b7 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--org.apache.log4j.Category
This is the central class in the log4j package. One of the distintive features of log4j are hierarchical categories and their evaluation.
See the user manual for an introduction on this class.
Field Summary | |
protected boolean |
additive
Additivity is set to true by default, that is children inherit the appenders of their ancestors by default. |
static String |
DEFAULT_CONFIGURATION_FILE
This string constant is set to log4j.properties the name of the file that will be searched by default in classpath. |
static String |
DEFAULT_CONFIGURATION_KEY
This string constant is set to log4j.configuration. |
static String |
DEFAULT_INIT_OVERRIDE_KEY
Setting the system property log4j.defaultInitOverride to "true" or any other value than "false" will skip default configuration process. |
static Hierarchy |
defaultHierarchy
The hierarchy where categories are attached to by default. |
protected Hierarchy |
hierarchy
|
protected String |
name
The name of this category. |
protected Category |
parent
The parent of this category. |
protected Priority |
priority
The assigned priority of this category. |
protected ResourceBundle |
resourceBundle
|
Constructor Summary | |
protected |
Category(String name)
This constructor created a new Category instance and
sets its name.
|
Method Summary | |
void |
addAppender(Appender newAppender)
Add newAppender to the list of appenders of this
Category instance.
|
void |
assert(boolean assertion,
String msg)
If assertion parameter is false , then
logs msg as an error statement. |
void |
callAppenders(LoggingEvent event)
Call the appenders in the hierrachy starting at this . |
void |
debug(Object message)
Log a message object with the DEBUG priority.
|
void |
debug(Object message,
Throwable t)
Log a message object with the DEBUG priority including
the stack trace of the Throwable t passed as
parameter.
|
void |
error(Object message)
Log a message object with the ERROR priority.
|
void |
error(Object message,
Throwable t)
Log a message object with the ERROR priority including
the stack trace of the Throwable t passed as
parameter.
|
static Category |
exists(String name)
If the named category exists (in the default hierarchy) then it returns a reference to the category, otherwise it returns null .
|
void |
fatal(Object message)
Log a message object with the FATAL priority.
|
void |
fatal(Object message,
Throwable t)
Log a message object with the FATAL priority including
the stack trace of the Throwable t passed as
parameter.
|
protected void |
forcedLog(String fqcn,
Priority priority,
Object message,
Throwable t)
This method creates a new logging event and logs the event without further checks. |
boolean |
getAdditivity()
Get the additivity flag for this Category instance. |
Enumeration |
getAllAppenders()
Get the appenders contained in this category as an Enumeration . |
Appender |
getAppender(String name)
Look for the appender named as name .
|
Priority |
getChainedPriority()
Starting from this category, search the category hierarchy for a non-null priority and return it. |
static Enumeration |
getCurrentCategories()
Returns all the currently defined categories in the default hierarchy as an Enumeration .
|
static Hierarchy |
getDefaultHierarchy()
Return the default Hierarchy instance. |
Hierarchy |
getHierarchy()
Return the the Hierarchy where this Category instance is
attached. |
static Category |
getInstance(Class clazz)
Shorthand for getInstance(clazz.getName()) . |
static Category |
getInstance(String name)
Retrieve a category with named as the name
parameter. |
static Category |
getInstance(String name,
CategoryFactory factory)
Like getInstance(String) except that the type of category
instantiated depends on the type returned by the CategoryFactory.makeNewCategoryInstance(java.lang.String) method of the
factory parameter.
|
String |
getName()
Return the category name. |
Priority |
getPriority()
Returns the assigned Priority , if any, for this Category. |
ResourceBundle |
getResourceBundle()
Return the ResourceBundle for this category.
|
protected String |
getResourceBundleString(String key)
|
static Category |
getRoot()
Return the root of the default category hierrachy. |
void |
info(Object message)
Log a message object with the INFO priority.
|
void |
info(Object message,
Throwable t)
Log a message object with the INFO priority including
the stack trace of the Throwable t passed as
parameter.
|
boolean |
isDebugEnabled()
Check whether this category is enabled for the DEBUG
priority.
|
boolean |
isEnabledFor(Priority priority)
Check whether this category is enabled for a given Priority passed as parameter.
|
boolean |
isInfoEnabled()
Check whether this category is enabled for the info priority. |
void |
l7dlog(Priority priority,
String key,
Object[] params,
Throwable t)
Log a localized and parameterized message. |
void |
l7dlog(Priority priority,
String key,
Throwable t)
Log a localized message. |
void |
log(Priority priority,
Object message)
This generic form is intended to be used by wrappers. |
void |
log(Priority priority,
Object message,
Throwable t)
This generic form is intended to be used by wrappers. |
void |
log(String callerFQCN,
Priority priority,
Object message,
Throwable t)
This is the most generic printing method. |
void |
removeAllAppenders()
Remove all previously added appenders from this Category instance. |
void |
removeAppender(Appender appender)
Remove the appender passed as parameter form the list of appenders. |
void |
removeAppender(String name)
Remove the appender with the name passed as parameter form the list of appenders. |
void |
setAdditivity(boolean additive)
Set the additivity flag for this Category instance. |
void |
setPriority(Priority priority)
Set the priority of this Category. |
void |
setResourceBundle(ResourceBundle bundle)
Set the resource bundle to be used with localized logging methods l7dlog(Priority,String,Throwable) and l7dlog(Priority,String,Object[],Throwable) . |
static void |
shutdown()
Calling this method will safely close and remove all appenders in all the categories including root contained in the default hierachy. |
void |
warn(Object message)
Log a message object with the WARN priority.
|
void |
warn(Object message,
Throwable t)
Log a message with the WARN priority including the
stack trace of the Throwable t passed as
parameter.
|
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static final Hierarchy defaultHierarchy
public static final String DEFAULT_CONFIGURATION_FILE
PropertyConfigurator
.
See also DEFAULT_CONFIGURATION_KEY
for a more general
alternative.
See also the full description of default intialization procedure.
public static final String DEFAULT_CONFIGURATION_KEY
It corresponds to name of a system property that, if set,
specifies the name of the resource containing the properties file
or URL
with which log4j should configure itself. See
OptionConverter.selectAndConfigure(java.net.URL, org.apache.log4j.Hierarchy)
for more detailed
information on the processing of this option.
Setting the log4j.configuration system property overrides the default search for the file log4j.properties.
Note that all property keys are case sensitive.
See also the full description of default intialization procedure.
public static final String DEFAULT_INIT_OVERRIDE_KEY
The current value of the DEFAULT_INIT_OVERRIDE_KEY string constant is log4j.defaultInitOverride.
See also the full description of default intialization procedure.
Note that all property keys are case sensitive.
protected String name
protected volatile Priority priority
priority
variable need not be assined a value in
which case it is inherited form the hierarchy.protected volatile Category parent
protected ResourceBundle resourceBundle
protected Hierarchy hierarchy
protected boolean additive
false
then the appenders found in the
ancestors of this category are not used. However, the children
of this category will inherit its appenders, unless the children
have their additivity flag set to false
too. See
the user manual for more details.Constructor Detail |
protected Category(String name)
Category
instance and
sets its name.
It is intended to be used by sub-classes only. You should not create categories directly.
name
- The name of the category.Method Detail |
public void addAppender(Appender newAppender)
newAppender
to the list of appenders of this
Category instance.
If newAppender
is already in the list of
appenders, then it won't be added again.
addAppender
in interface AppenderAttachable
public void assert(boolean assertion, String msg)
assertion
parameter is false
, then
logs msg
as an error
statement.assertion
- msg
- The message to print if assertion
is
false.public void callAppenders(LoggingEvent event)
this
. If no appenders could be found, emit a
warning.
This method calls all the appenders inherited from the hierarchy circumventing any evaluation of whether to log or not to log the particular log request.
LoggingEvent
- the event to log.public void debug(Object message)
DEBUG
priority.
This method first checks if this category is DEBUG
enabled by comparing the priority of this category with the DEBUG
priority. If this category is
DEBUG
enabled, then it converts the message object
(passed as parameter) to a string by invoking the appropriate
ObjectRenderer
. It then proceeds to call all the
registered appenders in this category and also higher in the
hierarchy depending on the value of the additivity flag.
WARNING Note that passing a Throwable
to this
method will print the name of the Throwable
but no
stack trace. To print a stack trace use the debug(Object,
Throwable)
form instead.
message
- the message object to log.public void debug(Object message, Throwable t)
DEBUG
priority including
the stack trace of the Throwable
t
passed as
parameter.
See debug(Object)
form for more detailed information.
message
- the message object to log.t
- the exception to log, including its stack trace.public void error(Object message)
ERROR
priority.
This method first checks if this category is ERROR
enabled by comparing the priority of this category with ERROR
priority. If this category is
ERROR
enabled, then it converts the message object
passed as parameter to a string by invoking the appropriate ObjectRenderer
. It proceeds to call all the registered appenders
in this category and also higher in the hierarchy depending on
the value of the additivity flag.
WARNING Note that passing a Throwable
to this
method will print the name of the Throwable
but no
stack trace. To print a stack trace use the error(Object,
Throwable)
form instead.
message
- the message object to logpublic void error(Object message, Throwable t)
ERROR
priority including
the stack trace of the Throwable
t
passed as
parameter.
See error(Object)
form for more detailed information.
message
- the message object to log.t
- the exception to log, including its stack trace.public static Category exists(String name)
null
.
Contributed by Ciaran Treanor - ciaran@xelector.com
public void fatal(Object message)
FATAL
priority.
This method first checks if this category is FATAL
enabled by comparing the priority of this category with FATAL
priority. If the category is FATAL
enabled, then it converts the message object passed as parameter
to a string by invoking the appropriate ObjectRenderer
. It
proceeds to call all the registered appenders in this category and
also higher in the hierarchy depending on the value of the
additivity flag.
WARNING Note that passing a Throwable
to this
method will print the name of the Throwable but no stack trace. To
print a stack trace use the fatal(Object, Throwable)
form
instead.
message
- the message object to logpublic void fatal(Object message, Throwable t)
FATAL
priority including
the stack trace of the Throwable
t
passed as
parameter.
See fatal(Object)
for more detailed information.
message
- the message object to log.t
- the exception to log, including its stack trace.protected void forcedLog(String fqcn, Priority priority, Object message, Throwable t)
public boolean getAdditivity()
public Enumeration getAllAppenders()
Enumeration
. If no appenders can be found, then a NullEnumeration
is returned.getAllAppenders
in interface AppenderAttachable
public Appender getAppender(String name)
name
.
Return the appender with that name if in the list. Return
null
otherwise.
getAppender
in interface AppenderAttachable
public Priority getChainedPriority()
The Category class is designed so that this method executes as quickly as possible.
public static Enumeration getCurrentCategories()
Enumeration
.
The root category is not included in the returned
Enumeration
.
public static Hierarchy getDefaultHierarchy()
public Hierarchy getHierarchy()
Hierarchy
where this Category
instance is
attached.public static Category getInstance(String name)
name
parameter. If the named category already exists, then the
existing instance will be reutrned. Otherwise, a new instance is
created.
By default, categories do not have a set priority but inherit
it from the hierarchy. This is one of the central features of
log4j.name
- The name of the category to retrieve.public static Category getInstance(Class clazz)
getInstance(clazz.getName())
.clazz
- The name of clazz
will be used as the
name of the category to retrieve. See getInstance(String)
for more detailed information.public static Category getInstance(String name, CategoryFactory factory)
getInstance(String)
except that the type of category
instantiated depends on the type returned by the CategoryFactory.makeNewCategoryInstance(java.lang.String)
method of the
factory
parameter.
This method is intended to be used by sub-classes.
name
- The name of the category to retrieve.factory
- A CategoryFactory
implementation that will
actually create a new Instance.public final String getName()
public final Priority getPriority()
Priority
, if any, for this Category.null
.public static final Category getRoot()
The root category is always instantiated and available. It's name is "root".
Nevertheless, calling Category.getInstance("root")
does not retrieve the root category
but a category just under root named "root".
public ResourceBundle getResourceBundle()
ResourceBundle
for this category.
This method walks the hierarchy to find the appropriate resource bundle.
In case there is no bundle in the hierarchy then
null
is returned.
protected String getResourceBundleString(String key)
public void info(Object message)
INFO
priority.
This method first checks if this category is INFO
enabled by comparing the priority of this category with INFO
priority. If the category is INFO
enabled, then it converts the message object passed as parameter
to a string by invoking the appropriate ObjectRenderer
. It
proceeds to call all the registered appenders in this category and
also higher in the hierarchy depending on the value of the
additivity flag.
WARNING Note that passing a Throwable
to this
method will print the name of the Throwable but no stack trace. To
print a stack trace use the info(Object, Throwable)
form
instead.
message
- the message object to logpublic void info(Object message, Throwable t)
INFO
priority including
the stack trace of the Throwable
t
passed as
parameter.
See info(Object)
for more detailed information.
message
- the message object to log.t
- the exception to log, including its stack trace.public boolean isDebugEnabled()
DEBUG
priority.
This function is intended to lessen the computational cost of disabled log debug statements.
For some cat
Category object, when you write,
cat.debug("This is entry number: " + i );
You incur the cost constructing the message, concatenatiion in this case, regardless of whether the message is logged or not.
If you are worried about speed, then you should write
if(cat.isDebugEnabled()) { cat.debug("This is entry number: " + i ); }
This way you will not incur the cost of parameter construction
if debugging is disabled for cat
. On the other hand,
if the cat
is debug enabled, you will incur the cost
of evaluating whether the category is debug enabled twice. Once
in isDebugEnabled
and once in the
debug
. This is an insignificant overhead since
evaluating a category takes about 1% of the time it takes to
actually log.
true
if this category is debug
enabled, false
otherwise.public boolean isEnabledFor(Priority priority)
Priority
passed as parameter.
See also isDebugEnabled()
.priority
.public boolean isInfoEnabled()
isDebugEnabled()
.true
if this category is enabled
for priority info, false
otherwise.public void l7dlog(Priority priority, String key, Throwable t)
key
is replaced by its localized version from the
resource bundle.setResourceBundle(java.util.ResourceBundle)
public void l7dlog(Priority priority, String key, Object[] params, Throwable t)
key
is searched in the resource
bundle. Next, the resulting pattern is formatted using
MessageFormat.format(String,Object[])
method with the user
supplied object array params
.public void log(Priority priority, Object message, Throwable t)
public void log(Priority priority, Object message)
public void log(String callerFQCN, Priority priority, Object message, Throwable t)
callerFQCN
- The wrapper class' fully qualified class name.priority
- The priority of the logging request.message
- The message of the logging request.t
- The throwable of the logging request, may be null.public void removeAllAppenders()
This is useful when re-reading configuration information.
removeAllAppenders
in interface AppenderAttachable
public void removeAppender(Appender appender)
removeAppender
in interface AppenderAttachable
public void removeAppender(String name)
removeAppender
in interface AppenderAttachable
public void setAdditivity(boolean additive)
public void setPriority(Priority priority)
Null values are admitted.
public void setResourceBundle(ResourceBundle bundle)
l7dlog(Priority,String,Throwable)
and l7dlog(Priority,String,Object[],Throwable)
.public static void shutdown()
Some appenders such as SocketAppender
and AsyncAppender
need to be closed before the
application exists. Otherwise, pending logging events might be
lost.
The shutdown
method is careful to close nested
appenders before closing regular appenders. This is allows
configurations where a regular appender is attached to a category
and again to a nested appender.
public void warn(Object message)
WARN
priority.
This method first checks if this category is WARN
enabled by comparing the priority of this category with WARN
priority. If the category is WARN
enabled, then it converts the message object passed as parameter
to a string by invoking the appropriate ObjectRenderer
. It
proceeds to call all the registered appenders in this category and
also higher in the hieararchy depending on the value of the
additivity flag.
WARNING Note that passing a Throwable
to this
method will print the name of the Throwable but no stack trace. To
print a stack trace use the warn(Object, Throwable)
form
instead.
message
- the message object to log.public void warn(Object message, Throwable t)
WARN
priority including the
stack trace of the Throwable
t
passed as
parameter.
See warn(Object)
for more detailed information.
message
- the message object to log.t
- the exception to log, including its stack trace.
|
Log4j 1.1b7 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |