⋮
Prev     Next

158 Log Stream Provider Service Specification

158.1 Introduction

The Log Stream Provider service can be used to create Push Streams of Log Entries. Since the log is basically an ongoing stream of Log Entries having asynchronous arrival, a Push Stream of LogEntry objects can be used receive the Log Entries. See Push Stream Specification for information on Push Streams and how to use them.

Figure 158.1 Log Stream Diagram org.osgi.service.log.stream package

Log Stream Diagram org.osgi.service.log.stream package

This specification defines the methods and semantics of interfaces which bundle developers can use to retrieve log entries.

Bundles can use the Log Stream Provider to retrieve Log Entry objects that were recorded recently or to receive Log Entry objects as they are logged by other bundles.

158.1.1 Entities

  • LogEntry - An interface that allows access to a log entry in the log. It includes all the information that can be logged through the Logger as well as a time stamp, a sequence number, thread information, and location information. See [1] Log Service for more information about LogEntry.

  • LogStreamProvider - A service interface that allows access to a PushStream of LogEntry objects.

158.2 Log Stream Provider

Push Streams created by the LogStreamProvider must:

  • Be buffered with a buffer large enough to contain the history, if included.

  • Have the QueuePolicyOption.DISCARD_OLDEST queue policy option.

  • Use a shared executor.

  • Have a parallelism of one.

The following code snippet show how one could get future Log Entries and print them. 

logStreamProvider.createStream()
  .forEach(l -> System.out.println(l))
  .onResolve(() -> System.out.println("stream closed"));

The LogStreamProvider service offers a HISTORY option which will prime the returned Push Stream with the available log history, if any. The following code will process the available historical log entries followed by any new log entries. 

logStreamProvider.createStream(LogStreamProvider.Options.HISTORY)
  .forEach(l -> System.out.println(l))
  .onResolve(() -> System.out.println("stream closed"));

158.3 Capabilities

The bundle providing the LogStreamProvider service must provide a capability in the osgi.service namespace representing this service. This capability must also declare a uses constraint for the org.osgi.service.log.stream package: 

Provide-Capability: osgi.service;
 objectClass:List<String>="org.osgi.service.log.stream.LogStreamProvider";
 uses:="org.osgi.service.log.stream"

This capability must follow the rules defined for the osgi.service Namespace.

158.4 Security

The Log Stream Provide Service specification should only be implemented by trusted bundles. These bundles require ServicePermission[LogStreamProvider, REGISTER].

Only trusted bundles who must be able to access log entries should be assigned ServicePermission[LogStreamProvider, GET].

158.5 org.osgi.service.log.stream

Version 1.0

Log Stream Package Version 1.0.

Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest. This package has two types of users: the consumers that use the API in this package and the providers that implement the API in this package.

Example import for consumers using the API in this package:

Import-Package: org.osgi.service.log.stream; version="[1.0,2.0)"

Example import for providers implementing the API in this package:

Import-Package: org.osgi.service.log.stream; version="[1.0,1.1)"

158.5.1 Summary

158.5.2 public interface LogStreamProvider

LogStreamProvider service for creating a PushStream of LogEntry objects.

Thread-safe

Consumers of this API must not implement this type

158.5.2.1 public PushStream<LogEntry> createStream(LogStreamProvider.Options... options)

The options to use when creating the PushStream.

Create a PushStream of LogEntry objects.

The returned PushStream must:

  • Be buffered with a buffer large enough to contain the history, if included.

  • Have the QueuePolicyOption.DISCARD_OLDEST queue policy option.

  • Use a shared executor.

  • Have a parallelism of one.

When this LogStreamProvider service is released by the obtaining bundle, this LogStreamProvider service must call PushStream.close() on the returned PushStream object if it has not already been closed.

A PushStream of LogEntry objects.

158.5.3 enum LogStreamProvider.Options

Creation options for the PushStream of LogEntry objects.

158.5.3.1 HISTORY

Include history.

Prime the created PushStream with the available historical LogEntry objects. The number of available LogEntry objects is implementation specific.

The created PushStream will supply the available historical LogEntry objects followed by newly created LogEntry objects.

158.5.3.2 public static LogStreamProvider.Options valueOf(String name)

158.5.3.3 public static LogStreamProvider.Options[] values()

158.6 References

[1]Log ServiceOSGi Core, Chapter 101 Log Service Specification

Prev     Next
  Home