KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > google > gwt > core > ext > TreeLogger


1 /*
2  * Copyright 2006 Google Inc.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5  * use this file except in compliance with the License. You may obtain a copy of
6  * the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13  * License for the specific language governing permissions and limitations under
14  * the License.
15  */
16 package com.google.gwt.core.ext;
17
18 import java.util.HashMap JavaDoc;
19 import java.util.Map JavaDoc;
20
21 /**
22  * An interface used to log messages in deferred binding generators.
23  */
24 public interface TreeLogger {
25
26   /**
27    * A type-safe enum of all possible logging severity types.
28    */
29   class Type {
30
31     private static final int TYPES_COUNT = 7;
32
33     /**
34      * MUST lazy-init (@link #instances}. Some compilers (javac) will cause
35      * Type's clinit to call TreeLogger's clinit <i>first</i>. This means
36      * ERROR, WARN, etc run their constructors before instances can
37      * self-initialize.
38      */
39     private static Map JavaDoc labelMap;
40     private static Type[] typeList;
41
42     static {
43       // ensure the standard types are actually registered
44 Type type = ERROR;
45     }
46
47     /**
48      * Gets all the possible severity types as an array.
49      *
50      * @return an array of severity types
51      */
52     public static Type[] instances() {
53       return (Type[]) typeList.clone();
54     }
55
56     /**
57      * Looks up a severity type by label.
58      *
59      * @param label the label of the desired severity
60      * @return the severity type labelled <code>label</code>, or
61      * <code>null</code> if no such type exists
62      */
63     public static Type valueOf(String JavaDoc label) {
64       return (Type) labelMap.get(label.toUpperCase());
65     }
66
67     private final String JavaDoc label;
68     private final boolean needsAttention;
69     private final int priority;
70
71     /**
72      * Constructs a log type with an optional parent.
73      */
74     private Type(boolean needsAttention, String JavaDoc name, int priority) {
75       if (labelMap == null) {
76         labelMap = new HashMap JavaDoc();
77       }
78       if (typeList == null) {
79         typeList = new Type[TYPES_COUNT];
80       }
81       Object JavaDoc existing = labelMap.put(name.toUpperCase(), this);
82       assert (existing == null);
83       assert (typeList[priority] == null);
84       typeList[priority] = this;
85       this.needsAttention = needsAttention;
86       this.label = name;
87       this.priority = priority;
88     }
89
90     /**
91      * Gets the label for this severity type.
92      *
93      * @return the label
94      */
95     public String JavaDoc getLabel() {
96       return label;
97     }
98
99     /**
100      * Determines whether this log type is of lower priority than some other log
101      * type.
102      *
103      * @param other the other log type
104      * @return <code>true</code> if this log type is lower priority
105      */
106     public boolean isLowerPriorityThan(Type other) {
107       return this.priority > other.priority;
108     }
109
110     /**
111      * Indicates whether this severity type represents a high severity that
112      * should be highlighted for the user.
113      *
114      * @return <code>true</code> if this severity is high, otherwise
115      * <code>false</code>.
116      */
117     public boolean needsAttention() {
118       return needsAttention;
119     }
120
121     public String JavaDoc toString() {
122       return label;
123     }
124   }
125
126   /**
127    * Logs an error.
128    */
129   Type ERROR = new Type(true, "ERROR", 0);
130
131   /**
132    * Logs a warning.
133    */
134   Type WARN = new Type(true, "WARN", 1);
135
136   /**
137    * Logs information.
138    */
139   Type INFO = new Type(false, "INFO", 2);
140
141   /**
142    * Logs information related to lower-level operation.
143    */
144   Type TRACE = new Type(false, "TRACE", 3);
145
146   /**
147    * Logs detailed information that could be useful during debugging.
148    */
149   Type DEBUG = new Type(false, "DEBUG", 4);
150
151   /**
152    * Logs extremely verbose and detailed information that is typically useful
153    * only to product implementors.
154    */
155   Type SPAM = new Type(false, "SPAM", 5);
156
157   /**
158    * Logs everything -- quite a bit of stuff.
159    */
160   Type ALL = new Type(false, "ALL", 6);
161
162   /**
163    * A valid logger that ignores all messages. Occasionally useful when calling
164    * methods that require a logger parameter.
165    */
166   TreeLogger NULL = new TreeLogger() {
167     public TreeLogger branch(Type type, String JavaDoc msg, Throwable JavaDoc caught) {
168       return this;
169     }
170
171     public boolean isLoggable(Type type) {
172       return false;
173     }
174
175     public void log(Type type, String JavaDoc msg, Throwable JavaDoc caught) {
176       // nothing
177 }
178   };
179
180   /**
181    * Produces a branched logger, which can be used to write messages that are
182    * logically grouped together underneath the current logger. The details of
183    * how/if the resulting messages are displayed is implementation-dependent.
184    *
185    * <p>
186    * The log message supplied when branching serves two purposes. First, the
187    * message should be considered a heading for all the child messages below it.
188    * Second, the <code>type</code> of the message provides a hint as to the
189    * importance of the children below it. As an optimization, an implementation
190    * could return a "no-op" logger if messages of the specified type weren't
191    * being logged, which the implication being that all nested log messages were
192    * no more important than the level of their branch parent.
193    * </p>
194    *
195    * <p>
196    * As an example of how hierarchical logging can be used, a branched logger in
197    * a GUI could write log message as child items of a parent node in a tree
198    * control. If logging to streams, such as a text console, the branched logger
199    * could prefix each entry with a unique string and indent its text so that it
200    * could be sorted later to reconstruct a proper hierarchy.
201    * </p>
202    *
203    * @param type
204    * @param msg An optional message to log, which can be <code>null</code> if
205    * only an exception is being logged
206    * @param caught An optional exception to log, which can be <code>null</code>
207    * if only a message is being logged
208    * @return an instance of {@link TreeLogger} representing the new branch of
209    * the log. May be the same instance on which this method is called
210    */
211   TreeLogger branch(TreeLogger.Type type, String JavaDoc msg, Throwable JavaDoc caught);
212
213   /**
214    * Determines whether or not a log entry of the specified type would actually
215    * be logged. Caller use this method to avoid constructing log messages that
216    * would be thrown away.
217    */
218   boolean isLoggable(TreeLogger.Type type);
219
220   /**
221    * Logs a message and/or an exception. It is also legal to call this method
222    * using <code>null</code> arguments for <i>both</i> <code>msg</code> and
223    * <code>caught</code>, in which case the log event can be ignored.
224    *
225    * @param type
226    * @param msg An optional message to log, which can be <code>null</code> if
227    * only an exception is being logged
228    * @param caught An optional exception to log, which can be <code>null</code>
229    * if only a message is being logged
230    */
231   void log(TreeLogger.Type type, String JavaDoc msg, Throwable JavaDoc caught);
232 }
233
Popular Tags