org.apache.log4j.Category Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
// Contibutors: Alex Blewitt
// Markus Oestreicher
// Frank Hoering
// Nelson Minar
// Jim Cakalic
// Avy Sharell
// Ciaran Treanor
// Jeff Turner
// Michael Horwitz
// Calvin Chan
// Aaron Greenhouse
// Beat Meier
// Colin Sampaleanu
package org.apache.log4j;
import org.apache.log4j.spi.AppenderAttachable;
import org.apache.log4j.spi.LoggingEvent;
import org.apache.log4j.spi.LoggerRepository;
import java.util.Enumeration;
import java.util.ResourceBundle;
/**
* This class has been deprecated and
* replaced by the {@link 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.
*
* @author Ceki Gülcü
* @author Anders Kristensen
*/
public class Category implements AppenderAttachable {
/**
* The name of this category.
*/
protected String name;
/**
* The assigned level of this category. The
* level variable need not be assigned a value in
* which case it is inherited form the hierarchy.
*/
protected volatile Level level;
/**
* The parent of this category. All categories have at least one
* ancestor which is the root category.
*/
protected volatile Category parent;
// No comment
protected ResourceBundle resourceBundle;
// No comment
protected LoggerRepository repository;
/**
*Additivity is set to true by default, that is children inherit
* the appenders of their ancestors by default. If this variable is
* set to 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.
*/
protected boolean additive;
/**
* This constructor created a new Category instance and
* sets its name.
*
It is intended to be used by sub-classes only. You should not
* create categories directly.
* @param name The name of the category.
*/
protected Category(String name) {
}
/**
Add 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.
*/
synchronized
public
void addAppender(Appender newAppender) {
}
/**
If assertion parameter is false, then
logs msg as an {@link #error(Object) error} statement.
The assert method has been renamed to
assertLog because assert is a language
reserved word in JDK 1.4.
@param assertion
@param msg The message to print if assertion is
false.
@since 1.2 */
public
void assertLog(boolean assertion, String msg) {
}
/**
Call the appenders in the hierrachy starting at
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.
@param event the event to log. */
public
void callAppenders(LoggingEvent event) {
}
/**
Log a message object with the {@link Level#DEBUG DEBUG} level.
This method first checks if this category is DEBUG
enabled by comparing the level of this category with the {@link
Level#DEBUG DEBUG} level. If this category is
DEBUG enabled, then it converts the message object
(passed as parameter) to a string by invoking the appropriate
{@link org.apache.log4j.or.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 {@link Throwable} to this
method will print the name of the Throwable but no
stack trace. To print a stack trace use the {@link #debug(Object,
Throwable)} form instead.
@param message the message object to log. */
public
void debug(Object message) {
}
/**
Log a message object with the DEBUG level including
the stack trace of the {@link Throwable} t passed as
parameter.
See {@link #debug(Object)} form for more detailed information.
@param message the message object to log.
@param t the exception to log, including its stack trace. */
public
void debug(Object message, Throwable t) {
}
/**
Log a message object with the {@link Level#ERROR ERROR} Level.
This method first checks if this category is ERROR
enabled by comparing the level of this category with {@link
Level#ERROR ERROR} Level. If this category is ERROR
enabled, then it converts the message object passed as parameter
to a string by invoking the appropriate {@link
org.apache.log4j.or.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 {@link Throwable} to this
method will print the name of the Throwable but no
stack trace. To print a stack trace use the {@link #error(Object,
Throwable)} form instead.
@param message the message object to log */
public
void error(Object message) {
}
/**
Log a message object with the ERROR level including
the stack trace of the {@link Throwable} t passed as
parameter.
See {@link #error(Object)} form for more detailed information.
@param message the message object to log.
@param t the exception to log, including its stack trace. */
public
void error(Object message, Throwable t) {
}
/**
If the named category exists (in the default hierarchy) then it
returns a reference to the category, otherwise it returns
null.
@deprecated Please use {@link LogManager#exists} instead.
@since 0.8.5 */
public
static
Logger exists(String name) {
return null;
}
/**
Log a message object with the {@link Level#FATAL FATAL} Level.
This method first checks if this category is FATAL
enabled by comparing the level of this category with {@link
Level#FATAL FATAL} Level. If the category is FATAL
enabled, then it converts the message object passed as parameter
to a string by invoking the appropriate
{@link org.apache.log4j.or.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 {@link Throwable} to this
method will print the name of the Throwable but no stack trace. To
print a stack trace use the {@link #fatal(Object, Throwable)} form
instead.
@param message the message object to log */
public
void fatal(Object message) {
}
/**
Log a message object with the FATAL level including
the stack trace of the {@link Throwable} t passed as
parameter.
See {@link #fatal(Object)} for more detailed information.
@param message the message object to log.
@param t the exception to log, including its stack trace. */
public
void fatal(Object message, Throwable t) {
}
public void setGroup(String group) {
}
/**
* This method creates a new logging event and logs the event
* without further checks.
*/
protected void forcedLog(String fqcn, Level level, Object message, Throwable t) {
}
/**
Get the additivity flag for this Category instance.
*/
public
boolean getAdditivity() {
return false;
}
/**
Get the appenders contained in this category as an {@link
Enumeration}. If no appenders can be found, then a {@link NullEnumeration}
is returned.
@return Enumeration An enumeration of the appenders in this category. */
synchronized
public
Enumeration getAllAppenders() {
return null;
}
/**
Look for the appender named as name.
Return the appender with that name if in the list. Return
null otherwise. */
synchronized
public
Appender getAppender(String name) {
return null;
}
/**
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
Level getEffectiveLevel() {
return null; // If reached will cause an NullPointerException.
}
/**
*
* @deprecated Please use the the {@link #getEffectiveLevel} method
* instead.
* */
public
Priority getChainedPriority() {
return null; // If reached will cause an NullPointerException.
}
/**
Returns all the currently defined categories in the default
hierarchy as an {@link java.util.Enumeration Enumeration}.
The root category is not included in the returned
{@link Enumeration}.
@deprecated Please use {@link LogManager#getCurrentLoggers()} instead.
*/
public
static
Enumeration getCurrentCategories() {
return null;
}
/**
Return the default Hierarchy instance.
@deprecated Please use {@link LogManager#getLoggerRepository()} instead.
@since 1.0
*/
public
static
LoggerRepository getDefaultHierarchy() {
return null;
}
/**
Return the the {@link Hierarchy} where this Category
instance is attached.
@deprecated Please use {@link #getLoggerRepository} instead.
@since 1.1 */
public
LoggerRepository getHierarchy() {
return null;
}
/**
Return the the {@link LoggerRepository} where this
Category is attached.
@since 1.2 */
public
LoggerRepository getLoggerRepository() {
return null;
}
/**
* @deprecated Make sure to use {@link Logger#getLogger(String)} instead.
*/
public
static
Category getInstance(String name) {
return null;
}
/**
* @deprecated Please make sure to use {@link Logger#getLogger(Class)} instead.
*/
public
static
Category getInstance(Class clazz) {
return null;
}
/**
Return the category name. */
public
final
String getName() {
return null;
}
/**
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 return null.
@since 1.2
*/
final
public
Category getParent() {
return null;
}
/**
Returns the assigned {@link Level}, if any, for this Category.
@return Level - the assigned Level, can be null.
*/
final
public
Level getLevel() {
return null;
}
/**
@deprecated Please use {@link #getLevel} instead.
*/
final
public
Level getPriority() {
return null;
}
/**
* @deprecated Please use {@link Logger#getRootLogger()} instead.
*/
final
public
static
Category getRoot() {
return null;
}
/**
Return the inherited {@link ResourceBundle} 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 then null is returned.
@since 0.9.0 */
public
ResourceBundle getResourceBundle() {
return null;
}
/**
* Returns the string resource coresponding to key in
* this category's inherited resource bundle. See also {@link
* #getResourceBundle}.
*
If the resource cannot be found, then an {@link #error error}
* message will be logged complaining about the missing resource.
*/
protected String getResourceBundleString(String key) {
return null;
}
/**
Log a message object with the {@link Level#INFO INFO} Level.
This method first checks if this category is INFO
enabled by comparing the level of this category with {@link
Level#INFO INFO} Level. If the category is INFO
enabled, then it converts the message object passed as parameter
to a string by invoking the appropriate
{@link org.apache.log4j.or.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 {@link Throwable} to this
method will print the name of the Throwable but no stack trace. To
print a stack trace use the {@link #info(Object, Throwable)} form
instead.
@param message the message object to log */
public
void info(Object message) {
}
/**
Log a message object with the INFO level including
the stack trace of the {@link Throwable} t passed as
parameter.
See {@link #info(Object)} for more detailed information.
@param message the message object to log.
@param t the exception to log, including its stack trace. */
public
void info(Object message, Throwable t) {
}
/**
Is the appender passed as parameter attached to this category?
*/
public
boolean isAttached(Appender appender) {
return false;
}
/**
* Check whether this category is enabled for the DEBUG
* Level.
*
*
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.
*
* @return boolean - true if this category is debug
* enabled, false otherwise.
* */
public
boolean isDebugEnabled() {
return false;
}
/**
* Check whether this category is enabled for the WARN
* Level.
*
*
This function is intended to lessen the computational cost of
* disabled log warn statements.
*
*
For some cat Category object, when you write,
*
* cat.warn("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.isWarnEnabled()) {
* cat.warn("This is entry number: " + i );
* }
*
*
* This way you will not incur the cost of parameter
* construction if warn is disabled for cat. On
* the other hand, if the cat is warn enabled, you
* will incur the cost of evaluating whether the category is warn
* enabled twice. Once in isWarnEnabled and once in
* the warn. This is an insignificant overhead
* since evaluating a category takes about 1%% of the time it
* takes to actually log.
*
* @return boolean - true if this category is warn
* enabled, false otherwise.
* */
public boolean isWarnEnabled() {
return false;
}
/**
* Check whether this category is enabled for the ERROR
* Level.
*
*
This function is intended to lessen the computational cost of
* disabled log error statements.
*
*
For some cat Category object, when you write,
*
* cat.error("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.isErrorEnabled()) {
* cat.error("This is entry number: " + i );
* }
*
*
* This way you will not incur the cost of parameter
* construction if error is disabled for cat. On
* the other hand, if the cat is warn enabled, you
* will incur the cost of evaluating whether the category is error
* enabled twice. Once in isErrorEnabled and once in
* the error. This is an insignificant overhead
* since evaluating a category takes about 1%% of the time it
* takes to actually log.
*
* @return boolean - true if this category is error
* enabled, false otherwise.
* */
public boolean isErrorEnabled() {
return false;
}
/**
* Check whether this category is enabled for the FATAL
* Level.
*
*
This function is intended to lessen the computational cost of
* disabled log fatal statements.
*
*
For some cat Category object, when you write,
*
* cat.fatal("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.fatal("This is entry number: " + i );
* }
*
*
* This way you will not incur the cost of parameter
* construction if fatal is disabled for cat. On
* the other hand, if the cat is fatal enabled, you
* will incur the cost of evaluating whether the category is fatal
* enabled twice. Once in isFatalEnabled and once in
* the fatal. This is an insignificant overhead
* since evaluating a category takes about 1%% of the time it
* takes to actually log.
*
* @return boolean - true if this category is fatal
* enabled, false otherwise.
* */
public boolean isFatalEnabled() {
return false;
}
/**
Check whether this category is enabled for a given {@link
Level} passed as parameter.
See also {@link #isDebugEnabled}.
@return boolean True if this category is enabled for level.
*/
public
boolean isEnabledFor(Priority level) {
return false;
}
/**
Check whether this category is enabled for the info Level.
See also {@link #isDebugEnabled}.
@return boolean - true if this category is enabled
for level info, false otherwise.
*/
public
boolean isInfoEnabled() {
return false;
}
/**
Log a localized message. The user supplied parameter
key is replaced by its localized version from the
resource bundle.
@see #setResourceBundle
@since 0.8.4 */
public
void l7dlog(Level level, String key, Throwable t) {
}
/**
Log a localized and parameterized message. First, the user
supplied key is searched in the resource
bundle. Next, the resulting pattern is formatted using
{@link java.text.MessageFormat#format(String,Object[])} method with the
user supplied object array params.
@since 0.8.4
*/
public
void l7dlog(Level level, String key, Object[] params, Throwable t) {
}
/**
This generic form is intended to be used by wrappers.
*/
public
void log(Level level, Object message, Throwable t) {
}
/**
This generic form is intended to be used by wrappers.
*/
public
void log(Level level, Object message) {
}
/**
This is the most generic printing method. It is intended to be
invoked by wrapper classes.
@param callerFQCN The wrapper class' fully qualified class name.
@param level The level of the logging request.
@param message The message of the logging request.
@param t The throwable of the logging request, may be null. */
public
void log(String callerFQCN, Level level, Object message, Throwable t) {
}
/**
Remove all previously added appenders from this Category
instance.
This is useful when re-reading configuration information.
*/
synchronized
public
void removeAllAppenders() {
}
/**
Remove the appender passed as parameter form the list of appenders.
@since 0.8.2
*/
synchronized
public
void removeAppender(Appender appender) {
}
/**
Remove the appender with the name passed as parameter form the
list of appenders.
@since 0.8.2 */
synchronized
public
void removeAppender(String name) {
}
/**
Set the additivity flag for this Category instance.
@since 0.8.1
*/
public
void setAdditivity(boolean additive) {
}
/**
Set the level of this Category. If you are passing any of
Level.DEBUG, Level.INFO,
Level.WARN, Level.ERROR,
Level.FATAL as a parameter, you need to case them as
Level.
As in
logger.setLevel((Level) Level.DEBUG);
Null values are admitted. */
public
void setLevel(Level level) {
}
/**
Set the level of this Category.
Null values are admitted.
@deprecated Please use {@link #setLevel} instead.
*/
public
void setPriority(Priority priority) {
}
/**
Set the resource bundle to be used with localized logging
methods {@link #l7dlog(Priority,String,Throwable)} and {@link
#l7dlog(Priority,String,Object[],Throwable)}.
@since 0.8.4
*/
public
void setResourceBundle(ResourceBundle bundle) {
}
/**
Calling this method will safely close and remove all
appenders in all the categories including root contained in the
default hierachy.
Some appenders such as {@link org.apache.log4j.net.SocketAppender}
and {@link 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.
@deprecated Please use {@link LogManager#shutdown()} instead.
@since 1.0
*/
public
static
void shutdown() {
}
/**
Log a message object with the {@link Level#WARN WARN} Level.
This method first checks if this category is WARN
enabled by comparing the level of this category with {@link
Level#WARN WARN} Level. If the category is WARN
enabled, then it converts the message object passed as parameter
to a string by invoking the appropriate
{@link org.apache.log4j.or.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 {@link Throwable} to this
method will print the name of the Throwable but no stack trace. To
print a stack trace use the {@link #warn(Object, Throwable)} form
instead.
@param message the message object to log. */
public
void warn(Object message) {
}
/**
Log a message with the WARN level including the
stack trace of the {@link Throwable} t passed as
parameter.
See {@link #warn(Object)} for more detailed information.
@param message the message object to log.
@param t the exception to log, including its stack trace. */
public
void warn(Object message, Throwable t) {
}
}