org.jboss.webbeans.log
Interface Log


public interface Log

A Log object is used by RI classes to log messages. They will be logged in any environment that has setup a logging service such as Log4J or the standard JDK logging facilities. In fact, this logging interface is very similar to the other facilities with the difference that logging methods also take any number of optional parameters beyond the message object for later interpolation into the message.

The idea of using interpolation parameters is very important for performance reasons in production code. Normally developers write logging messages similar to this one:

    log.debug("Started processing of " + obj1 + " with action " + obj2);
 
The problem that arises at runtime in production systems, is that DEBUG level logging may not be enabled. And even if this logging is going to be a no-op call, Java must still build the string dynamically that is the argument to the call. It is the building of this string that can be quite time consuming. The more complex the objects being concatenated are, the worse the time penalty incurred is. And this time is completely wasted since the string may never be used.

Normally to combat the problem of making this call and building the string dynamically, the developer uses a conditional statement to invoke the call only if the corresponding logging level is enabled. So the above call may end up looking like:

    if (log.isDebugEnabled())
    {
       log.debug("Started processing of " + obj1 + " with action " + obj2);
    }
 
Ideally, this structure should always be used to avoid the cost of building the dynamic string (concatenation) and making the unnecessary call. The only drawback to this is that code can become less readable. In some cases, there might be more code devoted to logging than the actual behavior required by a method.

A cleaner way to do the logging is to use this interface where simple objects without any concatenation are passed as arguments. Albeit the call itself may still be a no-op when the logging level is not enabled, this is still much smaller than the concatenation process with dynamic strings. Each of the methods defined here will first check to see if the logging level is enabled, if that feature exists in the underlying logging system. If and only if that logging level is enabled, will the implementation proceed with concatenation of the strings and objects passed. So the above code using this interface becomes:

    log.debug("Started processing of {0} with action {1}, obj1, obj2);
 

The interpolation of parameters into the message string are done using MessageFormat. See the documentation on that class for more ideas of interpolation possibilities. In the above code, obj1 and obj2 simply have their toString() methods invoked to produce a string which is then concatenated.

Author:
Gavin King, David Allen

Method Summary
 void debug(java.lang.Object object, java.lang.Object... params)
           
 void debug(java.lang.Object object, java.lang.Throwable t, java.lang.Object... params)
           
 void error(java.lang.Object object, java.lang.Object... params)
           
 void error(java.lang.Object object, java.lang.Throwable t, java.lang.Object... params)
           
 void fatal(java.lang.Object object, java.lang.Object... params)
           
 void fatal(java.lang.Object object, java.lang.Throwable t, java.lang.Object... params)
           
 void info(java.lang.Object object, java.lang.Object... params)
           
 void info(java.lang.Object object, java.lang.Throwable t, java.lang.Object... params)
           
 boolean isDebugEnabled()
           
 boolean isErrorEnabled()
           
 boolean isFatalEnabled()
           
 boolean isInfoEnabled()
           
 boolean isTraceEnabled()
           
 boolean isWarnEnabled()
           
 void trace(java.lang.Object object, java.lang.Object... params)
           
 void trace(java.lang.Object object, java.lang.Throwable t, java.lang.Object... params)
           
 void warn(java.lang.Object object, java.lang.Object... params)
           
 void warn(java.lang.Object object, java.lang.Throwable t, java.lang.Object... params)
           
 

Method Detail

isDebugEnabled

boolean isDebugEnabled()

isErrorEnabled

boolean isErrorEnabled()

isFatalEnabled

boolean isFatalEnabled()

isInfoEnabled

boolean isInfoEnabled()

isTraceEnabled

boolean isTraceEnabled()

isWarnEnabled

boolean isWarnEnabled()

trace

void trace(java.lang.Object object,
           java.lang.Object... params)

trace

void trace(java.lang.Object object,
           java.lang.Throwable t,
           java.lang.Object... params)

debug

void debug(java.lang.Object object,
           java.lang.Object... params)

debug

void debug(java.lang.Object object,
           java.lang.Throwable t,
           java.lang.Object... params)

info

void info(java.lang.Object object,
          java.lang.Object... params)

info

void info(java.lang.Object object,
          java.lang.Throwable t,
          java.lang.Object... params)

warn

void warn(java.lang.Object object,
          java.lang.Object... params)

warn

void warn(java.lang.Object object,
          java.lang.Throwable t,
          java.lang.Object... params)

error

void error(java.lang.Object object,
           java.lang.Object... params)

error

void error(java.lang.Object object,
           java.lang.Throwable t,
           java.lang.Object... params)

fatal

void fatal(java.lang.Object object,
           java.lang.Object... params)

fatal

void fatal(java.lang.Object object,
           java.lang.Throwable t,
           java.lang.Object... params)


Copyright © 2011. All Rights Reserved.