41 import jdk.jfr.internal.consumer.FileAccess; |
41 import jdk.jfr.internal.consumer.FileAccess; |
42 |
42 |
43 /** |
43 /** |
44 * Represents a stream of events. |
44 * Represents a stream of events. |
45 * <p> |
45 * <p> |
46 * The EventStream interface is not to be implemented and future version may |
|
47 * prevent this completely. |
|
48 * <p> |
|
49 * A stream is a sequence of events and the way to interact with a stream is to |
46 * A stream is a sequence of events and the way to interact with a stream is to |
50 * register actions. |
47 * register actions. The {@code EventStream} interface is not to be implemented |
|
48 * and future versions of the JDK may prevent this completely. |
51 * <p> |
49 * <p> |
52 * To receive a notification when an event arrives, register an action using the |
50 * To receive a notification when an event arrives, register an action using the |
53 * {@link #onEvent(Consumer)} method. To filter the stream for an event with a |
51 * {@link #onEvent(Consumer)} method. To filter the stream for an event with a |
54 * specific name, use {@link #onEvent(String, Consumer)} method. |
52 * specific name, use {@link #onEvent(String, Consumer)} method. |
55 * |
53 * <p> |
56 * By default, the same {@code RecordedEvent} object can be used for |
54 * By default, the same {@code RecordedEvent} object can be used for |
57 * representing two or more distinct events. The object can be delivered |
55 * representing two or more distinct events. The object can be delivered |
58 * multiple times to the same action as well as to other actions. If the life |
56 * multiple times to the same action as well as to other actions. If the life |
59 * cycle of the event object is needed outside the scope of an action, the |
57 * cycle of the event object exceeds the scope of an action, the |
60 * {@link #setReuse(boolean)} method should be set to {@code false} so that a |
58 * {@link #setReuse(boolean)} method should be set to {@code false} so that a |
61 * new object is allocated for each event. |
59 * new object is allocated for each event. |
62 * |
|
63 * <p> |
60 * <p> |
64 * Events are delivered in batches. To receive a notification when a batch is |
61 * Events are delivered in batches. To receive a notification when a batch is |
65 * complete, register an action using the {@link #onFlush(Runnable)} method. |
62 * complete, register an action using the {@link #onFlush(Runnable)} method. |
66 * This is an opportunity to aggregate or push data to external systems while |
63 * This is an opportunity to aggregate or push data to external systems while |
67 * the Java Virtual Machine (JVM) is preparing the next batch. |
64 * the Java Virtual Machine (JVM) is preparing the next batch. |
76 * {@link #startAsync()} method. To await completion of the stream, use the |
73 * {@link #startAsync()} method. To await completion of the stream, use the |
77 * awaitTermination {@link #awaitTermination()} or the {link |
74 * awaitTermination {@link #awaitTermination()} or the {link |
78 * {@link #awaitTermination(Duration)} method. |
75 * {@link #awaitTermination(Duration)} method. |
79 * <p> |
76 * <p> |
80 * When a stream ends it is automatically closed. To manually stop processing of |
77 * When a stream ends it is automatically closed. To manually stop processing of |
81 * events, close the stream with the {@link #close()} method. A stream can also |
78 * events, close the stream by invoking the {@link #close()} method. A stream |
82 * be automatically closed in exceptional circumstances, for instance if the JVM |
79 * can also be automatically closed in exceptional circumstances, for example |
83 * exits. To receive a notification in any of these occasions, use the |
80 * if the JVM that is being monitored exits. To receive a notification in any of |
84 * {@link #onClose(Runnable)} method to register an action. |
81 * these occasions, use the {@link #onClose(Runnable)} method to register an |
|
82 * action. |
85 * <p> |
83 * <p> |
86 * If an unexpected exception occurs in an action, it is possible to catch the |
84 * If an unexpected exception occurs in an action, it is possible to catch the |
87 * exception in an error handler. An error handler can be registered using the |
85 * exception in an error handler. An error handler can be registered using the |
88 * {@link #onError(Runnable)} method. If no error handler is registered, the |
86 * {@link #onError(Runnable)} method. If no error handler is registered, the |
89 * default behavior is to print the exception and its backtrace to the standard |
87 * default behavior is to print the exception and its backtrace to the standard |
90 * error stream. |
88 * error stream. |
91 * <p> |
89 * <p> |
92 * The following example shows how an {@code EventStream} can be used to |
90 * The following example shows how an {@code EventStream} can be used to listen |
93 * listen to events on a JVM running Flight Recorder |
91 * to events on a JVM running Flight Recorder |
|
92 * |
94 * <pre> |
93 * <pre> |
95 * <code> |
94 * <code> |
96 * try (EventStream es = EventStream.openRepository()) { |
95 * try (EventStream es = EventStream.openRepository()) { |
97 * es.onEvent("jdk.CPULoad", event -> { |
96 * es.onEvent("jdk.CPULoad", event -> { |
98 * System.out.println("CPU Load " + event.getEndTime()); |
97 * System.out.println("CPU Load " + event.getEndTime()); |