Log4j 1.0.4

org.apache.log4j
Class Hierarchy

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

public class Hierarchy
extends Object

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

The casual user should never have to deal with this class firectly. In fact, up until version 0.9.0, this class had default package access.

The structure of the category hierachy is maintained by the getInstance(java.lang.String) method. The hierrachy 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 decendant before ancestor.

In case a decendant is created before a particular ancestor, then it creates a provision node for the ancestor and adds itself to the provision node. Other decendants 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.
 Category exists(String name)
          Check if the named category exists in the hirarchy.
 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.
 void shutdown()
          Shutting down a hiearchy will safely close and remove all appenders in all the categories including root.
 
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 hiearchy.

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 hirarchy. If so return its reference, otherwise returns null.
Parameters:
name - The name of the category to search for.

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 lthen inked with its existing ancestors as well as children.

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

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 retreive.
factory - The factory that will make the new category instance.

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

shutdown

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

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

Please notify me about new log4j releases.