com.gemstone.gemfire.LogWriter Maven / Gradle / Ivy

Go to download
/*
 * Copyright (c) 2010-2015 Pivotal Software, Inc. All rights reserved.
 *
 * 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. See accompanying
 * LICENSE file.
 */

package com.gemstone.gemfire;

import com.gemstone.gemfire.distributed.DistributedSystem;
import com.gemstone.gemfire.i18n.LogWriterI18n;
import com.gemstone.org.jgroups.util.GFLogWriter;

import java.util.logging.Handler;
/**
  * Defines methods available to clients that want to write a log message
  * to their GemFire distributed system log file.
  * 
  * Instances of this interface can be obtained by calling
  * {@link DistributedSystem#getLogWriter}.
  * 

  * For any logged message the log file will contain:
  * 

  *  The message's level.
  * 
 The time the message was logged.
  * 
 The id of the thread that logged the message.
  * 
 The message itself which can be a string and/or an exception
  *      including the exception's stack trace.
  * 
  * 
  * A message always has a level.
  * Logging levels are ordered. Enabling logging at a given level also
  * enables logging at higher levels. The higher the level the more
  * important and urgent the message.
  * 

  * The levels, in descending order, are:
  * 

  *  severe  (highest value) is a message level indicating a serious failure.
  *   In general severe messages should describe events that
  *   are of considerable importance and which will prevent normal program
  *   execution. They should be reasonably intelligible to end users and
  *   to information managers.
  * 
 error  
  *   In general error messages should describe events that
  *   are of considerable importance but will not prevent normal program
  *   execution. They should be reasonably intelligible to end users and
  *   to information managers. They are weaker than severe and
  *   stronger than warning.
  * 
 warning is a message level indicating a potential problem.
  *   In general warning messages should describe events that
  *   will be of interest to end users or information managers, or which indicate
  *   potential problems.
  * 
 info is a message level for informational messages.
  *   Typically info messages should be reasonably significant
  *   and should make sense to end users and system administrators.
  * 
 config is a message level for static configuration messages.
  *   config messages are intended to provide a variety of static
  *   configuration information, to assist in debugging problems that may be
  *   associated with particular configurations.
  * 
 fine is a message level providing tracing information.
  *   In general the fine level should be used for information
  *   that will be broadly interesting to developers. This level is for
  *   the lowest volume, and most important, tracing messages.
  * 
 finer indicates a fairly detailed tracing message.
  *   Logging calls for entering, returning, or throwing an exception
  *   are traced at the finer level.
  * 
 finest (lowest value) indicates a highly detailed tracing message.
  *   In general the finest level should be used for the most
  *   voluminous detailed tracing messages.
  * 
  * 
  * For each level methods exist that will request a message, at that
  * level, to be logged. These methods are all named after their level.
  * 

  * For each level a method exists that returns a boolean indicating
  * if messages at that level will currently be logged. The names
  * of these methods are of the form: levelEnabled.
  *
  * @author      darrel
  */
public interface LogWriter extends GFLogWriter {
    /**
     * Returns true if "severe" log messages are enabled.
     * Returns false if "severe" log messages are disabled.
     */
    public boolean severeEnabled();
    /**
     * Writes both a message and exception to this writer.
     * The message level is "severe".
     */
    public void severe(String msg, Throwable ex);
    /**
     * Writes a message to this writer.
     * The message level is "severe".
     */
    public void severe(String msg);
    /**
     * Writes an exception to this writer.
     * The exception level is "severe".
     */
    public void severe(Throwable ex);
    /**
     * Returns true if "error" log messages are enabled.
     * Returns false if "error" log messages are disabled.
     */
    public boolean errorEnabled();
    /**
     * Writes both a message and exception to this writer.
     * The message level is "error".
     */
    public void error(String msg, Throwable ex);
    /**
     * Writes a message to this writer.
     * The message level is "error".
     */
    public void error(String msg);
    /**
     * Writes an exception to this writer.
     * The exception level is "error".
     */
    public void error(Throwable ex);
    /**
     * Returns true if "warning" log messages are enabled.
     * Returns false if "warning" log messages are disabled.
     */
    public boolean warningEnabled();
    /**
     * Writes both a message and exception to this writer.
     * The message level is "warning".
     */
    public void warning(String msg, Throwable ex);
    /**
     * Writes a message to this writer.
     * The message level is "warning".
     */
    public void warning(String msg);
    /**
     * Writes an exception to this writer.
     * The exception level is "warning".
     */
    public void warning(Throwable ex);
    /**
     * Returns true if "info" log messages are enabled.
     * Returns false if "info" log messages are disabled.
     */
    public boolean infoEnabled();
    /**
     * Writes both a message and exception to this writer.
     * The message level is "information".
     */
    public void info(String msg, Throwable ex);
    /**
     * Writes a message to this writer.
     * The message level is "information".
     */
    public void info(String msg);
    /**
     * Writes an exception to this writer.
     * The exception level is "information".
     */
    public void info(Throwable ex);
    /**
     * Returns true if "config" log messages are enabled.
     * Returns false if "config" log messages are disabled.
     */
    public boolean configEnabled();
    /**
     * Writes both a message and exception to this writer.
     * The message level is "config".
     */
    public void config(String msg, Throwable ex);
    /**
     * Writes a message to this writer.
     * The message level is "config".
     */
    public void config(String msg);
    /**
     * Writes an exception to this writer.
     * The exception level is "config".
     */
    public void config(Throwable ex);
    /**
     * Returns true if "fine" log messages are enabled.
     * Returns false if "fine" log messages are disabled.
     */
    public boolean fineEnabled();
    /**
     * Writes both a message and exception to this writer.
     * The message level is "fine".
     */
    public void fine(String msg, Throwable ex);
    /**
     * Writes a message to this writer.
     * The message level is "fine".
     */
    public void fine(String msg);
    /**
     * Writes an exception to this writer.
     * The exception level is "fine".
     */
    public void fine(Throwable ex);
    /**
     * Returns true if "finer" log messages are enabled.
     * Returns false if "finer" log messages are disabled.
     */
    public boolean finerEnabled();
    /**
     * Writes both a message and exception to this writer.
     * The message level is "finer".
     */
    public void finer(String msg, Throwable ex);
    /**
     * Writes a message to this writer.
     * The message level is "finer".
     */
    public void finer(String msg);
    /**
     * Writes an exception to this writer.
     * The exception level is "finer".
     */
    public void finer(Throwable ex);
    /**
     * Log a method entry.
     * 
The logging is done using the finer level.
     * The string message will start with "ENTRY" and
     * include the class and method names.
     * @param sourceClass Name of class that issued the logging request.
     * @param sourceMethod Name of the method that issued the logging request.
     */
    public void entering(String sourceClass, String sourceMethod);
    /**
     * Log a method return.
     * 
The logging is done using the finer level.
     * The string message will start with "RETURN" and
     * include the class and method names.
     * @param sourceClass Name of class that issued the logging request.
     * @param sourceMethod Name of the method that issued the logging request.
     */
    public void exiting(String sourceClass, String sourceMethod);
    /**
     * Log throwing an exception.
     * 
 Use to log that a method is
     * terminating by throwing an exception. The logging is done using
     * the finer level.
     *  This is a convenience method that could be done
     * instead by calling {@link #finer(String, Throwable)}.
     * The string message will start with "THROW" and
     * include the class and method names.
     * @param sourceClass Name of class that issued the logging request.
     * @param sourceMethod Name of the method that issued the logging request.
     * @param thrown The Throwable that is being thrown.
     */
    public void throwing(String sourceClass, String sourceMethod,
			 Throwable thrown);
    /**
     * Returns true if "finest" log messages are enabled.
     * Returns false if "finest" log messages are disabled.
     */
    public boolean finestEnabled();
    /**
     * Writes both a message and exception to this writer.
     * The message level is "finest".
     */
    public void finest(String msg, Throwable ex);
    /**
     * Writes a message to this writer.
     * The message level is "finest".
     */
    public void finest(String msg);
    /**
     * Writes an exception to this writer.
     * The exception level is "finest".
     */
    public void finest(Throwable ex);

    /**
     * Returns a 1.4 logging handler that can be used to direct application
     * output to this GemFire logger using the standard JDK logger APIs.
     * Each time this method is called it creates a new instance of a
     * Handler so care should be taken to not call this method too often.
     */
    public Handler getHandler();
    
    /**
     * A mechanism for accessing the abstraction layer used for 
     * internationalization.
     * @return LogWriterI18n
     */
    public LogWriterI18n convertToLogWriterI18n();
}