Log4j 1.1.3

org.apache.log4j
Class Hierarchy

java.lang.Object
  |
  +--org.apache.log4j.Hierarchy

public class Hierarchy
extends Object

This class is specialized in retrieving categories by name and also maintaining the category hierarchy.

The casual user should not have to deal with this class directly. In fact, up until version 0.9.0, this class had default package access. However, if you are in an environment where multiple applications run in the same VM, then read on.

The structure of the category hierarchy is maintained by the getInstance(java.lang.String) method. The hierarchy is such that children link to their parent but parents do not have any pointers to their children. Moreover, categories can be instantiated in any order, in particular descendant before ancestor.

In case a descendant is created before a particular ancestor, then it creates a provision node for the ancestor and adds itself to the provision node. Other descendants of the same ancestor add themselves to the previously created provision node.

See the code below for further details.

Author:
Ceki Gülcü

Constructor Summary
Hierarchy(Category root)
          Create a new Category hierarchy.
 
Method Summary
 void addRenderer(Class classToRender, ObjectRenderer or)
          Add an object renderer for a specific class.
 void clear()
          This call will clear all category definitions from the internal hashtable.
 void disable(Priority p)
          Disable all logging requests of priority equal to or below the priority parameter p, for all categories in this hierarchy.
 void disable(String priorityStr)
          Similar to disable(Priority) except that the priority argument is given as a String.
 void disableAll()
          Disable all logging requests regardless of category and priority.
 void disableDebug()
          Disable all logging requests of priority DEBUG regardless of category.
 void disableInfo()
          Disable all logging requests of priority INFO and below regardless of category.
 void enableAll()
          Undoes the effect of calling any of disable(java.lang.String), disableAll(), disableDebug() and disableInfo() methods.
 Category exists(String name)
          Check if the named category exists in the hierarchy.
 Enumeration getCurrentCategories()
          Returns all the currently defined categories in this hierarchy as an Enumeration.
 Category getInstance(String name)
          Return a new category instance named as the first parameter using the default factory.
 Category getInstance(String name, CategoryFactory factory)
          Return a new category instance named as the first parameter using factory.
 RendererMap getRendererMap()
          Get the renderer map for this hierarchy.
 Category getRoot()
          Get the root of this hierarchy.
 boolean isDisabled(int level)
           
 void overrideAsNeeded(String override)
          Override the shipped code flag if the override parameter is not null.
 void resetConfiguration()
          Reset all values contained in this hierarchy instance to their default.
 void setCategoryFactory(CategoryFactory factory)
          Set the default CategoryFactory instance.
 void setDisableOverride(String override)
          Set the disable override value given a string.
 void shutdown()
          Shutting down a hierarchy will safely close and remove all appenders in all categories including the root category.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Hierarchy

public Hierarchy(Category root)
Create a new Category hierarchy.
Parameters:
root - The root of the new hierarchy.
Method Detail

addRenderer

public void addRenderer(Class classToRender,
                        ObjectRenderer or)
Add an object renderer for a specific class.

clear

public void clear()
This call will clear all category definitions from the internal hashtable. Invoking this method will irrevocably mess up the category hierarchy.

You should really know what you are doing before invoking this method.

Since:
0.9.0

exists

public Category exists(String name)
Check if the named category exists in the hierarchy. If so return its reference, otherwise returns null.
Parameters:
name - The name of the category to search for.

disable

public void disable(String priorityStr)
Similar to disable(Priority) except that the priority argument is given as a String.

disable

public void disable(Priority p)
Disable all logging requests of priority equal to or below the priority parameter p, for all categories in this hierarchy. Logging requests of higher priority then p remain unaffected.

Nevertheless, if the BasicConfigurator.DISABLE_OVERRIDE_KEY system property is set to "true" or any value other than "false", then logging requests are evaluated as usual, i.e. according to the Basic Selection Rule.

The "disable" family of methods are there for speed. They allow printing methods such as debug, info, etc. to return immediately after an integer comparison without walking the category hierarchy. In most modern computers an integer comparison is measured in nanoseconds where as a category walk is measured in units of microseconds.

Other configurators define alternate ways of overriding the disable override flag. See PropertyConfigurator and DOMConfigurator.

Since:
0.8.5

disableAll

public void disableAll()
Disable all logging requests regardless of category and priority. This method is equivalent to calling disable(java.lang.String) with the argument Priority.FATAL, the highest possible priority.
Since:
0.8.5

disableDebug

public void disableDebug()
Disable all logging requests of priority DEBUG regardless of category. Invoking this method is equivalent to calling disable(java.lang.String) with the argument Priority.DEBUG.
Since:
0.8.5

disableInfo

public void disableInfo()
Disable all logging requests of priority INFO and below regardless of category. Note that DEBUG messages are also disabled.

Invoking this method is equivalent to calling disable(Priority) with the argument Priority.INFO.

Since:
0.8.5

enableAll

public void enableAll()
Undoes the effect of calling any of disable(java.lang.String), disableAll(), disableDebug() and disableInfo() methods. More precisely, invoking this method sets the Category class internal variable called disable to its default "off" value.
Since:
0.8.5

overrideAsNeeded

public void overrideAsNeeded(String override)
Override the shipped code flag if the override parameter is not null.

If override is null then there is nothing to do. Otherwise, set Category.shippedCode to false if override has a value other than "false".


getInstance

public Category getInstance(String name)
Return a new category instance named as the first parameter using the default factory.

If a category of that name already exists, then it will be returned. Otherwise, a new category will be instantiated and then linked with its existing ancestors as well as children.

Parameters:
name - The name of the category to retrieve.

getInstance

public Category getInstance(String name,
                            CategoryFactory factory)
Return a new category instance named as the first parameter using factory.

If a category of that name already exists, then it will be returned. Otherwise, a new category will be instantiated by the factory parameter and linked with its existing ancestors as well as children.

Parameters:
name - The name of the category to retrieve.
factory - The factory that will make the new category instance.

getCurrentCategories

public Enumeration getCurrentCategories()
Returns all the currently defined categories in this hierarchy as an Enumeration.

The root category is not included in the returned Enumeration.


isDisabled

public boolean isDisabled(int level)

getRendererMap

public RendererMap getRendererMap()
Get the renderer map for this hierarchy.

getRoot

public Category getRoot()
Get the root of this hierarchy.
Since:
0.9.0

resetConfiguration

public void resetConfiguration()
Reset all values contained in this hierarchy instance to their default. This removes all appenders from all categories, sets the priority of all non-root categories to null, sets their additivity flag to true and sets the priority of the root category to DEBUG. Moreover, message disabling is set its default "off" value.

Existing categories are not removed. They are just reset.

This method should be used sparingly and with care as it will block all logging until it is completed.

Since:
version 0.8.5

setCategoryFactory

public void setCategoryFactory(CategoryFactory factory)
Set the default CategoryFactory instance.
Since:
1.1

setDisableOverride

public void setDisableOverride(String override)
Set the disable override value given a string.
Since:
1.1

shutdown

public void shutdown()
Shutting down a hierarchy will safely close and remove all appenders in all categories including the root category.

Some appenders such as SocketAppender and 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.

Since:
1.0

Log4j 1.1.3

Please notify me about new log4j releases.