diff --git a/src/jdk.jfr/share/classes/jdk/jfr/BooleanFlag.java b/src/jdk.jfr/share/classes/jdk/jfr/BooleanFlag.java index 6fc92ceab34..10aedc19bb6 100644 --- a/src/jdk.jfr/share/classes/jdk/jfr/BooleanFlag.java +++ b/src/jdk.jfr/share/classes/jdk/jfr/BooleanFlag.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2016, 2020, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2016, 2023, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -31,8 +31,14 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Event field annotation, specifies that the value is a boolean flag, a {@code true} or - * {@code false} value. + * Event field annotation, specifies that the value is a boolean flag, a + * {@code true} or {@code false} value. + *
+ * The following example shows how the {@code BooleanFlag} annotation can be + * used to describe that a setting is a boolean value. This information can be + * used by a graphical user interface to display the setting as a checkbox. + * + * {@snippet class = "Snippets" region = "BooleanFlagOverview"} * * @since 9 */ diff --git a/src/jdk.jfr/share/classes/jdk/jfr/Configuration.java b/src/jdk.jfr/share/classes/jdk/jfr/Configuration.java index 5afd5e1a7da..8be9d2ee23d 100644 --- a/src/jdk.jfr/share/classes/jdk/jfr/Configuration.java +++ b/src/jdk.jfr/share/classes/jdk/jfr/Configuration.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2016, 2023, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -40,6 +40,11 @@ import jdk.jfr.internal.jfc.JFC; /** * A collection of settings and metadata describing the configuration. + *
+ * The following example shows how the {@code Configuration} class can be used + * to list available configurations and how to pass a configuration object to a + * {@code Recording}. + * {@snippet class = "Snippets" region = "ConfigurationxsOverview"} * * @since 9 */ diff --git a/src/jdk.jfr/share/classes/jdk/jfr/DataAmount.java b/src/jdk.jfr/share/classes/jdk/jfr/DataAmount.java index 5f2650a9e64..c2442ad2c92 100644 --- a/src/jdk.jfr/share/classes/jdk/jfr/DataAmount.java +++ b/src/jdk.jfr/share/classes/jdk/jfr/DataAmount.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2016, 2023, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -32,6 +32,11 @@ import java.lang.annotation.Target; /** * Event field annotation, specifies that a value represents an amount of data (for example, bytes). + *
+ * The following example shows how the {@code DataAmount} annotation can be used to + * set the units {@code BITS} and {@code BYTES} to event fields. + * + * {@snippet class="Snippets" region="DataAmountOverview"} * * @since 9 */ diff --git a/src/jdk.jfr/share/classes/jdk/jfr/Enabled.java b/src/jdk.jfr/share/classes/jdk/jfr/Enabled.java index d8e697e871e..328826356a1 100644 --- a/src/jdk.jfr/share/classes/jdk/jfr/Enabled.java +++ b/src/jdk.jfr/share/classes/jdk/jfr/Enabled.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2016, 2023, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -34,7 +34,19 @@ import java.lang.annotation.Target; /** * Event annotation, determines if an event should be enabled by default. *
- * If an event doesn't have the annotation, then by default the event is enabled. + * If an event doesn't have the annotation, then by default the event is + * enabled. + *
+ * The following example shows how the {@code Enabled} annotation can be used to + * create a disabled event. A disabled event will at most have the overhead of + * an allocation, or none if the runtime JIT compiler is able to eliminate it. + * + * {@snippet class = "Snippets" region = "EnabledOverview"} + * + * The event can be enabled programmatically, or on command line when needed, + * for example: + * + * {@snippet class = "Snippets" region = "EnabledOverviewCommandLine"} * * @since 9 */ diff --git a/src/jdk.jfr/share/classes/jdk/jfr/EventType.java b/src/jdk.jfr/share/classes/jdk/jfr/EventType.java index 8ced73b2ab9..c8ea51a50dc 100644 --- a/src/jdk.jfr/share/classes/jdk/jfr/EventType.java +++ b/src/jdk.jfr/share/classes/jdk/jfr/EventType.java @@ -40,6 +40,11 @@ import jdk.jfr.internal.Utils; /** * Describes an event, its fields, settings and annotations. + *
+ * The following example shows how the {@code EventType} class can + * be used to print metadata about an event. + * + * {@snippet class="Snippets" region="EventTypeOverview"} * * @since 9 */ diff --git a/src/jdk.jfr/share/classes/jdk/jfr/Period.java b/src/jdk.jfr/share/classes/jdk/jfr/Period.java index fba49b8d6f4..90c4a9699d8 100644 --- a/src/jdk.jfr/share/classes/jdk/jfr/Period.java +++ b/src/jdk.jfr/share/classes/jdk/jfr/Period.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2016, 2020, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2016, 2023, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -33,6 +33,11 @@ import java.lang.annotation.Target; /** * Event annotation, specifies the default setting value for a periodic event. + *
+ * The following example shows how the {@code Period} annotation can be used + * to emit events at different intervals. + * + * {@snippet class = "Snippets" region = "PeriodOverview"} * * @since 9 */ diff --git a/src/jdk.jfr/share/classes/jdk/jfr/ValueDescriptor.java b/src/jdk.jfr/share/classes/jdk/jfr/ValueDescriptor.java index 75ed52371ec..1cd01d22398 100644 --- a/src/jdk.jfr/share/classes/jdk/jfr/ValueDescriptor.java +++ b/src/jdk.jfr/share/classes/jdk/jfr/ValueDescriptor.java @@ -36,6 +36,11 @@ import jdk.jfr.internal.Utils; /** * Describes the event fields and annotation elements. + *
+ * The following example shows how the {@code ValueDescriptor} class can
+ * be used to list field information of all types.
+ *
+ * {@snippet class="Snippets" region="ValueDescriptorOverview"}
*
* @since 9
*/
diff --git a/src/jdk.jfr/share/classes/jdk/jfr/snippet-files/Snippets.java b/src/jdk.jfr/share/classes/jdk/jfr/snippet-files/Snippets.java
index 4d4a5a0516d..53db6f76094 100644
--- a/src/jdk.jfr/share/classes/jdk/jfr/snippet-files/Snippets.java
+++ b/src/jdk.jfr/share/classes/jdk/jfr/snippet-files/Snippets.java
@@ -25,12 +25,16 @@
package jdk.jfr.snippets;
import jdk.jfr.AnnotationElement;
+import jdk.jfr.BooleanFlag;
import jdk.jfr.ValueDescriptor;
import jdk.jfr.EventFactory;
+import jdk.jfr.EventType;
import jdk.jfr.Event;
import jdk.jfr.Name;
import jdk.jfr.Label;
+import jdk.jfr.DataAmount;
import jdk.jfr.Description;
+import jdk.jfr.Enabled;
import jdk.jfr.Category;
import jdk.jfr.ContentType;
import jdk.jfr.Period;
@@ -39,6 +43,7 @@ import jdk.jfr.StackTrace;
import jdk.jfr.MetadataDefinition;
import jdk.jfr.Relational;
import jdk.jfr.consumer.RecordingFile;
+import jdk.jfr.consumer.RecordingStream;
import jdk.jfr.Configuration;
import jdk.jfr.SettingDefinition;
import jdk.jfr.SettingControl;
@@ -53,10 +58,13 @@ import java.nio.file.Paths;
import java.time.Duration;
import java.util.ArrayList;
import java.util.Collections;
+import java.util.LinkedHashMap;
import java.util.List;
+import java.util.Map;
import java.util.Set;
+import java.util.StringJoiner;
+import java.util.concurrent.atomic.AtomicInteger;
import java.util.regex.Pattern;
-import java.util.stream.Collectors;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@@ -83,6 +91,77 @@ public class Snippets {
// @end
}
+ // @start region="BooleanFlagOverview"
+ @BooleanFlag
+ @Name("example.Rollback")
+ @Label("Rollback")
+ @Description("Include transactions that are rollbacked")
+ public static class RollbackSetting extends SettingControl {
+ private boolean value = true;
+
+ @Override
+ public String combine(Set