001: /**
002: * Copyright (C) 2001-2003 France Telecom R&D
003: *
004: * This library is free software; you can redistribute it and/or
005: * modify it under the terms of the GNU Lesser General Public
006: * License as published by the Free Software Foundation; either
007: * version 2 of the License, or (at your option) any later version.
008: *
009: * This library is distributed in the hope that it will be useful,
010: * but WITHOUT ANY WARRANTY; without even the implied warranty of
011: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012: * Lesser General Public License for more details.
013: *
014: * You should have received a copy of the GNU Lesser General Public
015: * License along with this library; if not, write to the Free Software
016: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
017: */package org.objectweb.util.monolog.api;
018:
019: import java.util.Enumeration;
020:
021: /**
022: *<P>A TopicalLogger dispatches events to a set of Handlers. A TopicalLogger
023: * is a sort of message router.</P>
024: *
025: * <P>A topic is associated with each TopicalLogger. A topic
026: * is represented by a dotted string, which is used to build a hierarchical
027: * namespace. The latter should typically be aligned with the Java packaging
028: * namespace.</P>
029: *
030: * <P>The name hierarchy of TopicalLogger allows adding properties
031: * inheritance. For example, a TopicalLogger with the "a.b.c" name can inherit
032: * of the Handlers list and the level from the "a.b" parent. </P>
033: *
034: *<P>Another property for a TopicalLogger is the capacity to have several
035: * topics. This is important when a component is used by several other
036: * components. This will allow events logged by the shared component to
037: * appear for each component using this shared component. A consequence
038: * of this property is that a Logger may have several parents</P>
039: *
040: * <P>The additivity flag indicates if the current TopicalLogger inherits the
041: * handlers of its parents. The default value is true.</P>
042: */
043: public interface TopicalLogger extends Logger {
044:
045: // HANDLER MANAGEMENT //
046: //--------------------//
047:
048: /**
049: * A TopicalLogger manages a list of Handler instances. This method
050: * allows adding a handler to this list. The addHandler method returns
051: * true only if the Handler did not exist
052: */
053: void addHandler(Handler h) throws Exception;
054:
055: /**
056: * It returns the list of the handler associated to this logger.
057: * @return an array of Handler or an empty array.
058: */
059: Handler[] getHandler();
060:
061: /**
062: * It returns the handler which the name is equals to the parameter
063: * @hn is the handler name
064: * @return an Handler or a null value.
065: */
066: Handler getHandler(String hn);
067:
068: /**
069: * A TopicalLogger manages a list of Handler instances. This method
070: * allows removing a handler to this list.
071: */
072: void removeHandler(Handler h) throws Exception;
073:
074: /**
075: * A TopicalLogger manages a list of Handler instances. This method
076: * allows removing all handler.
077: */
078: void removeAllHandlers() throws Exception;
079:
080: /**
081: * It assigns the additivity flag for this logger instance.
082: */
083: void setAdditivity(boolean a);
084:
085: /**
086: * It retrieves the additivity flag for this logger instance.
087: */
088: boolean getAdditivity();
089:
090: // TOPIC MANAGEMENT //
091: //------------------//
092:
093: /**
094: *This method allows adding a topic to a TopicalLogger. This actions change
095: * the hierarchical structure, but also the list of handlers. The list of handlers
096: * of a TopicalLogger is composed of its handlers and all handlers inherited
097: * from its parents. Adding a topic changes the inherited handlers list.
098: */
099: void addTopic(String topic) throws Exception;
100:
101: /**
102: *This method allows getting a topic list of this TopicalLogger.
103: */
104: String[] getTopic();
105:
106: /**
107: * This method allows getting a topic list of this TopicalLogger.
108: * Only kept for the backward compatibility.
109: */
110: Enumeration getTopics();
111:
112: /**
113: *This method allows removing a topic to a TopicalLogger. This actions change
114: * the hierarchical structure, but also the list of handlers. The list of handlers
115: * of a TopicalLogger is composed of its handlers and all handlers inherited
116: * from its parents. Removing a topic changes the inherited handlers list.
117: */
118: void removeTopic(String topic) throws Exception;
119: }
|