8297686: JFR: Improve documentation of EventStream::onMetadata(Consumer)

Reviewed-by: mgronlun

src/jdk.jfr/share/classes/jdk/jfr/consumer/EventStream.java

@@ -192,6 +192,15 @@ public interface EventStream extends AutoCloseable {
      *
      * The event type of an event always arrives sometime before the actual event.
      * The action must be registered before the stream is started.
+     * <p>
+     * The following example shows how to listen to new event types, register
+     * an action if the event type name matches a regular expression and increase a
+     * counter if a matching event is found. A benefit of using an action per
+     * event type, instead of the generic {@link #onEvent(Consumer)} method,
+     * is that a stream implementation can avoid reading events that are of no
+     * interest.
+     *
+     * {@snippet class = "Snippets" region = "EventStreamMetadata"}
      *
      * @implSpec The default implementation of this method is empty.
      *
@@ -199,15 +208,24 @@ public interface EventStream extends AutoCloseable {
      *
      * @throws IllegalStateException if an action is added after the stream has
      *                               started
+     * @since 16
      */
      default void onMetadata(Consumer<MetadataEvent> action) {
      }
 
     /**
      * Registers an action to perform on all events in the stream.
+     * <p>
+     * To perform an action on a subset of event types, consider using
+     * {@link #onEvent(String, Consumer)} and {@link #onMetadata(Consumer)} as it is
+     * likely more performant than any selection or filtering mechanism implemented
+     * in a generic action.
      *
      * @param action an action to perform on each {@code RecordedEvent}, not
      *        {@code null}
+     *
+     * @see #onEvent(Consumer)
+     * @see #onMetadata(Consumer)
      */
     void onEvent(Consumer<RecordedEvent> action);
 

src/jdk.jfr/share/classes/jdk/jfr/consumer/snippet-files/Snippets.java

@@ -28,6 +28,7 @@ import java.io.IOException;
 import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.time.Duration;
+import java.util.regex.Pattern;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.stream.Collectors;
 import jdk.jfr.consumer.EventStream;
@@ -36,11 +37,12 @@ import jdk.jfr.consumer.RecordedClass;
 import jdk.jfr.consumer.RecordedThread;
 import jdk.jfr.consumer.RecordingStream;
 import jdk.jfr.Configuration;
+import jdk.jfr.EventType;
 import jdk.jfr.consumer.RecordedEvent;
 
 public class Snippets {
 
-    class PackageOveriview {
+    class PackageOverview {
         // @start region="PackageOverview"
         public static void main(String[] args) throws IOException {
             if (args.length != 1) {
@@ -88,6 +90,25 @@ public class Snippets {
         // @end
     }
 
+    class EventStreamMetadata {
+        // @start region="EventStreamMetadata"
+        static long count = 0;
+        public static void main(String... args) throws IOException {
+            Path file = Path.of(args[0]);
+            String regExp = args[1];
+            var pr = Pattern.compile(regExp).asMatchPredicate();
+            try (var s = EventStream.openFile(file)) {
+                s.setOrdered(false);
+                s.onMetadata(metadata -> metadata.getAddedEventTypes()
+                 .stream().map(EventType::getName).filter(pr)
+                 .forEach(eventName -> s.onEvent(eventName, event -> count++)));
+                s.start();
+                System.out.println(count + " events matches " + regExp);
+            }
+        }
+        // @end
+    }
+
     void RecordingFileOverview() throws Exception {
         // @start region="RecordingFileOverview"
         try (RecordingFile recordingFile = new RecordingFile(Paths.get("recording.jfr"))) {