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.
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.
-
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
LogEntryobjects.
Push Streams created by the LogStreamProvider must:
-
Be buffered with a buffer large enough to contain the history, if included.
-
Have the
QueuePolicyOption.DISCARD_OLDESTqueue 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"));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.
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].
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)"
-
LogStreamProvider- LogStreamProvider service for creating a PushStream of LogEntry objects. -
LogStreamProvider.Options- Creation options for the PushStream of LogEntry objects.
LogStreamProvider service for creating a PushStream of LogEntry objects.
Thread-safe
Consumers of this API must not implement this type
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.
Creation options for the PushStream of LogEntry objects.
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.