Knopflerfish OSGi 3.0.0

org.knopflerfish.service.log
Class LogRef

java.lang.Object
  extended by org.knopflerfish.service.log.LogRef
All Implemented Interfaces:
java.util.EventListener, ServiceListener, LogService

public class LogRef
extends java.lang.Object
implements ServiceListener, LogService

LogRef is an utility class that simplifies the use of the LogService.

LogRef let you use the log without worrying about getting new service objects when the log service is restarted. It also supplies methods with short names that does logging with all the different LogService severity types.

To use the LogRef you need to import org.knopflerfish.service.log.LogRef and instantiate LogRef with your bundle context as parameter. The bundle context is used for getting the LogService and adding a service listener.

Example usage

The if statement that protects each call to the LogRef instance below is there to save the effort required for creating the message string object in cases where the log will throw away the log entry due to its unimportance. The user must have this if-test in his code since that is the only way to avoid constructing the string object. Placing it in the wrapper (LogRef) will not help due to the design of the Java programming language.
 package org.knopflerfish.example.hello;

 import
 org.osgi.framework.*;
 import org.knopflerfish.service.log.LogRef;


 public class Hello implements BundleActivator {
   LogRef log;

   public void start(BundleContext bundleContext) {
     log = new LogRef(bundleContext);
     if (log.doInfo()) log.info("Hello started.");
   }

   public void stop(BundleContext bundleContext) {
     if (log.doDebug()) log.debug("Hello stopped.");
   }
 }
 

Author:
Gatespace AB
See Also:
LogService, LogService

Field Summary
 
Fields inherited from interface org.osgi.service.log.LogService
LOG_DEBUG, LOG_ERROR, LOG_INFO, LOG_WARNING
 
Constructor Summary
LogRef(BundleContext bc)
          Create new LogRef object for a given bundle.
LogRef(BundleContext bc, boolean out)
          Create new LogRef object for a given bundle.
 
Method Summary
 void close()
          Close this LogRef object.
 void debug(java.lang.String msg)
          Log a debug level message
 void debug(java.lang.String msg, ServiceReference sr)
          Log a debug level message.
 void debug(java.lang.String msg, ServiceReference sr, java.lang.Throwable e)
          Log a debug level message.
 void debug(java.lang.String msg, java.lang.Throwable e)
          Log a debug level message.
 boolean doDebug()
          Returns true if messages with severity debug or higher are saved by the log.
 boolean doError()
          Returns true if messages with severity error or higher are saved by the log.
 boolean doInfo()
          Returns true if messages with severity info or higher are saved by the log.
protected  void doLog(java.lang.String msg, int level, ServiceReference sr, java.lang.Throwable e)
          Sends a message to the log if possible.
 boolean doWarn()
          Returns true if messages with severity warning or higher are saved by the log.
 void error(java.lang.String msg)
          Log an error level message.
 void error(java.lang.String msg, ServiceReference sr)
          Log an error level message.
 void error(java.lang.String msg, ServiceReference sr, java.lang.Throwable e)
          Log an error level message.
 void error(java.lang.String msg, java.lang.Throwable e)
          Log an error level message.
 int getLogLevel()
          Returns the current log level.
 void info(java.lang.String msg)
          Log an info level message.
 void info(java.lang.String msg, ServiceReference sr)
          Log an info level message.
 void info(java.lang.String msg, ServiceReference sr, java.lang.Throwable e)
          Log an info level message.
 void info(java.lang.String msg, java.lang.Throwable e)
          Log an info level message.
 void log(int level, java.lang.String message)
          Log a message.
 void log(int level, java.lang.String message, java.lang.Throwable exception)
          Log a message with an exception.
 void log(ServiceReference sr, int level, java.lang.String message)
          Log a message associated with a specific Service.
 void log(ServiceReference sr, int level, java.lang.String message, java.lang.Throwable exception)
          Log a message with an exception associated with a specific Service.
 void serviceChanged(ServiceEvent evt)
          Service listener entry point.
 void warn(java.lang.String msg)
          Log a warning level message.
 void warn(java.lang.String msg, ServiceReference sr)
          Log a warning level message.
 void warn(java.lang.String msg, ServiceReference sr, java.lang.Throwable e)
          Log a warning level message.
 void warn(java.lang.String msg, java.lang.Throwable e)
          Log a warning level message.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

LogRef

public LogRef(BundleContext bc,
              boolean out)
Create new LogRef object for a given bundle.

Parameters:
bc - the bundle context of the bundle that this log ref instance belongs too.
out - If true print messages on System.out when there is no log service.

LogRef

public LogRef(BundleContext bc)
Create new LogRef object for a given bundle.

If the system property org.knopflerfish.log.out equals "true", system.out will be used as fallback if no log service is found.

Parameters:
bc - the bundle context of the bundle that this log ref instance belongs too.
Method Detail

serviceChanged

public void serviceChanged(ServiceEvent evt)
Service listener entry point. Releases the log service object if one has been fetched.

Specified by:
serviceChanged in interface ServiceListener
Parameters:
evt - Service event

close

public void close()
Close this LogRef object. Ungets the log service if active.


doLog

protected void doLog(java.lang.String msg,
                     int level,
                     ServiceReference sr,
                     java.lang.Throwable e)
Sends a message to the log if possible.

Parameters:
msg - Human readable string describing the condition.
level - The severity of the message (Should be one of the four predefined severities).
sr - The ServiceReference of the service that this message is associated with.
e - The exception that reflects the condition.

getLogLevel

public int getLogLevel()
Returns the current log level. There is no use to generate log entries with a severity level less than this value since such entries will be thrown away by the log.

Returns:
the current severity log level for this bundle.

doDebug

public boolean doDebug()
Returns true if messages with severity debug or higher are saved by the log.

Returns:
true if messages with severity LOG_DEBUG or higher are included in the log, otherwise false.

doWarn

public boolean doWarn()
Returns true if messages with severity warning or higher are saved by the log.

Returns:
true if messages with severity LOG_WARNING or higher are included in the log, otherwise false.

doInfo

public boolean doInfo()
Returns true if messages with severity info or higher are saved by the log.

Returns:
true if messages with severity LOG_INFO or higher are included in the log, otherwise false.

doError

public boolean doError()
Returns true if messages with severity error or higher are saved by the log.

Returns:
true if messages with severity LOG_ERROR or higher are included in the log, otherwise false.

debug

public void debug(java.lang.String msg)
Log a debug level message

Parameters:
msg - Log message.

debug

public void debug(java.lang.String msg,
                  ServiceReference sr)
Log a debug level message.

Parameters:
msg - Log message
sr - The ServiceReference of the service that this message is associated with.

debug

public void debug(java.lang.String msg,
                  java.lang.Throwable e)
Log a debug level message.

Parameters:
msg - Log message
e - The exception that reflects the condition.

debug

public void debug(java.lang.String msg,
                  ServiceReference sr,
                  java.lang.Throwable e)
Log a debug level message.

Parameters:
msg - Log message
sr - The ServiceReference of the service that this message is associated with.
e - The exception that reflects the condition.

info

public void info(java.lang.String msg)
Log an info level message.

Parameters:
msg - Log message

info

public void info(java.lang.String msg,
                 ServiceReference sr)
Log an info level message.

Parameters:
msg - Log message
sr - The ServiceReference of the service that this message is associated with.

info

public void info(java.lang.String msg,
                 java.lang.Throwable e)
Log an info level message.

Parameters:
msg - Log message
e - The exception that reflects the condition.

info

public void info(java.lang.String msg,
                 ServiceReference sr,
                 java.lang.Throwable e)
Log an info level message.

Parameters:
msg - Log message
sr - The ServiceReference of the service that this message is associated with.
e - The exception that reflects the condition.

warn

public void warn(java.lang.String msg)
Log a warning level message.

Parameters:
msg - Log message

warn

public void warn(java.lang.String msg,
                 ServiceReference sr)
Log a warning level message.

Parameters:
msg - Log message
sr - The ServiceReference of the service that this message is associated with.

warn

public void warn(java.lang.String msg,
                 java.lang.Throwable e)
Log a warning level message.

Parameters:
msg - Log message
e - The exception that reflects the condition.

warn

public void warn(java.lang.String msg,
                 ServiceReference sr,
                 java.lang.Throwable e)
Log a warning level message.

Parameters:
msg - Log message
sr - The ServiceReference of the service that this message is associated with.
e - The exception that reflects the condition.

error

public void error(java.lang.String msg)
Log an error level message.

Parameters:
msg - Log message

error

public void error(java.lang.String msg,
                  ServiceReference sr)
Log an error level message.

Parameters:
msg - Log message
sr - The ServiceReference of the service that this message is associated with.

error

public void error(java.lang.String msg,
                  java.lang.Throwable e)
Log an error level message.

Parameters:
msg - Log message
e - The exception that reflects the condition.

error

public void error(java.lang.String msg,
                  ServiceReference sr,
                  java.lang.Throwable e)
Log an error level message.

Parameters:
msg - Log message
sr - The ServiceReference of the service that this message is associated with.
e - The exception that reflects the condition.

log

public void log(int level,
                java.lang.String message)
Log a message. The ServiceDescription field and the Throwable field of the LogEntry will be set to null.

Specified by:
log in interface LogService
Parameters:
level - The severity of the message. (Should be one of the four predefined severities.)
message - Human readable string describing the condition.
See Also:
LogService.LOG_ERROR, LogService.LOG_WARNING, LogService.LOG_INFO, LogService.LOG_DEBUG

log

public void log(int level,
                java.lang.String message,
                java.lang.Throwable exception)
Log a message with an exception. The ServiceDescription field of the LogEntry will be set to null.

Specified by:
log in interface LogService
Parameters:
level - The severity of the message. (Should be one of the four predefined severities.)
message - Human readable string describing the condition.
exception - The exception that reflects the condition.
See Also:
LogService.LOG_ERROR, LogService.LOG_WARNING, LogService.LOG_INFO, LogService.LOG_DEBUG

log

public void log(ServiceReference sr,
                int level,
                java.lang.String message)
Log a message associated with a specific Service. The Throwable field of the LogEntry will be set to null.

Specified by:
log in interface LogService
Parameters:
sr - The ServiceReference of the service that this message is associated with.
level - The severity of the message. (Should be one of the four predefined severities.)
message - Human readable string describing the condition.
See Also:
LogService.LOG_ERROR, LogService.LOG_WARNING, LogService.LOG_INFO, LogService.LOG_DEBUG

log

public void log(ServiceReference sr,
                int level,
                java.lang.String message,
                java.lang.Throwable exception)
Log a message with an exception associated with a specific Service.

Specified by:
log in interface LogService
Parameters:
sr - The ServiceReference of the service that this message is associated with.
level - The severity of the message. (Should be one of the four predefined severities.)
message - Human readable string describing the condition.
exception - The exception that reflects the condition.
See Also:
LogService.LOG_ERROR, LogService.LOG_WARNING, LogService.LOG_INFO, LogService.LOG_DEBUG

Knopflerfish OSGi 3.0.0