Log4j 1.2.13 | |
Prev Class | Next Class | Frames | No Frames |
Summary: Nested | Field | Method | Constr | Detail: Nested | Field | Method | Constr |
java.lang.Object
org.apache.log4j.Category
Logger
subclass. It
will be kept around to preserve backward compatibility until mid
2003.
Logger
is a subclass of Category, i.e. it extends
Category. In other words, a logger is a category. Thus,
all operations that can be performed on a category can be
performed on a logger. Internally, whenever log4j is asked to
produce a Category object, it will instead produce a Logger
object. Log4j 1.2 will never produce Category objects but
only Logger
instances. In order to preserve backward
compatibility, methods that previously accepted category objects
still continue to accept category objects.
For example, the following are all legal and will work as
expected.
// Deprecated form: Category cat = Category.getInstance("foo.bar") // Preferred form for retrieving loggers: Logger logger = Logger.getLogger("foo.bar")The first form is deprecated and should be avoided. There is absolutely no need for new client code to use or refer to the
Category
class. Whenever possible,
please avoid referring to it or using it.
See the short manual for an
introduction on this class.
See the document entitled preparing
for log4j 1.3 for a more detailed discussion.
Field Summary | |
protected boolean |
|
protected Level |
|
protected String |
|
protected Category |
|
protected LoggerRepository | |
protected ResourceBundle |
Constructor Summary | |
|
Method Summary | |
void |
|
void | |
void |
|
void | |
void |
|
void | |
void |
|
static Logger |
|
void | |
void |
|
protected void | |
boolean |
|
Enumeration |
|
Appender |
|
Priority |
|
static Enumeration |
|
static LoggerRepository |
|
Level |
|
LoggerRepository |
|
static Category |
|
static Category |
|
Level | |
LoggerRepository |
|
String |
|
Category |
|
Level |
|
ResourceBundle |
|
protected String |
|
static Category |
|
void | |
void |
|
boolean |
|
boolean |
|
boolean |
|
boolean |
|
void | |
void | |
void | |
void | |
void | |
void |
|
void |
|
void |
|
void |
|
void | |
void |
|
void |
|
static void |
|
void | |
void |
|
protected boolean additive
Additivity is set to true by default, that is children inherit the appenders of their ancestors by default. If this variable is set tofalse
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 tofalse
too. See the user manual for more details.
protected Level level
The assigned level of this category. Thelevel
variable need not be assigned a value in which case it is inherited form the hierarchy.
protected String name
The name of this category.
protected Category parent
The parent of this category. All categories have at least one ancestor which is the root category.
protected ResourceBundle resourceBundle
protected Category(String name)
This constructor created a newCategory
instance and sets its name. It is intended to be used by sub-classes only. You should not create categories directly.
- Parameters:
name
- The name of the category.
public void addAppender(Appender newAppender)
AddnewAppender
to the list of appenders of this Category instance. IfnewAppender
is already in the list of appenders, then it won't be added again.
- Specified by:
- addAppender in interface AppenderAttachable
public void assertLog(boolean assertion, String msg)
Ifassertion
parameter isfalse
, then logsmsg
as anerror
statement. Theassert
method has been renamed toassertLog
becauseassert
is a language reserved word in JDK 1.4.
- Parameters:
assertion
-msg
- The message to print ifassertion
is false.
- Since:
- 1.2
public void callAppenders(LoggingEvent event)
Call the appenders in the hierrachy starting atthis
. 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.
- Parameters:
event
- the event to log.
public void debug(Object message)
Log a message object with theDEBUG
level. This method first checks if this category isDEBUG
enabled by comparing the level of this category with theDEBUG
level. If this category isDEBUG
enabled, then it converts the message object (passed as parameter) to a string by invoking the appropriateObjectRenderer
. 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 aThrowable
to this method will print the name of theThrowable
but no stack trace. To print a stack trace use thedebug(Object,Throwable)
form instead.
- Parameters:
message
- the message object to log.
public void debug(Object message, Throwable t)
Log a message object with theDEBUG
level including the stack trace of theThrowable
t
passed as parameter. Seedebug(Object)
form for more detailed information.
- Parameters:
message
- the message object to log.t
- the exception to log, including its stack trace.
public void error(Object message)
Log a message object with theERROR
Level. This method first checks if this category isERROR
enabled by comparing the level of this category withERROR
Level. If this category isERROR
enabled, then it converts the message object passed as parameter to a string by invoking the appropriateObjectRenderer
. 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 aThrowable
to this method will print the name of theThrowable
but no stack trace. To print a stack trace use theerror(Object,Throwable)
form instead.
- Parameters:
message
- the message object to log
public void error(Object message, Throwable t)
Log a message object with theERROR
level including the stack trace of theThrowable
t
passed as parameter. Seeerror(Object)
form for more detailed information.
- Parameters:
message
- the message object to log.t
- the exception to log, including its stack trace.
public static Logger exists(String name)
Deprecated. Please use
LogManager.exists(String)
instead.If the named category exists (in the default hierarchy) then it returns a reference to the category, otherwise it returnsnull
.
- Since:
- 0.8.5
public void fatal(Object message)
Log a message object with theFATAL
Level. This method first checks if this category isFATAL
enabled by comparing the level of this category withFATAL
Level. If the category isFATAL
enabled, then it converts the message object passed as parameter to a string by invoking the appropriateObjectRenderer
. 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 aThrowable
to this method will print the name of the Throwable but no stack trace. To print a stack trace use thefatal(Object,Throwable)
form instead.
- Parameters:
message
- the message object to log
public void fatal(Object message, Throwable t)
Log a message object with theFATAL
level including the stack trace of theThrowable
t
passed as parameter. Seefatal(Object)
for more detailed information.
- Parameters:
message
- the message object to log.t
- the exception to log, including its stack trace.
protected void forcedLog(String fqcn, Priority level, Object message, Throwable t)
This method creates a new logging event and logs the event without further checks.
public boolean getAdditivity()
Get the additivity flag for this Category instance.
public Enumeration getAllAppenders()
Get the appenders contained in this category as anEnumeration
. If no appenders can be found, then aNullEnumeration
is returned.
- Specified by:
- getAllAppenders in interface AppenderAttachable
- Returns:
- Enumeration An enumeration of the appenders in this category.
public Appender getAppender(String name)
Look for the appender named asname
. Return the appender with that name if in the list. Returnnull
otherwise.
- Specified by:
- getAppender in interface AppenderAttachable
public Priority getChainedPriority()
Deprecated. Please use the the
getEffectiveLevel()
method instead.
public static Enumeration getCurrentCategories()
Deprecated. Please use
LogManager.getCurrentLoggers()
instead.Returns all the currently defined categories in the default hierarchy as anEnumeration
. The root category is not included in the returnedEnumeration
.
public static LoggerRepository getDefaultHierarchy()
Deprecated. Please use
LogManager.getLoggerRepository()
instead.Return the default Hierarchy instance.
- Since:
- 1.0
public Level getEffectiveLevel()
Starting from this category, search the category hierarchy for a non-null level and return it. Otherwise, return the level of the root category. The Category class is designed so that this method executes as quickly as possible.
public LoggerRepository getHierarchy()
Deprecated. Please use
getLoggerRepository()
instead.Return the theHierarchy
where thisCategory
instance is attached.
- Since:
- 1.1
public static Category getInstance(Class clazz)
Deprecated. Please make sure to use
Logger.getLogger(Class)
instead.
public static Category getInstance(String name)
Deprecated. Make sure to use
Logger.getLogger(String)
instead.
public final Level getLevel()
Returns the assignedLevel
, if any, for this Category.
- Returns:
- Level - the assigned Level, can be
null
.
public LoggerRepository getLoggerRepository()
Return the theLoggerRepository
where thisCategory
is attached.
- Since:
- 1.2
public final String getName()
Return the category name.
public final Category getParent()
Returns the parent of this category. Note that the parent of a given category may change during the lifetime of the category. The root category will returnnull
.
- Since:
- 1.2
public ResourceBundle getResourceBundle()
Return the inheritedResourceBundle
for this category. This method walks the hierarchy to find the appropriate resource bundle. It will return the resource bundle attached to the closest ancestor of this category, much like the way priorities are searched. In case there is no bundle in the hierarchy thennull
is returned.
- Since:
- 0.9.0
protected String getResourceBundleString(String key)
Returns the string resource coresponding tokey
in this category's inherited resource bundle. See alsogetResourceBundle()
. If the resource cannot be found, then anerror
message will be logged complaining about the missing resource.
public void info(Object message)
Log a message object with theINFO
Level. This method first checks if this category isINFO
enabled by comparing the level of this category withINFO
Level. If the category isINFO
enabled, then it converts the message object passed as parameter to a string by invoking the appropriateObjectRenderer
. 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 aThrowable
to this method will print the name of the Throwable but no stack trace. To print a stack trace use theinfo(Object,Throwable)
form instead.
- Parameters:
message
- the message object to log
public void info(Object message, Throwable t)
Log a message object with theINFO
level including the stack trace of theThrowable
t
passed as parameter. Seeinfo(Object)
for more detailed information.
- Parameters:
message
- the message object to log.t
- the exception to log, including its stack trace.
public boolean isAttached(Appender appender)
Is the appender passed as parameter attached to this category?
- Specified by:
- isAttached in interface AppenderAttachable
public boolean isDebugEnabled()
Check whether this category is enabled for theDEBUG
Level. This function is intended to lessen the computational cost of disabled log debug statements. For somecat
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 writeif(cat.isDebugEnabled()) { cat.debug("This is entry number: " + i ); }This way you will not incur the cost of parameter construction if debugging is disabled forcat
. On the other hand, if thecat
is debug enabled, you will incur the cost of evaluating whether the category is debug enabled twice. Once inisDebugEnabled
and once in thedebug
. This is an insignificant overhead since evaluating a category takes about 1%% of the time it takes to actually log.
- Returns:
- boolean -
true
if this category is debug enabled,false
otherwise.
public boolean isEnabledFor(Priority level)
Check whether this category is enabled for a givenLevel
passed as parameter. See alsoisDebugEnabled()
.
- Returns:
- boolean True if this category is enabled for
level
.
public boolean isInfoEnabled()
Check whether this category is enabled for the info Level. See alsoisDebugEnabled()
.
- Returns:
- boolean -
true
if this category is enabled for level info,false
otherwise.
public void l7dlog(Priority priority, String key, Object[] params, Throwable t)
Log a localized and parameterized message. First, the user suppliedkey
is searched in the resource bundle. Next, the resulting pattern is formatted usingMessageFormat.format(String,Object[])
method with the user supplied object arrayparams
.
- Since:
- 0.8.4
public void l7dlog(Priority priority, String key, Throwable t)
Log a localized message. The user supplied parameterkey
is replaced by its localized version from the resource bundle.
- Since:
- 0.8.4
- See Also:
setResourceBundle(ResourceBundle)
public void log(String callerFQCN, Priority level, Object message, Throwable t)
This is the most generic printing method. It is intended to be invoked by wrapper classes.
- Parameters:
callerFQCN
- The wrapper class' fully qualified class name.level
- The level of the logging request.message
- The message of the logging request.t
- The throwable of the logging request, may be null.
public void log(Priority priority, Object message)
This generic form is intended to be used by wrappers.
public void log(Priority priority, Object message, Throwable t)
This generic form is intended to be used by wrappers.
public void removeAllAppenders()
Remove all previously added appenders from this Category instance. This is useful when re-reading configuration information.
- Specified by:
- removeAllAppenders in interface AppenderAttachable
public void removeAppender(String name)
Remove the appender with the name passed as parameter form the list of appenders.
- Specified by:
- removeAppender in interface AppenderAttachable
- Since:
- 0.8.2
public void removeAppender(Appender appender)
Remove the appender passed as parameter form the list of appenders.
- Specified by:
- removeAppender in interface AppenderAttachable
- Since:
- 0.8.2
public void setAdditivity(boolean additive)
Set the additivity flag for this Category instance.
- Since:
- 0.8.1
public void setLevel(Level level)
Set the level of this Category. If you are passing any ofLevel.DEBUG
,Level.INFO
,Level.WARN
,Level.ERROR
,Level.FATAL
as a parameter, you need to case them as Level. As inlogger.setLevel((Level) Level.DEBUG);Null values are admitted.
public void setPriority(Priority priority)
Deprecated. Please use
setLevel(Level)
instead.Set the level of this Category. Null values are admitted.
public void setResourceBundle(ResourceBundle bundle)
Set the resource bundle to be used with localized logging methodsl7dlog(Priority,String,Throwable)
andl7dlog(Priority,String,Object[],Throwable)
.
- Since:
- 0.8.4
public static void shutdown()
Deprecated. Please use
LogManager.shutdown()
instead.Calling this method will safely close and remove all appenders in all the categories including root contained in the default hierachy. Some appenders such asSocketAppender
andAsyncAppender
need to be closed before the application exists. Otherwise, pending logging events might be lost. Theshutdown
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.
- Since:
- 1.0
public void warn(Object message)
Log a message object with theWARN
Level. This method first checks if this category isWARN
enabled by comparing the level of this category withWARN
Level. If the category isWARN
enabled, then it converts the message object passed as parameter to a string by invoking the appropriateObjectRenderer
. 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 aThrowable
to this method will print the name of the Throwable but no stack trace. To print a stack trace use thewarn(Object,Throwable)
form instead.
- Parameters:
message
- the message object to log.
public void warn(Object message, Throwable t)
Log a message with theWARN
level including the stack trace of theThrowable
t
passed as parameter. Seewarn(Object)
for more detailed information.
- Parameters:
message
- the message object to log.t
- the exception to log, including its stack trace.