2.4/dev/core/src/com/google/gwt/core/ext/TreeLogger.java - gwt - Git at Google

 /*
  * 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);
 }
	/*
	* 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);
	}