Package org.osgi.service.log

Description

The OSGi LogService Specification.

The LogService takes log requests from bundles and the LogReaderService allows other bundles to read entries from the log. Although you can ask the LogService to log any message, it is primarily intended for reporting events and error conditions.

In general, the LogService interface provides the means for:

• Specifying the message and/or exception to be logged.

• Supplying a log level signifying severity of the message being logged.

• Specifying the service associated with the log requests.

The LogReaderService interface provides the means for:

• Getting recent past log entries.

• Getting notified of new log entries.

LogService

Making Log Requests

Callers make log requests through LogService after they get the Service object from the OSGi Framework. In the following example, the caller writes a message into the log:

logService.log(myServiceReference, LogService.LOG_INFO,
    "myService is up and running");

myServiceReference identifies the originator of the log request. The provided level LogService.LOG_INFO indicates that this is informational.

Following is another example that records error conditions:

try {
    FileInputStream fis = new FileInputStream("myFile");
    int b;
    while ((b = fis.read()) != -1) {
       ...
    }
    fis.close();
} catch (IOException e) {
    logService.log(myServiceReference, LogService.LOG_ERROR,
        "Cannot access file", e);
}

Note that in addition to the error message, the exception itself is also logged.

Methods for Logging

The LogService provides for the logging of different types of messages:

• Log a simple message at the given log level.

• Log a message with an exception at the given log level.

Although it is possible to call log methods without providing a service description, it is recommended that the caller supplies this parameter whenever appropriate.

Log Level and Error Severity

The LogService expects a level indicating error severity. This can be used to filter log messages according to the level of severity. The LogService interface defines the various severity levels.

Callers must supply log levels that they deem appropriate when making log requests.

Event Listening

The LogService also serves as an event listener for the OSGi Framework. There is no dedicated error handling service in the Framework. Because events are broadcast in the Framework, other interested listeners can still have the opportunity to receive the events. The LogService will log all Framework events at the LogService.LOG_INFO level, except for FrameworkErrorEvents which will be logged at the LogService.LOG_ERROR level.

LogReaderService

In addition to producing log entries a bundle programmer might also be interested in receiving log entries either as they happen or entries that have already occurred.

In secure implementations of the Framework, a bundle wishing to use the LogReaderService must have the appropriate permission.

Retrieving past log entries

Log entries from the past are obtained via the getLog method. This method returns an enumeration of LogEntries. The LogEntries will be ordered with the most recent entry first. It should be noted that the size of the log is implementation specific. Also, how far into the past the log goes will depend upon the size of the log. Finally, not all log entries will be recorded in the past log. Debug log entries, in particular, may not be recorded.

Subscribing to the LogReaderService

A bundle that is interested in the log entries will probably want to process log messages as they happen. Unlike the past log, all logging messages will be sent to a subscriber of the LogReaderService. A subscriber to the LogReaderService must implement the LogListener interface. The subscriber then subscribes to the LogReaderService using the addLogListener method. After starting the subscription, each time a message is logged, the logged method of the subscriber's LogListener will be called with a LogEntry object for the message that was logged.