com.varra.log.Log Maven / Gradle / Ivy
Show all versions of utils4j Show documentation
/*
* utils4j - Log.java, Aug 16, 2015 3:52:46 PM
*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You 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.varra.log;
import org.apache.log4j.Level;
import com.varra.classification.InterfaceAudience;
import com.varra.classification.InterfaceStability;
import com.varra.util.Shutdownable;
/**
* A convenient way of implementing the Logger functionality. Very useful to
* integrate with the third party Logger implementations.
* Just implement this with the preferred logging framework whatever you choose.
*
* Note: Actual implementations need to take
* care of Log Level enabled/disabled check before processing to log the
* messages, if you are not using the third party framework.
*
* @author Rajakrishna V. Reddy
* @version 3.0
* @see Logger
*/
@InterfaceAudience.Public
@InterfaceStability.Evolving
public interface Log extends Shutdownable
{
/**
* Gets the name of the logger.
*
* @return the name
*/
String getName();
/**
* Sets the name.
*
* @param name
* the name
*/
void setName(String name);
/**
* Log a message object with the {@link Level#TRACE TRACE} level.
*
* @param message
* the message
*/
void trace(Object message);
/**
* Log a message object with the {@link Level#TRACE TRACE} level including
* the stack trace of the {@link Throwable}t passed as
* parameter.
*
*
* See {@link #debug(Object)} form for more detailed information.
*
*
* @param message
* the message
* @param t
* the t
*/
void trace(Object message, Throwable t);
/**
* Log a message object with the {@link Level#INFO INFO} Level.
*
* @param message
* the message
*/
void info(Object message);
/**
* Log a message object with the {@link Level#INFO INFO} level including the
* stack trace of the {@link Throwable} t passed as parameter.
*
*
* See {@link #info(Object)} for more detailed information.
*
* @param message
* the message
* @param t
* the t
*/
void info(Object message, Throwable t);
/**
* Log a message object with the {@link Level#DEBUG DEBUG} level.
*
* @param message
* the message
*/
void debug(Object message);
/**
* Log a message object with the {@link Level#DEBUG DEBUG} level including
* the stack trace of the {@link Throwable} t passed as
* parameter.
*
* @param message
* the message
* @param t
* the t
*
* @see com.varra.log.Log#debug
*/
void debug(Object message, Throwable t);
/**
* Log a message object with the {@link Level#WARN WARN} Level.
*
* @param message
* the message
*/
void warn(Object message);
/**
* Log a message with the WARN level including the stack trace
* of the {@link Throwable} t passed as parameter.
*
* @param message
* the message
* @param t
* the t
* @see com.varra.log.Log#warn for more detailed information.
*/
void warn(Object message, Throwable t);
/**
* Log a message object with the {@link Level#ERROR ERROR} Level..
*
* @param message
* the message
*/
void error(Object message);
/**
* Log a message object with the ERROR level including the
* stack trace of the {@link Throwable} t passed as parameter.
*
* @param message
* the message
* @param t
* the t
* @see com.varra.log.Log#error form for more detailed information.
*/
void error(Object message, Throwable t);
/**
* Log a message object with the {@link Level#FATAL FATAL} Level.
*
* @param message
* the message
*/
void fatal(Object message);
/**
* Log a message object with the {@link Level#FATAL FATAL} level including
* the stack trace of the {@link Throwable} t passed as
* parameter.
*
* @param message
* the message
* @param t
* the t
* @see com.varra.log.Log#fatal for more detailed information.
*/
void fatal(Object message, Throwable t);
/**
* Log a message object with the test Level.
*
* Note: Is useful for testing purpose, if the code is moved to
* production just you can disable this level instead of removing the log
* entries in classes spread across in your Application.
* There will be a situation where {@link Level#DEBUG DEBUG} and
* {@link Level#INFO INFO} are not adequate.
*
* @param message
* the message
*/
void test(Object message);
/**
* Log a message object with the test level including the
* stack trace of the {@link Throwable} t passed as parameter.
*
* @param message
* the message
* @param t
* the t
* @see com.varra.log.Log#test for more detailed information.
*/
void test(Object message, Throwable t);
/**
* Log a message object with the {@link Level#level MyLevel} (an user
* defined) Level.
*
* Note: Is very useful for the developers to use for specific purpose,
* like for displaying the time elapsed for an event or for showing the
* statistics or for showing the progress of a task..etc
*
* @param message
* the message
* @param level
* the level
* @param levelString
* the level string
*/
void log(Object message, int level, String levelString);
/**
* Log a message object with the {@link Level#level MyLevel} (an user
* defined) Level
* including the stack trace of the {@link Throwable} t passed
* as parameter.
*
* @param message
* the message
* @param t
* the t
* @see com.varra.log.Log#log for more detailed information.
*/
void log(Object message, Throwable t);
/**
* Check whether this category is enabled for the DEBUG Level.
*
*
* This function is intended to lessen the computational cost of disabled
* log debug statements.
*
*
* For some cat Category object, when you write,
*
*
* logger.debug("This is entry number: " + i);
*
*
*
* You incur the cost constructing the message, concatenatiion in this case,
* regardless of whether the message is logged or not.
*
*
* If you are worried about speed, then you should write
*
*
* if (logger.isDebugEnabled())
* {
* logger.debug("This is entry number: " + i);
* }
*
*
*
* This way you will not incur the cost of parameter construction if
* debugging is disabled for cat. On the other hand, if the
* cat is debug enabled, you will incur the cost of evaluating
* whether the category is debug enabled twice. Once in
* isDebugEnabled and once in the debug. This is
* an insignificant overhead since evaluating a category takes about 1%% of
* the time it takes to actually log.
*
* @return boolean - true if this category is debug enabled,
* false otherwise.
*/
public boolean isDebugEnabled();
/**
* Check whether this category is enabled for the info Level. See also
* {@link #isDebugEnabled}.
*
* @return boolean - true if this category is enabled for level
* info, false otherwise.
*/
public boolean isInfoEnabled();
/**
* Set the level of this Category. If you are passing any of
* MyLogLevel.DEBUG, MyLogLevel.INFO,
* MyLogLevel.WARN, MyLogLevel.ERROR,
* MyLogLevel.FATAL as a parameter, you need to case them as
* MyLogLevel.
*
* As in
*
*
* logger.setLevel((MyLogLevel) MyLogLevel.DEBUG);
*
*
* Null values are not entertained.
*
* @param level
* the new level
*/
public void setLevel(MyLogLevel level);
/**
* Returns the assigned {@link MyLogLevel}, if any, for this Category.
*
* @return MyLogLevel - the assigned Level, can be null.
*
* the level
*/
public MyLogLevel getLevel();
}