org.apache.logging.log4j.core

Class LoggerContext

java.lang.Object

org.apache.logging.log4j.core.AbstractLifeCycle

org.apache.logging.log4j.core.LoggerContext

All Implemented Interfaces:

AutoCloseable, ConfigurationListener, LifeCycle, LifeCycle2, org.apache.logging.log4j.spi.LoggerContext, org.apache.logging.log4j.spi.LoggerContextShutdownEnabled, org.apache.logging.log4j.spi.Terminable

Direct Known Subclasses:

AsyncLoggerContext

public class LoggerContext
extends AbstractLifeCycle
implements org.apache.logging.log4j.spi.LoggerContext, AutoCloseable, org.apache.logging.log4j.spi.Terminable, ConfigurationListener, org.apache.logging.log4j.spi.LoggerContextShutdownEnabled

The LoggerContext is the anchor for the logging system. It maintains a list of all the loggers requested by applications and a reference to the Configuration. The Configuration will contain the configured loggers, appenders, filters, etc and will be atomically updated whenever a reconfigure occurs.

Nested Class Summary

Nested classes/interfaces inherited from interface org.apache.logging.log4j.core.LifeCycle

LifeCycle.State

Field Summary

Fields

Modifier and Type	Field and Description
static String	PROPERTY_CONFIG Property name of the property change event fired if the configuration is changed.

Fields inherited from class org.apache.logging.log4j.core.AbstractLifeCycle

DEFAULT_STOP_TIMEOUT, DEFAULT_STOP_TIMEUNIT, LOGGER

Constructor Summary

Constructors

Constructor and Description
LoggerContext(String name) Constructor taking only a name.
LoggerContext(String name, Object externalContext) Constructor taking a name and a reference to an external context.
LoggerContext(String name, Object externalContext, String configLocn) Constructor taking a name external context and a configuration location String.
LoggerContext(String name, Object externalContext, URI configLocn) Constructor taking a name, external context and a configuration URI.

Method Summary

Modifier and Type	Method and Description
void	addFilter(Filter filter) Adds a Filter to the Configuration.
void	addPropertyChangeListener(PropertyChangeListener listener)
void	addShutdownListener(org.apache.logging.log4j.spi.LoggerContextShutdownAware listener)
void	close()
URI	getConfigLocation() Returns the initial configuration location or null.
Configuration	getConfiguration() Returns the current Configuration.
static LoggerContext	getContext() Returns the current LoggerContext.
static LoggerContext	getContext(boolean currentContext) Returns a LoggerContext.
static LoggerContext	getContext(ClassLoader loader, boolean currentContext, URI configLocation) Returns a LoggerContext.
Object	getExternalContext() Returns the external context.
List<org.apache.logging.log4j.spi.LoggerContextShutdownAware>	getListeners()
Logger	getLogger(String name) Gets a Logger from the Context.
Logger	getLogger(String name, org.apache.logging.log4j.message.MessageFactory messageFactory) Obtains a Logger from the Context.
Collection<Logger>	getLoggers() Gets a collection of the current loggers.
String	getName() Gets the name.
Object	getObject(String key)
Logger	getRootLogger() Gets the root logger.
boolean	hasLogger(String name) Determines if the specified Logger exists.
boolean	hasLogger(String name, Class<? extends org.apache.logging.log4j.message.MessageFactory> messageFactoryClass) Determines if the specified Logger exists.
boolean	hasLogger(String name, org.apache.logging.log4j.message.MessageFactory messageFactory) Determines if the specified Logger exists.
protected Logger	newInstance(LoggerContext ctx, String name, org.apache.logging.log4j.message.MessageFactory messageFactory)
void	onChange(Reconfigurable reconfigurable) Causes a reconfiguration to take place when the underlying configuration file changes.
Object	putObject(String key, Object value)
Object	putObjectIfAbsent(String key, Object value)
void	reconfigure() Reconfigures the context.
void	reconfigure(Configuration configuration)
void	removeFilter(Filter filter) Removes a Filter from the current Configuration.
Object	removeObject(String key)
boolean	removeObject(String key, Object value)
void	removePropertyChangeListener(PropertyChangeListener listener)
void	setConfigLocation(URI configLocation) Sets the configLocation to the specified value and reconfigures this context.
Configuration	setConfiguration(Configuration config) Sets the Configuration to be used.
void	setExternalContext(Object context) Sets the external context.
void	setName(String name) Sets the name.
void	start()
void	start(Configuration config) Starts with a specific configuration.
boolean	stop(long timeout, TimeUnit timeUnit) Blocks until all Log4j tasks have completed execution after a shutdown request and all appenders have shut down, or the timeout occurs, or the current thread is interrupted, whichever happens first.
void	terminate()
void	updateLoggers() Causes all Loggers to be updated against the current Configuration.
void	updateLoggers(Configuration config) Causes all Logger to be updated against the specified Configuration.

Methods inherited from class org.apache.logging.log4j.core.AbstractLifeCycle

equalsImpl, getState, getStatusLogger, hashCodeImpl, initialize, isInitialized, isStarted, isStarting, isStopped, isStopping, setStarted, setStarting, setState, setStopped, setStopping, stop, stop

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.logging.log4j.spi.LoggerContext

getLogger, getLogger

Field Detail

PROPERTY_CONFIG

public static final String PROPERTY_CONFIG

Property name of the property change event fired if the configuration is changed.

See Also:

Constant Field Values

Constructor Detail

LoggerContext

public LoggerContext(String name)

Constructor taking only a name.

Parameters:

name - The context name.

LoggerContext

public LoggerContext(String name,
                     Object externalContext)

Constructor taking a name and a reference to an external context.

Parameters:

name - The context name.

externalContext - The external context.

LoggerContext

public LoggerContext(String name,
                     Object externalContext,
                     URI configLocn)

Constructor taking a name, external context and a configuration URI.

Parameters:

name - The context name.

externalContext - The external context.

configLocn - The location of the configuration as a URI.

LoggerContext

public LoggerContext(String name,
                     Object externalContext,
                     String configLocn)

Constructor taking a name external context and a configuration location String. The location must be resolvable to a File.

Parameters:

name - The configuration location.

externalContext - The external context.

configLocn - The configuration location.

Method Detail

addShutdownListener

public void addShutdownListener(org.apache.logging.log4j.spi.LoggerContextShutdownAware listener)

Specified by:

addShutdownListener in interface org.apache.logging.log4j.spi.LoggerContextShutdownEnabled

getListeners

public List<org.apache.logging.log4j.spi.LoggerContextShutdownAware> getListeners()

Specified by:

getListeners in interface org.apache.logging.log4j.spi.LoggerContextShutdownEnabled

getContext

public static LoggerContext getContext()

Returns the current LoggerContext.

Avoids the type cast for:

 (LoggerContext) LogManager.getContext();
 

WARNING - The LoggerContext returned by this method may not be the LoggerContext used to create a Logger for the calling class.

Returns:

The current LoggerContext.

See Also:

LogManager.getContext()

getContext

public static LoggerContext getContext(boolean currentContext)

Returns a LoggerContext.

Avoids the type cast for:

 (LoggerContext) LogManager.getContext(currentContext);
 

Parameters:

currentContext - if false the LoggerContext appropriate for the caller of this method is returned. For example, in a web application if the caller is a class in WEB-INF/lib then one LoggerContext may be returned and if the caller is a class in the container's classpath then a different LoggerContext may be returned. If true then only a single LoggerContext will be returned.

Returns:

a LoggerContext.

See Also:

LogManager.getContext(boolean)

getContext

public static LoggerContext getContext(ClassLoader loader,
                                       boolean currentContext,
                                       URI configLocation)

Returns a LoggerContext.

Avoids the type cast for:

 (LoggerContext) LogManager.getContext(loader, currentContext, configLocation);
 

Parameters:

loader - The ClassLoader for the context. If null the context will attempt to determine the appropriate ClassLoader.

currentContext - if false the LoggerContext appropriate for the caller of this method is returned. For example, in a web application if the caller is a class in WEB-INF/lib then one LoggerContext may be returned and if the caller is a class in the container's classpath then a different LoggerContext may be returned. If true then only a single LoggerContext will be returned.

configLocation - The URI for the configuration to use.

Returns:

a LoggerContext.

See Also:

LogManager.getContext(ClassLoader, boolean, URI)

start

public void start()

Specified by:

start in interface LifeCycle

Overrides:

start in class AbstractLifeCycle

start

public void start(Configuration config)

Starts with a specific configuration.

Parameters:

config - The new Configuration.

close

public void close()

Specified by:

close in interface AutoCloseable

terminate

public void terminate()

Specified by:

terminate in interface org.apache.logging.log4j.spi.Terminable

stop

public boolean stop(long timeout,
                    TimeUnit timeUnit)

Blocks until all Log4j tasks have completed execution after a shutdown request and all appenders have shut down, or the timeout occurs, or the current thread is interrupted, whichever happens first.

Not all appenders will honor this, it is a hint and not an absolute guarantee that the this method not block longer. Setting timeout too low increase the risk of losing outstanding log events not yet written to the final destination.

Log4j can start threads to perform certain actions like file rollovers, calling this method with a positive timeout will block until the rollover thread is done.

Specified by:

stop in interface LifeCycle2

Overrides:

stop in class AbstractLifeCycle

Parameters:

timeout - the maximum time to wait, or 0 which mean that each apppender uses its default timeout, and don't wait for background tasks

timeUnit - the time unit of the timeout argument

Returns:

true if the logger context terminated and false if the timeout elapsed before termination.

Since:

2.7

getName

public String getName()

Gets the name.

Returns:

the name.

getRootLogger

public Logger getRootLogger()

Gets the root logger.

Returns:

the root logger.

setName

public void setName(String name)

Sets the name.

Parameters:

name - the new LoggerContext name

Throws:

NullPointerException - if the specified name is null

getObject

public Object getObject(String key)

Specified by:

getObject in interface org.apache.logging.log4j.spi.LoggerContext

putObject

public Object putObject(String key,
                        Object value)

Specified by:

putObject in interface org.apache.logging.log4j.spi.LoggerContext

putObjectIfAbsent

public Object putObjectIfAbsent(String key,
                                Object value)

Specified by:

putObjectIfAbsent in interface org.apache.logging.log4j.spi.LoggerContext

removeObject

public Object removeObject(String key)

Specified by:

removeObject in interface org.apache.logging.log4j.spi.LoggerContext

removeObject

public boolean removeObject(String key,
                            Object value)

Specified by:

removeObject in interface org.apache.logging.log4j.spi.LoggerContext

setExternalContext

public void setExternalContext(Object context)

Sets the external context.

Parameters:

context - The external context.

getExternalContext

public Object getExternalContext()

Returns the external context.

Specified by:

getExternalContext in interface org.apache.logging.log4j.spi.LoggerContext

Returns:

The external context.

getLogger

public Logger getLogger(String name)

Gets a Logger from the Context.

Specified by:

getLogger in interface org.apache.logging.log4j.spi.LoggerContext

Parameters:

name - The name of the Logger to return.

Returns:

The Logger.

getLoggers

public Collection<Logger> getLoggers()

Gets a collection of the current loggers.

Whether this collection is a copy of the underlying collection or not is undefined. Therefore, modify this collection at your own risk.

Returns:

a collection of the current loggers.

getLogger

public Logger getLogger(String name,
                        org.apache.logging.log4j.message.MessageFactory messageFactory)

Obtains a Logger from the Context.

Specified by:

getLogger in interface org.apache.logging.log4j.spi.LoggerContext

Parameters:

name - The name of the Logger to return.

messageFactory - The message factory is used only when creating a logger, subsequent use does not change the logger but will log a warning if mismatched.

Returns:

The Logger.

hasLogger

public boolean hasLogger(String name)

Determines if the specified Logger exists.

Specified by:

hasLogger in interface org.apache.logging.log4j.spi.LoggerContext

Parameters:

name - The Logger name to search for.

Returns:

True if the Logger exists, false otherwise.

hasLogger

public boolean hasLogger(String name,
                         org.apache.logging.log4j.message.MessageFactory messageFactory)

Determines if the specified Logger exists.

Specified by:

hasLogger in interface org.apache.logging.log4j.spi.LoggerContext

Parameters:

name - The Logger name to search for.

Returns:

True if the Logger exists, false otherwise.

hasLogger

public boolean hasLogger(String name,
                         Class<? extends org.apache.logging.log4j.message.MessageFactory> messageFactoryClass)

Determines if the specified Logger exists.

Specified by:

hasLogger in interface org.apache.logging.log4j.spi.LoggerContext

Parameters:

name - The Logger name to search for.

Returns:

True if the Logger exists, false otherwise.

getConfiguration

public Configuration getConfiguration()

Returns the current Configuration. The Configuration will be replaced when a reconfigure occurs.

Returns:

The current Configuration, never null, but may be NullConfiguration.

addFilter

public void addFilter(Filter filter)

Adds a Filter to the Configuration. Filters that are added through the API will be lost when a reconfigure occurs.

Parameters:

filter - The Filter to add.

removeFilter

public void removeFilter(Filter filter)

Removes a Filter from the current Configuration.

Parameters:

filter - The Filter to remove.

setConfiguration

public Configuration setConfiguration(Configuration config)

Sets the Configuration to be used.

Parameters:

config - The new Configuration.

Returns:

The previous Configuration.

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)

getConfigLocation

public URI getConfigLocation()

Returns the initial configuration location or null. The returned value may not be the location of the current configuration. Use getConfiguration().getConfigurationSource().getLocation() to get the actual source of the current configuration.

Returns:

the initial configuration location or null

setConfigLocation

public void setConfigLocation(URI configLocation)

Sets the configLocation to the specified value and reconfigures this context.

Parameters:

configLocation - the location of the new configuration

reconfigure

public void reconfigure()

Reconfigures the context. Log4j does not remove Loggers during a reconfiguration. Log4j will create new LoggerConfig objects and Log4j will point the Loggers at the new LoggerConfigs. Log4j will free the old LoggerConfig, along with old Appenders and Filters.

reconfigure

public void reconfigure(Configuration configuration)

updateLoggers

public void updateLoggers()

Causes all Loggers to be updated against the current Configuration.

updateLoggers

public void updateLoggers(Configuration config)

Causes all Logger to be updated against the specified Configuration.

Parameters:

config - The Configuration.

onChange

public void onChange(Reconfigurable reconfigurable)

Causes a reconfiguration to take place when the underlying configuration file changes.

Specified by:

onChange in interface ConfigurationListener

Parameters:

reconfigurable - The Configuration that can be reconfigured.

newInstance

protected Logger newInstance(LoggerContext ctx,
                             String name,
                             org.apache.logging.log4j.message.MessageFactory messageFactory)