Java tutorial
/* * Copyright 2008 Google Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); you may not * use this file except in compliance with the License. You may obtain a copy of * the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the * License for the specific language governing permissions and limitations under * the License. */ package com.google.gwt.core.ext; import java.net.URL; /** * An interface used to log messages in deferred binding generators. */ public abstract class TreeLogger { /** * Provides extra information to the user, generally details of what caused * the problem or what the user should do to fix the problem. How this * information is interpreted and displayed is implementation-dependent. */ public abstract static class HelpInfo { /** * @return the text to use for an anchor if not null and getURL is non-null. */ public String getAnchorText() { return null; } /** * @return the prefix to go before the link. */ public String getPrefix() { return "More info: "; } /** * @return a URL containing extra information about the problem, or null if * none. */ public URL getURL() { return null; } } /** * A type-safe enum of all possible logging severity types. */ @SuppressWarnings("hiding") public enum Type { /** * Logs an error. */ ERROR(true), /** * Logs a warning. */ WARN(true), /** * Logs information. */ INFO(false), /** * Logs information related to lower-level operation. */ TRACE(false), /** * Logs detailed information that could be useful during debugging. */ DEBUG(false), /** * Logs extremely verbose and detailed information that is typically useful * only to product implementors. */ SPAM(false), /** * Logs everything -- quite a bit of stuff. */ ALL(false); /** * Gets all the possible severity types as an array. * * @return an array of severity types */ public static Type[] instances() { return Type.values(); } private final boolean needsAttention; /** * Constructs a log type with an optional parent. */ private Type(boolean needsAttention) { this.needsAttention = needsAttention; } /** * Gets the label for this severity type. * * @return the label */ public String getLabel() { return this.toString(); } /** * Determines whether this log type is of lower priority than some other log * type. * * @param other the other log type * @return <code>true</code> if this log type is lower priority */ public boolean isLowerPriorityThan(Type other) { // Counterintuitive: higher number is lower priority. return this.ordinal() > other.ordinal(); } /** * Indicates whether this severity type represents a high severity that * should be highlighted for the user. * * @return <code>true</code> if this severity is high, otherwise * <code>false</code>. */ public boolean needsAttention() { return needsAttention; } } /** * Logs an error. */ public static final Type ERROR = Type.ERROR; /** * Logs a warning. */ public static final Type WARN = Type.WARN; /** * Logs information. */ public static final Type INFO = Type.INFO; /** * Logs information related to lower-level operation. */ public static final Type TRACE = Type.TRACE; /** * Logs detailed information that could be useful during debugging. */ public static final Type DEBUG = Type.DEBUG; /** * Logs extremely verbose and detailed information that is typically useful * only to product implementors. */ public static final Type SPAM = Type.SPAM; /** * Logs everything -- quite a bit of stuff. */ public static final Type ALL = Type.ALL; /** * A valid logger that ignores all messages. Occasionally useful when calling * methods that require a logger parameter. */ public static final TreeLogger NULL = new TreeLogger() { @Override public TreeLogger branch(Type type, String msg, Throwable caught, HelpInfo helpInfo) { return this; } @Override public boolean isLoggable(Type type) { return false; } @Override public void log(Type type, String msg, Throwable caught, HelpInfo helpInfo) { // nothing } }; /** * Calls * {@link #branch(com.google.gwt.core.ext.TreeLogger.Type, String, Throwable, com.google.gwt.core.ext.TreeLogger.HelpInfo)} * with a <code>null</code> <code>caught</code> and <code>helpInfo</code>. */ public final TreeLogger branch(TreeLogger.Type type, String msg) { return branch(type, msg, null, null); } /** * Calls * {@link #branch(com.google.gwt.core.ext.TreeLogger.Type, String, Throwable, com.google.gwt.core.ext.TreeLogger.HelpInfo)} * with a <code>null</code> <code>helpInfo</code>. */ public final TreeLogger branch(TreeLogger.Type type, String msg, Throwable caught) { return branch(type, msg, caught, null); } /** * Produces a branched logger, which can be used to write messages that are * logically grouped together underneath the current logger. The details of * how/if the resulting messages are displayed is implementation-dependent. * * <p> * The log message supplied when branching serves two purposes. First, the * message should be considered a heading for all the child messages below it. * Second, the <code>type</code> of the message provides a hint as to the * importance of the children below it. As an optimization, an implementation * could return a "no-op" logger if messages of the specified type weren't * being logged, which the implication being that all nested log messages were * no more important than the level of their branch parent. * </p> * * <p> * As an example of how hierarchical logging can be used, a branched logger in * a GUI could write log message as child items of a parent node in a tree * control. If logging to streams, such as a text console, the branched logger * could prefix each entry with a unique string and indent its text so that it * could be sorted later to reconstruct a proper hierarchy. * </p> * * @param type * @param msg an optional message to log, which can be <code>null</code> if * only an exception is being logged * @param caught an optional exception to log, which can be <code>null</code> * if only a message is being logged * @param helpInfo extra information that might be used by the logger to * provide extended information to the user * @return an instance of {@link TreeLogger} representing the new branch of * the log; may be the same instance on which this method is called */ public abstract TreeLogger branch(TreeLogger.Type type, String msg, Throwable caught, HelpInfo helpInfo); /** * Determines whether or not a log entry of the specified type would actually * be logged. Caller use this method to avoid constructing log messages that * would be thrown away. */ public abstract boolean isLoggable(TreeLogger.Type type); /** * Calls {@link #log(TreeLogger.Type, String, Throwable, HelpInfo)} with a * <code>null</code> <code>caught</code> and <code>helpInfo</code>. */ public final void log(TreeLogger.Type type, String msg) { log(type, msg, null, null); } /** * Calls {@link #log(TreeLogger.Type, String, Throwable, HelpInfo)} with a * <code>null</code> <code>helpInfo</code>. */ public final void log(TreeLogger.Type type, String msg, Throwable caught) { log(type, msg, caught, null); } /** * Logs a message and/or an exception, with optional help info. It is also * legal to call this method using <code>null</code> arguments for <i>both</i> * <code>msg</code> and <code>caught</code>, in which case the log event * can be ignored. The <code>info</code> can provide extra information to * the logger; a logger may choose to ignore this info. * * @param type * @param msg an optional message to log, which can be <code>null</code> if * only an exception is being logged * @param caught an optional exception to log, which can be <code>null</code> * if only a message is being logged * @param helpInfo extra information that might be used by the logger to * provide extended information to the user */ public abstract void log(TreeLogger.Type type, String msg, Throwable caught, HelpInfo helpInfo); }