KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > grlea > log > DebugLevel


1 package org.grlea.log;
2
3 import java.util.Collections JavaDoc;
4 import java.util.HashMap JavaDoc;
5 import java.util.Map JavaDoc;
6
7 // $Id: DebugLevel.java,v 1.9 2006/07/13 12:40:06 grlea Exp $
8 // Copyright (c) 2004-2006 Graham Lea. All rights reserved.
9
10 // Licensed under the Apache License, Version 2.0 (the "License");
11 // you may not use this file except in compliance with the License.
12 // You may obtain a copy of the License at
13 //
14 // http://www.apache.org/licenses/LICENSE-2.0
15 //
16 // Unless required by applicable law or agreed to in writing, software
17 // distributed under the License is distributed on an "AS IS" BASIS,
18 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 // See the License for the specific language governing permissions and
20 // limitations under the License.
21
22 /**
23  * <p>A Java enum defining all possible debug levels. There are seven levels, from "Fatal" (most
24  * important) to "Ludicrous" (most verbose).</p>
25  * <p>Note that tracing is not related to the debug levels, as tracing is controlled
26  * independently.</p>
27  *
28  * @version $Revision: 1.9 $
29  * @author $Author: grlea $
30  */
31 public final class
32 DebugLevel
33 {
34    /**
35     * The "Fatal" level. This should be used when an unexpected error occurs that is serious enough
36     * to cause or warrant the halting of the current process or even the whole application.
37     */
38    public static final DebugLevel L1_FATAL = new DebugLevel(1, "Fatal");
39
40    /**
41     * The "Error" level. This should be used when an unexpected error occurs that cannot be
42     * recovered from.
43     */
44    public static final DebugLevel L2_ERROR = new DebugLevel(2, "Error");
45
46    /**
47     * The "Warning" level. This should be used when an unexpected error occurs that CAN be
48     * recovered from.
49     */
50    public static final DebugLevel L3_WARN = new DebugLevel(3, "Warn");
51
52    /**
53     * The "Info" level. This should be used for reporting information to the end user.
54     */
55    public static final DebugLevel L4_INFO = new DebugLevel(4, "Info");
56
57    /**
58     * The "Debug" level. This should be used for the most basic debugging statements. This may
59     * include the direction taken in a control structure, events fired or received and the state of
60     * important objects or variables.
61     */
62    public static final DebugLevel L5_DEBUG = new DebugLevel(5, "Debug");
63
64    /**
65     * The "Verbose" level. This should be used for debugging statements that produce a large amount
66     * of output, are called often, or that don't need to be seen when performing high-level
67     * debugging. This could include extraneous events (e.g. keyboard or mouse events), the state of
68     * not-so-important objects or variables, and statements that exist within a loop. It is
69     * recommended that method parameters and return values be logged at this level (unless the
70     * amount of output they produce is "ludicrous").
71     */
72    public static final DebugLevel L6_VERBOSE = new DebugLevel(6, "Verbose");
73
74    /**
75     * The "Ludicrous" level. This should be used for debugging statements that produce a
76     * ridiculous wealth of output, e.g. printing a line for every pixel in an image.
77     */
78    public static final DebugLevel L7_LUDICROUS = new DebugLevel(7, "Ludicrous");
79
80    /**
81     * The "Trace" "level". This exists only to provide a name for output patterns that want to print
82     * the name of the debug level. It should <b>never</b> be used outside of the Simple Log package.
83     */
84    static final DebugLevel FAKE_TRACE = new DebugLevel(Integer.MAX_VALUE, "Trace");
85
86    /**
87     * A map of all {@link DebugLevel}s, keyed by the lower-case version of their name
88     * (without the Lx_ prefix).
89     */
90    private static final Map JavaDoc levelsByName;
91
92    static
93    {
94       HashMap JavaDoc levels = new HashMap JavaDoc(10, 0.8F);
95       levels.put("fatal", L1_FATAL);
96       levels.put("error", L2_ERROR);
97       levels.put("warn", L3_WARN);
98       levels.put("info", L4_INFO);
99       levels.put("debug", L5_DEBUG);
100       levels.put("verbose", L6_VERBOSE);
101       levels.put("ludicrous", L7_LUDICROUS);
102
103       levelsByName = Collections.unmodifiableMap(levels);
104    }
105
106    /**
107     * The level of this particular <code>DebugLevel</code> instance.
108     */
109    private final int level;
110
111    /**
112     * The name of this particular <code>DebugLevel</code> instance.
113     */
114    private final String JavaDoc name;
115
116    /**
117     * Creates a new <code>DebugLevel</code> with the given level. This is private to preven external
118     * instantiation.
119     *
120     * @param level the level for the new <code>DebugLevel</code>.
121     *
122     * @param name the name of the new <code>DebugLevel</code>.
123     */
124    private
125    DebugLevel(int level, String JavaDoc name)
126    {
127       this.level = level;
128       this.name = name;
129    }
130
131    /**
132     * Returns <code>true</code> if a {@link SimpleLogger} that has <b>this</b> level should log a
133     * message that has the <b>given</b> level.
134     *
135     * @param logLevel the level of the message to be considered
136     *
137     * @return <code>true</code> if the message should be logged, <code>false</code> if it should be
138     * ignored.
139     */
140    boolean
141    shouldLog(DebugLevel logLevel)
142    {
143       return logLevel.level <= this.level;
144    }
145
146    /**
147     * Returns the <code>DebugLevel</code> object associated with the given level. If the given level
148     * is above or below the defined levels, the closest level will be returned.
149     *
150     * @param level the level value whose corresponding <code>DebugLevel</code> is to be returned.
151     *
152     * @return The matching or closest matching <code>DebugLevel</code>.
153     */
154    public static DebugLevel
155    fromInt(int level)
156    {
157       switch (level)
158       {
159          case 1: return L1_FATAL;
160          case 2: return L2_ERROR;
161          case 3: return L3_WARN;
162          case 4: return L4_INFO;
163          case 5: return L5_DEBUG;
164          case 6: return L6_VERBOSE;
165          case 7: return L7_LUDICROUS;
166
167          default:
168             if (level < 1)
169                return L1_FATAL;
170             else
171                return L7_LUDICROUS;
172       }
173    }
174
175    /**
176     * Returns the <code>DebugLevel</code> object associated with the given name. The name of the
177     * debug levels is equivalent to their name in the class except with the "Lx_" prefix. E.g. the
178     * name of the {@link #L1_FATAL} level is "Fatal". The name is treated case-insensitively.
179     *
180     * @param name the name of the <code>DebugLevel</code> to return. This name is not
181     * case-sensitive, but <b>will not</b> be automatically trimmed by this method.
182     *
183     * @return The <code>DebugLevel</code> matching the given name.
184     *
185     * @throws IllegalArgumentException if <code>name</code> is <code>null</code> or if there is no
186     * <code>DebugLevel</code> associated with the specified name.
187     */
188    static DebugLevel
189    fromName(String JavaDoc name)
190    throws IllegalArgumentException JavaDoc
191    {
192       if (name == null)
193          throw new IllegalArgumentException JavaDoc("name cannot be null.");
194
195       DebugLevel level = (DebugLevel) levelsByName.get(name.toLowerCase());
196       if (level == null)
197          throw new IllegalArgumentException JavaDoc("Unrecognised DebugLevel name: '" + name + "'");
198
199       return level;
200    }
201
202    /**
203     * Returns this <code>DebugLevel</code>'s level.
204     */
205    public int
206    hashCode()
207    {
208       return level;
209    }
210
211    /**
212     * Returns <code>true</code> if the given object is a <code>DebugLevel</code> with the same level
213     * value as this <code>DebugLevel</code>.
214     */
215    public boolean
216    equals(Object JavaDoc o)
217    {
218       if (o == this)
219          return true;
220
221       if (o == null || !(o.getClass().equals(this.getClass())))
222          return false;
223
224       return this.level == ((DebugLevel) o).level;
225    }
226
227    /**
228     * Returns a string representation of this object in its current state.
229     */
230    public String JavaDoc
231    toString()
232    {
233       return name;
234    }
235 }
Popular Tags