001: /*
002: * Copyright 2007 Google Inc.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005: * use this file except in compliance with the License. You may obtain a copy of
006: * the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
012: * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013: * License for the specific language governing permissions and limitations under
014: * the License.
015: */
016: package com.google.gwt.core.ext;
017:
018: /**
019: * An interface used to log messages in deferred binding generators.
020: */
021: public interface TreeLogger {
022:
023: /**
024: * A type-safe enum of all possible logging severity types.
025: */
026: @SuppressWarnings("hiding")
027: enum Type {
028:
029: /**
030: * Logs an error.
031: */
032: ERROR(true),
033:
034: /**
035: * Logs a warning.
036: */
037: WARN(true),
038:
039: /**
040: * Logs information.
041: */
042: INFO(false),
043:
044: /**
045: * Logs information related to lower-level operation.
046: */
047: TRACE(false),
048:
049: /**
050: * Logs detailed information that could be useful during debugging.
051: */
052: DEBUG(false),
053:
054: /**
055: * Logs extremely verbose and detailed information that is typically useful
056: * only to product implementors.
057: */
058: SPAM(false),
059:
060: /**
061: * Logs everything -- quite a bit of stuff.
062: */
063: ALL(false);
064:
065: /**
066: * Gets all the possible severity types as an array.
067: *
068: * @return an array of severity types
069: */
070: public static Type[] instances() {
071: return Type.values();
072: }
073:
074: private final boolean needsAttention;
075:
076: /**
077: * Constructs a log type with an optional parent.
078: */
079: private Type(boolean needsAttention) {
080: this .needsAttention = needsAttention;
081: }
082:
083: /**
084: * Gets the label for this severity type.
085: *
086: * @return the label
087: */
088: public String getLabel() {
089: return this .toString();
090: }
091:
092: /**
093: * Determines whether this log type is of lower priority than some other log
094: * type.
095: *
096: * @param other the other log type
097: * @return <code>true</code> if this log type is lower priority
098: */
099: public boolean isLowerPriorityThan(Type other) {
100: // Counterintuitive: higher number is lower priority.
101: return this .ordinal() > other.ordinal();
102: }
103:
104: /**
105: * Indicates whether this severity type represents a high severity that
106: * should be highlighted for the user.
107: *
108: * @return <code>true</code> if this severity is high, otherwise
109: * <code>false</code>.
110: */
111: public boolean needsAttention() {
112: return needsAttention;
113: }
114: }
115:
116: /**
117: * Logs an error.
118: */
119: Type ERROR = Type.ERROR;
120:
121: /**
122: * Logs a warning.
123: */
124: Type WARN = Type.WARN;
125:
126: /**
127: * Logs information.
128: */
129: Type INFO = Type.INFO;
130:
131: /**
132: * Logs information related to lower-level operation.
133: */
134: Type TRACE = Type.TRACE;
135:
136: /**
137: * Logs detailed information that could be useful during debugging.
138: */
139: Type DEBUG = Type.DEBUG;
140:
141: /**
142: * Logs extremely verbose and detailed information that is typically useful
143: * only to product implementors.
144: */
145: Type SPAM = Type.SPAM;
146:
147: /**
148: * Logs everything -- quite a bit of stuff.
149: */
150: Type ALL = Type.ALL;
151:
152: /**
153: * A valid logger that ignores all messages. Occasionally useful when calling
154: * methods that require a logger parameter.
155: */
156: TreeLogger NULL = new TreeLogger() {
157: public TreeLogger branch(Type type, String msg, Throwable caught) {
158: return this ;
159: }
160:
161: public boolean isLoggable(Type type) {
162: return false;
163: }
164:
165: public void log(Type type, String msg, Throwable caught) {
166: // nothing
167: }
168: };
169:
170: /**
171: * Produces a branched logger, which can be used to write messages that are
172: * logically grouped together underneath the current logger. The details of
173: * how/if the resulting messages are displayed is implementation-dependent.
174: *
175: * <p>
176: * The log message supplied when branching serves two purposes. First, the
177: * message should be considered a heading for all the child messages below it.
178: * Second, the <code>type</code> of the message provides a hint as to the
179: * importance of the children below it. As an optimization, an implementation
180: * could return a "no-op" logger if messages of the specified type weren't
181: * being logged, which the implication being that all nested log messages were
182: * no more important than the level of their branch parent.
183: * </p>
184: *
185: * <p>
186: * As an example of how hierarchical logging can be used, a branched logger in
187: * a GUI could write log message as child items of a parent node in a tree
188: * control. If logging to streams, such as a text console, the branched logger
189: * could prefix each entry with a unique string and indent its text so that it
190: * could be sorted later to reconstruct a proper hierarchy.
191: * </p>
192: *
193: * @param type
194: * @param msg An optional message to log, which can be <code>null</code> if
195: * only an exception is being logged
196: * @param caught An optional exception to log, which can be <code>null</code>
197: * if only a message is being logged
198: * @return an instance of {@link TreeLogger} representing the new branch of
199: * the log. May be the same instance on which this method is called
200: */
201: TreeLogger branch(TreeLogger.Type type, String msg, Throwable caught);
202:
203: /**
204: * Determines whether or not a log entry of the specified type would actually
205: * be logged. Caller use this method to avoid constructing log messages that
206: * would be thrown away.
207: */
208: boolean isLoggable(TreeLogger.Type type);
209:
210: /**
211: * Logs a message and/or an exception. It is also legal to call this method
212: * using <code>null</code> arguments for <i>both</i> <code>msg</code> and
213: * <code>caught</code>, in which case the log event can be ignored.
214: *
215: * @param type
216: * @param msg An optional message to log, which can be <code>null</code> if
217: * only an exception is being logged
218: * @param caught An optional exception to log, which can be <code>null</code>
219: * if only a message is being logged
220: */
221: void log(TreeLogger.Type type, String msg, Throwable caught);
222: }
|