## 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>

There are sample XML files included in the package.

Since:
  0.8.3
Author:
  Christopher Taylor, Ceki Gülcü, Anders Kristensen

Field Summary
`protected LoggerFactory` `catFactory`

Fields inherited from interface org.apache.log4j.spi.Configurator
`INHERITED, NULL`

Constructor Summary
`DOMConfigurator()` No argument constructor.

Method Summary
`static void` `configure(org.w3c.dom.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(org.w3c.dom.Element element, LoggerRepository repository)` Configure by taking in an DOM element.
`protected void` `doConfigure(org.xml.sax.InputSource inputSource, LoggerRepository repository)` Configure log4j by reading in a log4j.dtd compliant XML configuration file.
`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.
`protected Appender` `findAppenderByName(org.w3c.dom.Document doc, String appenderName)` Used internally to parse appenders by IDREF name.
`protected Appender` `findAppenderByReference(org.w3c.dom.Element appenderRef)` Used internally to parse appenders by IDREF element.
`protected void` `parse(org.w3c.dom.Element element)` Used internally to configure the log4j framework by parsing a DOM tree of XML elements based on log4j.dtd.
`protected Appender` `parseAppender(org.w3c.dom.Element appenderElement)` Used internally to parse an appender element.
`protected void` `parseCategory(org.w3c.dom.Element loggerElement)` Used internally to parse an category element.
`protected void` `parseCategoryFactory(org.w3c.dom.Element factoryElement)` Used internally to parse the category factory element.
`protected void` `parseChildrenOfLoggerElement(org.w3c.dom.Element catElement, Logger cat, boolean isRoot)` Used internally to parse the children of a category element.
`static Object` `parseElement(org.w3c.dom.Element element, Properties props, Class expectedClass)` Creates an object and processes any nested param elements but does not call activateOptions.
`protected void` `parseErrorHandler(org.w3c.dom.Element element, Appender appender)` Used internally to parse an `ErrorHandler` element.
`protected void` `parseFilters(org.w3c.dom.Element element, Appender appender)` Used internally to parse a filter element.
`protected Layout` `parseLayout(org.w3c.dom.Element layout_element)` Used internally to parse a layout element.
`protected void` `parseLevel(org.w3c.dom.Element element, Logger logger, boolean isRoot)` Used internally to parse a level element.
`protected void` `parseRenderer(org.w3c.dom.Element element)`
`protected void` `parseRoot(org.w3c.dom.Element rootElement)` Used internally to parse the roor category element.
`protected ThrowableRenderer` `parseThrowableRenderer(org.w3c.dom.Element element)` Parses throwable renderer.
`protected void` `setParameter(org.w3c.dom.Element elem, PropertySetter propSetter)`
`static void` `setParameter(org.w3c.dom.Element elem, PropertySetter propSetter, Properties props)` Sets a parameter based from configuration file content.
`protected String` `subst(String value)`
`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`

Field Detail

### catFactory

    protected LoggerFactory catFactory

Constructor Detail

### DOMConfigurator

    public DOMConfigurator()

  No argument constructor.

Method Detail

### findAppenderByName

    protected Appender findAppenderByName(org.w3c.dom.Document doc,
                                          String appenderName)

  Used internally to parse appenders by IDREF name.

### findAppenderByReference

    protected Appender findAppenderByReference(org.w3c.dom.Element appenderRef)

  Used internally to parse appenders by IDREF element.

### parseAppender

    protected Appender parseAppender(org.w3c.dom.Element appenderElement)

  Used internally to parse an appender element.

### parseErrorHandler

    protected void parseErrorHandler(org.w3c.dom.Element element,
                                     Appender appender)

  Used internally to parse an `ErrorHandler` element.

### parseFilters

    protected void parseFilters(org.w3c.dom.Element element,
                                Appender appender)

  Used internally to parse a filter element.

### parseCategory

    protected void parseCategory(org.w3c.dom.Element loggerElement)

  Used internally to parse an category element.

### parseCategoryFactory

    protected void parseCategoryFactory(org.w3c.dom.Element factoryElement)

  Used internally to parse the category factory element.

### parseRoot

    protected void parseRoot(org.w3c.dom.Element rootElement)

  Used internally to parse the roor category element.

### parseChildrenOfLoggerElement

    protected void parseChildrenOfLoggerElement(org.w3c.dom.Element catElement,
                                                Logger cat,
                                                boolean isRoot)

  Used internally to parse the children of a category element.

### parseLayout

    protected Layout parseLayout(org.w3c.dom.Element layout_element)

  Used internally to parse a layout element.

### parseRenderer

    protected void parseRenderer(org.w3c.dom.Element element)

### parseThrowableRenderer

    protected ThrowableRenderer parseThrowableRenderer(org.w3c.dom.Element element)

  Parses throwable renderer.

  Parameters:
    `element` - throwableRenderer element.
  Returns:
    configured throwable renderer.
  Since:
    1.2.16.

### parseLevel

    protected void parseLevel(org.w3c.dom.Element element,
                              Logger logger,
                              boolean isRoot)

  Used internally to parse a level element.

### setParameter

    protected void setParameter(org.w3c.dom.Element elem,
                                PropertySetter propSetter)

### configure

    public static void configure(org.w3c.dom.Element element)

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

### 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.

### 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.

### doConfigure

    public void doConfigure(String filename,
                            LoggerRepository repository)

### 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.

### doConfigure

    public void doConfigure(InputStream inputStream,
                            LoggerRepository repository)
                     throws javax.xml.parsers.FactoryConfigurationError

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

  Throws:
    `javax.xml.parsers.FactoryConfigurationError`

### doConfigure

    public void doConfigure(Reader reader,
                            LoggerRepository repository)
                     throws javax.xml.parsers.FactoryConfigurationError

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

  Throws:
    `javax.xml.parsers.FactoryConfigurationError`

### doConfigure

    protected void doConfigure(org.xml.sax.InputSource inputSource,
                               LoggerRepository repository)
                        throws javax.xml.parsers.FactoryConfigurationError

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

  Throws:
    `javax.xml.parsers.FactoryConfigurationError`

### doConfigure

    public void doConfigure(org.w3c.dom.Element element,
                            LoggerRepository repository)

  Configure by taking in an DOM element.

### configure

    public static void configure(String filename)
                          throws javax.xml.parsers.FactoryConfigurationError

  A static version of `doConfigure(String, LoggerRepository)`.

  Throws:
    `javax.xml.parsers.FactoryConfigurationError`

### configure

    public static void configure(URL url)
                          throws javax.xml.parsers.FactoryConfigurationError

  A static version of `doConfigure(URL, LoggerRepository)`.

  Throws:
    `javax.xml.parsers.FactoryConfigurationError`

### parse

    protected void parse(org.w3c.dom.Element element)

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

### subst

    protected String subst(String value)

### 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.
  Since:
    1.2.15

### setParameter

    public static void setParameter(org.w3c.dom.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
  Since:
    1.2.15

### parseElement

    public static Object parseElement(org.w3c.dom.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.
  Since:
    1.2.15

Copyright © 1999-2010 Apache Software Foundation. All Rights Reserved.