+ * A stream is a sequence of events and the way to interact with a stream is to + * register actions. + *
+ * To receive a notification when an event arrives, register an action using the + * {@link #onEvent(Consumer)} method. To filter the stream for an event with a + * specific name, use {@link #onEvent(String, Consumer)} method. + * + * By default, the same {@code RecordedEvent} object can be used for + * representing two or more distinct events. The object can be delivered + * multiple times to the same action as well as to other actions. If the life + * cycle of the event object is needed outside the scope of an action, the + * {@link #setReuse(boolean)} method should be set to {@code false} so that a + * new object is allocated for each event. + * + *
+ * Events are delivered in batches. To receive a notification when a batch is + * complete, register an action using the {@link #onFlush(Runnable)} method. + * This is an opportunity to aggregate or push data to external systems while + * the Java Virtual Machine (JVM) is preparing the next batch. + *
+ * Events within a batch are sorted chronologically by their end time. If + * ordering is not a concern, sorting can be disabled using the + * {@link #setOrdered(boolean)} method. + *
+ * To dispatch events to registered actions, the stream must be started. To + * start processing in the current thread, invoke the {@link #start()} method. + * To process actions asynchronously in a separate thread, invoke the + * {@link #startAsync()} method. To await completion of the stream, use the + * awaitTermination {@link #awaitTermination()} or the {link + * {@link #awaitTermination(Duration)} method. + *
+ * When a stream ends it is automatically closed. To manually stop processing of + * events, close the stream with the {@link #close()} method. A stream can also + * be automatically closed in exceptional circumstances, for instance if the JVM + * exits. To receive a notification in any of these occasions, use the + * {@link #onClose(Runnable)} method to register an action. + *
+ * If an unexpected exception occurs in an action, it is possible to catch the + * exception in an error handler. An error handler can be registered using the + * {@link #onError(Runnable)} method. If no error handler is registered, the + * default behavior is to print the exception and its backtrace to the standard + * error stream. + *
+ * The following example demonstrates how an {@code EventStream} can be used to + * listen to garbage collection and CPU Load events + *
+ * */ public interface EventStream extends AutoCloseable { /** - * Creates a stream from the disk repository of the current Java Virtual - * Machine (JVM). + * Creates a stream from the repository of the current Java Virtual Machine + * (JVM). *
* By default, the stream starts with the next event flushed by Flight
* Recorder.
@@ -96,7 +144,7 @@
*
* @return an event stream, not {@code null}
*
- * @throws IOException if a stream can't be opened, or an I/O error occurs
+ * @throws IOException if the file can't be opened, or an I/O error occurs
* during reading
*
* @throws SecurityException if a security manager exists and its
@@ -107,71 +155,75 @@
}
/**
- * Performs an action on all events in the stream.
+ * Registers an action to perform on all events in the stream.
*
- * @param action an action to be performed on each {@code RecordedEvent},
- * not {@code null}
+ * @param action an action to perform on each {@code RecordedEvent}, not
+ * {@code null}
*/
void onEvent(Consumer
- * if an error handler has not been added to the stream, an exception stack
- * trace is printed to standard error.
+ * if an action is not registered, an exception stack trace is printed to
+ * standard error.
*
- * Adding an error handler overrides the default behavior. If multiple error
- * handlers have been added, they will be executed in the order they were
- * added.
+ * Registering an action overrides the default behavior. If multiple actions
+ * have been registered, they are performed in the order of registration.
+ *
+ * If this method itself throws an exception, resulting behavior is
+ * undefined.
*
- * @param action an action to be performed if an exception occurs, not
+ * @param action an action to perform if an exception occurs, not
* {@code null}
*/
void onError(Consumer
- * If the stream is already closed, the action will be executed immediately
+ * If the stream is already closed, the action will be performed immediately
* in the current thread.
*
- * @param action an action to be performed after the stream has been closed,
- * not {@code null}
+ * @param action an action to perform after the stream is closed, not
+ * {@code null}
+ * @see #close()
*/
void onClose(Runnable action);
/**
- * Releases all resources associated with this event stream.
+ * Releases all resources associated with this stream.
*/
void close();
/**
- * Removes an action from the stream.
+ * Unregisters an action.
*
- * If the action has been added multiple times, all instance of it will be
- * removed.
+ * If the action has been registered multiple times, all instances are
+ * unregistered.
*
- * @param action the action to remove, not {@code null}
+ * @param action the action to unregister, not {@code null}
*
- * @return {@code true} if the action was removed, {@code false} otherwise
+ * @return {@code true} if the action was unregistered, {@code false}
+ * otherwise
*
* @see #onEvent(Consumer)
* @see #onEvent(String, Consumer)
@@ -183,91 +235,98 @@
/**
* Specifies that the event object in an {@link #onEvent(Consumer)} action
- * is to be reused.
+ * can be reused.
*
- * If reuse is set to {@code true), a callback should not keep a reference
- * to the event object after the callback from {@code onEvent} has returned.
+ * If reuse is set to {@code true), an action should not keep a reference
+ * to the event object after the action has completed.
*
- * @param resuse if event objects can be reused between calls to
- * {@code #onEvent(Consumer)}
- *
+ * @param reuse {@code true} if an event object can be reused, {@code false}
+ * otherwise
*/
- public void setReuse(boolean reuse);
+ void setReuse(boolean reuse);
/**
* Specifies that events arrives in chronological order, sorted by the time
- * they were committed to the event stream.
+ * they were committed to the stream.
*
* @param ordered if event objects arrive in chronological order to
* {@code #onEvent(Consumer)}
*/
- public void setOrdered(boolean ordered);
+ void setOrdered(boolean ordered);
/**
- * Specifies start time of the event stream.
+ * Specifies the start time of the stream.
*
- * The start time must be set before the stream is started.
+ * The start time must be set before starting the stream
*
* @param startTime the start time, not {@code null}
*
- * @throws IllegalStateException if the stream has already been started
+ * @throws IllegalStateException if the stream is already started
+ *
+ * @see #start()
+ * @see #startAsync()
*/
- public void setStartTime(Instant startTime);
+ void setStartTime(Instant startTime);
/**
- * Specifies end time of the event stream.
+ * Specifies the end time of the stream.
*
- * The end time must be set before the stream is started.
+ * The end time must be set before starting the stream.
*
- * When the end time is reached the stream is closed.
+ * At end time, the stream is closed.
*
* @param endTime the end time, not {@code null}
*
- * @throws IllegalStateException if the stream has already been started
+ * @throws IllegalStateException if the stream is already started
+ *
+ * @see #start()
+ * @see #startAsync()
*/
- public void setEndTime(Instant endTime);
+ void setEndTime(Instant endTime);
/**
- * Start processing events in the stream.
+ * Start processing of actions.
*
- * All actions performed on this stream will happen in the current thread.
+ * Actions are performed in the current thread.
*
- * @throws IllegalStateException if the stream is already started or if it
- * has been closed
+ * @throws IllegalStateException if the stream is already started or closed
*/
void start();
/**
- * Start processing events in the stream asynchronously.
+ * Start asynchronous processing of actions.
*
- * All actions on this stream will be performed in a separate thread.
+ * Actions are performed in a single separate thread.
*
- * @throws IllegalStateException if the stream is already started, or if it
- * has been closed
+ * @throws IllegalStateException if the stream is already started or closed
*/
void startAsync();
/**
- * Blocks the current thread until the stream is finished, closed, or it
- * times out.
+ * Blocks until all actions are completed, or the stream is closed, or the
+ * timeout occurs, or the current thread is interrupted, whichever happens
+ * first.
*
* @param timeout the maximum time to wait, not {@code null}
*
* @throws IllegalArgumentException if timeout is negative
- * @throws InterruptedException
+ * @throws InterruptedException if interrupted while waiting
*
* @see #start()
* @see #startAsync()
+ * @see Thread#interrupt()
*/
void awaitTermination(Duration timeout) throws InterruptedException;
/**
- * Blocks the current thread until the stream is finished or closed.
+ * Blocks until all actions are completed, or the stream is closed, or the
+ * current thread is interrupted, whichever happens first.
*
- * @throws InterruptedException
+ * @throws InterruptedException if interrupted while waiting
*
* @see #start()
* @see #startAsync()
+ * @see Thread#interrupt()
*/
void awaitTermination() throws InterruptedException;
}
\ No newline at end of file