public class

DOMConfigurator

extends Object
implements Configurator
java.lang.Object
   ↳ org.apache.log4j.xml.DOMConfigurator

Class Overview

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>

There are sample XML files included in the package.

Summary

[Expand]
Inherited Constants
From interface org.apache.log4j.spi.Configurator
Fields
protected LoggerFactory catFactory
Public Constructors
DOMConfigurator()
No argument constructor.
Public Methods
static void configure(URL url)
A static version of doConfigure(URL, LoggerRepository).
static void configure(String filename)
A static version of doConfigure(String, LoggerRepository).
static void configure(Element element)
Configure log4j using a configuration element as defined in the log4j.dtd.
static void configureAndWatch(String configFilename)
Like configureAndWatch(String, long) except that the default delay as defined by DEFAULT_DELAY is used.
static void configureAndWatch(String configFilename, long delay)
Read the configuration file configFilename if it exists.
void doConfigure(Reader reader, LoggerRepository repository)
Configure log4j by reading in a log4j.dtd compliant XML configuration file.
void doConfigure(URL url, LoggerRepository repository)
Interpret a resource pointed by a URL and set up log4j accordingly.
void doConfigure(InputStream inputStream, LoggerRepository repository)
Configure log4j by reading in a log4j.dtd compliant XML configuration file.
void doConfigure(Element element, LoggerRepository repository)
Configure by taking in an DOM element.
void doConfigure(String filename, LoggerRepository repository)
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.
Protected Methods
void doConfigure(InputSource inputSource, LoggerRepository repository)
Configure log4j by reading in a log4j.dtd compliant XML configuration file.
Appender findAppenderByName(Document doc, String appenderName)
Used internally to parse appenders by IDREF name.
Appender findAppenderByReference(Element appenderRef)
Used internally to parse appenders by IDREF element.
void parse(Element element)
Used internally to configure the log4j framework by parsing a DOM tree of XML elements based on log4j.dtd.
Appender parseAppender(Element appenderElement)
Used internally to parse an appender element.
void parseCategory(Element loggerElement)
Used internally to parse an category element.
void parseCategoryFactory(Element factoryElement)
Used internally to parse the category factory element.
void parseChildrenOfLoggerElement(Element catElement, Logger cat, boolean isRoot)
Used internally to parse the children of a category element.
void parseErrorHandler(Element element, Appender appender)
Used internally to parse an ErrorHandler element.
void parseFilters(Element element, Appender appender)
Used internally to parse a filter element.
Layout parseLayout(Element layout_element)
Used internally to parse a layout element.
void parseLevel(Element element, Logger logger, boolean isRoot)
Used internally to parse a level element.
void parseRenderer(Element element)
void parseRoot(Element rootElement)
Used internally to parse the roor category element.
ThrowableRenderer parseThrowableRenderer(Element element)
Parses throwable renderer.
void setParameter(Element elem, PropertySetter propSetter)
String subst(String value)
[Expand]
Inherited Methods
From class java.lang.Object
From interface org.apache.log4j.spi.Configurator

Fields

protected LoggerFactory catFactory

Public Constructors

public DOMConfigurator ()

No argument constructor.

Public Methods

public static void configure (URL url)

A static version of doConfigure(URL, LoggerRepository).

Throws
FactoryConfigurationError

public static void configure (String filename)

A static version of doConfigure(String, LoggerRepository).

Throws
FactoryConfigurationError

public static void configure (Element element)

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

public static void configureAndWatch (String configFilename)

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

Parameters
configFilename A log4j configuration file in XML format.

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.

public void doConfigure (Reader reader, LoggerRepository repository)

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

Throws
FactoryConfigurationError

public void doConfigure (URL url, LoggerRepository repository)

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

Parameters
url The URL to parse
repository The hierarchy to operation upon.

public void doConfigure (InputStream inputStream, LoggerRepository repository)

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

Throws
FactoryConfigurationError

public void doConfigure (Element element, LoggerRepository repository)

Configure by taking in an DOM element.

public void doConfigure (String filename, LoggerRepository repository)

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

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.

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

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.

Protected Methods

protected void doConfigure (InputSource inputSource, LoggerRepository repository)

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

Throws
FactoryConfigurationError

protected Appender findAppenderByName (Document doc, String appenderName)

Used internally to parse appenders by IDREF name.

protected Appender findAppenderByReference (Element appenderRef)

Used internally to parse appenders by IDREF element.

protected void parse (Element element)

Used internally to configure the log4j framework by parsing a DOM tree of XML elements based on log4j.dtd.

protected Appender parseAppender (Element appenderElement)

Used internally to parse an appender element.

protected void parseCategory (Element loggerElement)

Used internally to parse an category element.

protected void parseCategoryFactory (Element factoryElement)

Used internally to parse the category factory element.

protected void parseChildrenOfLoggerElement (Element catElement, Logger cat, boolean isRoot)

Used internally to parse the children of a category element.

protected void parseErrorHandler (Element element, Appender appender)

Used internally to parse an ErrorHandler element.

protected void parseFilters (Element element, Appender appender)

Used internally to parse a filter element.

protected Layout parseLayout (Element layout_element)

Used internally to parse a layout element.

protected void parseLevel (Element element, Logger logger, boolean isRoot)

Used internally to parse a level element.

protected void parseRenderer (Element element)

protected void parseRoot (Element rootElement)

Used internally to parse the roor category element.

protected ThrowableRenderer parseThrowableRenderer (Element element)

Parses throwable renderer.

Parameters
element throwableRenderer element.
Returns
  • configured throwable renderer.

protected void setParameter (Element elem, PropertySetter propSetter)

protected String subst (String value)