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