org.apache.log4j.xml

Class DOMConfigurator

java.lang.Object

org.apache.log4j.xml.DOMConfigurator

All Implemented Interfaces:

Configurator

public class DOMConfigurator
extends Object
implements Configurator

Use this class to initialize the log4j environment using a DOM tree.

The DTD is specified in log4j.dtd.

Sometimes it is useful to see how log4j is reading configuration files. You can enable log4j internal logging by defining the log4j.debug variable on the java command line. Alternatively, set the debug attribute in the log4j:configuration element. As in

   <log4j:configuration debug="true" xmlns:log4j="http://jakarta.apache.org/log4j/">
   ...
   </log4j:configuration>

This version of DOMConfigurator has been modified to support the definition of groups as described in Logger by adding a 'group' element:

   <group name="GROUPNAME" level="LEVEL"/>

All loggers retrieved via Logger.getLogger(String, String) or Logger.getLogger(Class, String) with the same group name will have their effective level set to the provided level.

This group-defined Level verbosity threshold can be overridden by setting an explicit level on the Logger itself.

There are sample XML files included in the package.

Since:

0.8.3

Author:

Christopher Taylor, Ceki Gülcü, Anders Kristensen

Field Summary

Fields inherited from interface org.apache.log4j.spi.Configurator

INHERITED, NULL

Constructor Summary

Constructors

Constructor and Description
DOMConfigurator() No argument constructor.

Method Summary

Methods

Modifier and Type	Method and Description
static void	configure(Element element) Configure log4j using a configuration element as defined in the log4j.dtd.
static void	configure(String filename) A static version of doConfigure(String, LoggerRepository).
static void	configure(URL url) A static version of doConfigure(URL, LoggerRepository).
static void	configureAndWatch(String configFilename) Like configureAndWatch(String, long) except that the default delay as defined by FileWatchdog#DEFAULT_DELAY is used.
static void	configureAndWatch(String configFilename, long delay) Read the configuration file configFilename if it exists.
void	doConfigure(Element element, LoggerRepository repository) Configure by taking in an DOM element.
void	doConfigure(InputStream inputStream, LoggerRepository repository) Configure log4j by reading in a log4j.dtd compliant XML configuration file.
void	doConfigure(Reader reader, LoggerRepository repository) Configure log4j by reading in a log4j.dtd compliant XML configuration file.
void	doConfigure(String filename, LoggerRepository repository)
void	doConfigure(URL url, LoggerRepository repository) Interpret a resource pointed by a URL and set up log4j accordingly.
static Object	parseElement(Element element, Properties props, Class expectedClass) Creates an object and processes any nested param elements but does not call activateOptions.
static void	setParameter(Element elem, PropertySetter propSetter, Properties props) Sets a parameter based from configuration file content.
static String	subst(String value, Properties props) Substitutes property value for any references in expression.

Methods inherited from class java.lang.Object

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

Constructor Detail

DOMConfigurator

public DOMConfigurator()

No argument constructor.

Method Detail

configure

public static void configure(Element element)

Configure log4j using a configuration element as defined in the log4j.dtd.

Throws:

SecurityException - if the caller does not have MonitorAppPermission("logger.config").

configureAndWatch

public static void configureAndWatch(String configFilename)

Like configureAndWatch(String, long) except that the default delay as defined by FileWatchdog#DEFAULT_DELAY is used.

Parameters:

configFilename - A log4j configuration file in XML format.

Throws:

SecurityException - if the caller does not have MonitorAppPermission("logger.config").

configureAndWatch

public static void configureAndWatch(String configFilename,
                     long delay)

Read the configuration file configFilename if it exists. Moreover, a thread will be created that will periodically check if configFilename has been created or modified. The period is determined by the delay argument. If a change or file creation is detected, then configFilename is read to configure log4j.

Parameters:

configFilename - A log4j configuration file in XML format.

delay - The delay in milliseconds to wait between each check.

Throws:

SecurityException - if the caller does not have MonitorAppPermission("logger.config").

doConfigure

public void doConfigure(String filename,
               LoggerRepository repository)

Throws:

SecurityException - if the caller does not have MonitorAppPermission("logger.config").

doConfigure

public void doConfigure(URL url,
               LoggerRepository repository)

Description copied from interface: Configurator

Interpret a resource pointed by a URL and set up log4j accordingly. The configuration is done relative to the hierarchy parameter.

Specified by:

doConfigure in interface Configurator

Parameters:

url - The URL to parse

repository - The hierarchy to operation upon.

Throws:

SecurityException - if the caller does not have MonitorAppPermission("logger.config").

doConfigure

public void doConfigure(InputStream inputStream,
               LoggerRepository repository)
                 throws FactoryConfigurationError

Configure log4j by reading in a log4j.dtd compliant XML configuration file.

Throws:

SecurityException - if the caller does not have MonitorAppPermission("logger.config").

FactoryConfigurationError

doConfigure

public void doConfigure(Reader reader,
               LoggerRepository repository)
                 throws FactoryConfigurationError

Configure log4j by reading in a log4j.dtd compliant XML configuration file.

Throws:

SecurityException - if the caller does not have MonitorAppPermission("logger.config").

FactoryConfigurationError

doConfigure

public void doConfigure(Element element,
               LoggerRepository repository)

Configure by taking in an DOM element.

Throws:

SecurityException - if the caller does not have MonitorAppPermission("logger.config").

configure

public static void configure(String filename)
                      throws FactoryConfigurationError

A static version of doConfigure(String, LoggerRepository).

Throws:

SecurityException - if the caller does not have MonitorAppPermission("logger.config").

FactoryConfigurationError

configure

public static void configure(URL url)
                      throws FactoryConfigurationError

A static version of doConfigure(URL, LoggerRepository).

Throws:

SecurityException - if the caller does not have MonitorAppPermission("logger.config").

FactoryConfigurationError

subst

public static String subst(String value,
           Properties props)

Substitutes property value for any references in expression.

Parameters:

value - value from configuration file, may contain literal text, property references or both

props - properties.

Returns:

evaluated expression, may still contain expressions if unable to expand.

Throws:

SecurityException - if the caller does not have MonitorAppPermission("logger.config").

Since:

1.2.15

setParameter

public static void setParameter(Element elem,
                PropertySetter propSetter,
                Properties props)

Sets a parameter based from configuration file content.

Parameters:

elem - param element, may not be null.

propSetter - property setter, may not be null.

props - properties

Throws:

SecurityException - if the caller does not have MonitorAppPermission("logger.config").

Since:

1.2.15

parseElement

public static Object parseElement(Element element,
                  Properties props,
                  Class expectedClass)
                           throws Exception

Creates an object and processes any nested param elements but does not call activateOptions. If the class also supports UnrecognizedElementParser, the parseUnrecognizedElement method will be call for any child elements other than param.

Parameters:

element - element, may not be null.

props - properties

expectedClass - interface or class expected to be implemented by created class

Returns:

created class or null.

Throws:

Exception - thrown if the contain object should be abandoned.

SecurityException - if the caller does not have MonitorAppPermission("logger.config").

Since:

1.2.15