1 files changed, 24 insertions, 15 deletions

diff --git a/bundles/org.eclipse.equinox.log.stream/osgi/src/org/osgi/service/log/stream/LogStreamProvider.java b/bundles/org.eclipse.equinox.log.stream/osgi/src/org/osgi/service/log/stream/LogStreamProvider.java
index 99f5645c9..f48266bc6 100644
--- a/bundles/org.eclipse.equinox.log.stream/osgi/src/org/osgi/service/log/stream/LogStreamProvider.java
+++ b/bundles/org.eclipse.equinox.log.stream/osgi/src/org/osgi/service/log/stream/LogStreamProvider.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2016). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2016, 2017). All Rights Reserved.
  * 
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,10 +19,11 @@ package org.osgi.service.log.stream;
 import org.osgi.annotation.versioning.ProviderType;
 import org.osgi.service.log.LogEntry;
 import org.osgi.util.pushstream.PushStream;
+import org.osgi.util.pushstream.QueuePolicyOption;
 
 /**
- * LogStreamProvider service for creating a PushStream of {@link LogEntry}
- * objects.
+ * LogStreamProvider service for creating a {@link PushStream} of
+ * {@link LogEntry} objects.
  * 
  * @ThreadSafe
  * @author $Id$
@@ -30,34 +31,42 @@ import org.osgi.util.pushstream.PushStream;
 @ProviderType
 public interface LogStreamProvider {
 	/**
-	 * Creation options for the PushStream of {@link LogEntry} objects.
+	 * Creation options for the {@link PushStream} of {@link LogEntry} objects.
 	 */
 	enum Options {
 		/**
 		 * Include history.
 		 * <p>
-		 * Prime the created PushStream with the past {@link LogEntry} objects.
-		 * The number of past {@link LogEntry} objects is implementation
-		 * specific.
+		 * Prime the created PushStream with the available historical
+		 * {@link LogEntry} objects. The number of available {@link LogEntry}
+		 * objects is implementation specific.
 		 * <p>
-		 * The created PushStream will supply the past {@link LogEntry} objects
-		 * followed by newly created {@link LogEntry} objects.
+		 * The created PushStream will supply the available historical
+		 * {@link LogEntry} objects followed by newly created {@link LogEntry}
+		 * objects.
 		 */
 		HISTORY;
 	}
 
 	/**
-	 * Create a PushStream of {@link LogEntry} objects.
+	 * Create a {@link PushStream} of {@link LogEntry} objects.
 	 * <p>
-	 * The returned PushStream is an unbuffered stream with a parallelism of
-	 * one.
+	 * The returned PushStream must:
+	 * <ul>
+	 * <li>Be buffered with a buffer large enough to contain the history, if
+	 * included.</li>
+	 * <li>Have the {@link QueuePolicyOption#DISCARD_OLDEST} queue policy
+	 * option.</li>
+	 * <li>Use a shared executor.</li>
+	 * <li>Have a parallelism of one.</li>
+	 * </ul>
 	 * <p>
 	 * When this LogStreamProvider service is released by the obtaining bundle,
-	 * this LogStreamProvider service must call {@code close()} on the returned
-	 * PushStream object if it has not already been closed.
+	 * this LogStreamProvider service must call {@link PushStream#close()} on
+	 * the returned PushStream object if it has not already been closed.
 	 * 
 	 * @param options The options to use when creating the PushStream.
-	 * @return A PushStream of {@link LogEntry} objects.
+	 * @return A {@link PushStream} of {@link LogEntry} objects.
 	 */
 	PushStream<LogEntry> createStream(Options... options);
 }