TopicalLogger


1   /**
2    * Copyright (C) 2001-2003 France Telecom R&D
3    *
4    * This library is free software; you can redistribute it and/or
5    * modify it under the terms of the GNU Lesser General Public
6    * License as published by the Free Software Foundation; either
7    * version 2 of the License, or (at your option) any later version.
8    *
9    * This library is distributed in the hope that it will be useful,
10   * but WITHOUT ANY WARRANTY; without even the implied warranty of
11   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12   * Lesser General Public License for more details.
13   *
14   * You should have received a copy of the GNU Lesser General Public
15   * License along with this library; if not, write to the Free Software
16   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
17   */
18  
19  package org.objectweb.util.monolog.api;
20  
21  import java.util.Enumeration  ;
22  
23  /**
24   *<P>A TopicalLogger dispatches events to a set of Handlers. A TopicalLogger
25   * is a sort of message router.</P>
26   *
27   * <P>A topic is associated with each TopicalLogger. A topic
28   * is represented by a dotted string, which is used to build a hierarchical
29   * namespace. The latter should typically be aligned with the Java packaging
30   * namespace.</P>
31   *
32   * <P>The name hierarchy of TopicalLogger allows adding properties
33   * inheritance. For example, a TopicalLogger with the "a.b.c" name can inherit
34   * of the Handlers list and the level from the "a.b" parent. </P>
35   *
36   *<P>Another property for a TopicalLogger is the capacity to have several
37   * topics. This is important when a component is used by several other
38   * components. This will allow events logged by the shared component to
39   * appear for each component using this shared component. A consequence
40   *  of this property is that a Logger may have several parents</P>
41   *
42   * <P>The additivity flag indicates if the current TopicalLogger inherits the
43   * handlers of its parents. The default value is true.</P>
44   */
45  public interface TopicalLogger extends Logger {
46  
47      // HANDLER MANAGEMENT //
48      //--------------------//
49  
50      /**
51       * A TopicalLogger manages a list of Handler instances. This method
52       * allows adding a handler to this list. The addHandler method returns
53       * true only if the Handler did not exist
54       */
55      void addHandler(Handler h) throws Exception  ;
56  
57      /**
58       * It returns the list of the handler associated to this logger.
59       * @return an array of Handler or an empty array.
60       */
61      Handler[] getHandler();
62  
63      /**
64       * It returns the handler which the name is equals to the parameter
65       * @hn is the handler name
66       * @return an Handler or a null value.
67       */
68      Handler getHandler(String   hn);
69  
70      /**
71      * A TopicalLogger manages a list of Handler instances. This method
72      * allows removing a handler to this list.
73      */
74     void removeHandler(Handler h) throws Exception  ;
75  
76      /**
77      * A TopicalLogger manages a list of Handler instances. This method
78      * allows removing all handler.
79      */
80     void removeAllHandlers() throws Exception  ;
81  
82      /**
83       * It assigns the additivity flag for this logger instance.
84       */
85      void setAdditivity(boolean a);
86  
87      /**
88       * It retrieves the additivity flag for this logger instance.
89       */
90      boolean getAdditivity();
91  
92  
93  
94      // TOPIC MANAGEMENT //
95      //------------------//
96  
97      /**
98       *This method allows adding a topic to a TopicalLogger. This actions change
99       * the hierarchical structure, but also the list of handlers. The list of handlers
100      * of a TopicalLogger is composed of its handlers and all handlers inherited
101      * from its parents. Adding a topic changes the inherited handlers list.
102      */
103     void addTopic(String   topic)  throws Exception   ;
104 
105     /**
106      *This method allows getting a topic list of this TopicalLogger.
107      */
108     String  [] getTopic();
109 
110     /**
111      * This method allows getting a topic list of this TopicalLogger.
112      * Only kept for the backward compatibility.
113      */
114     Enumeration   getTopics();
115 
116     /**
117      *This method allows removing a topic to a TopicalLogger. This actions change
118      * the hierarchical structure, but also the list of handlers. The list of handlers
119      * of a TopicalLogger is composed of its handlers and all handlers inherited
120      * from its parents. Removing a topic changes the inherited handlers list.
121      */
122     void removeTopic(String   topic)  throws Exception   ;
123 }
124
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags