8281622: JFR: Improve documentation of jdk.jfr.Relational

Reviewed-by: jbachorik

src/jdk.jfr/share/classes/jdk/jfr/Relational.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2016, 2022, 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,13 @@ import java.lang.annotation.Target;
 
 /**
  * Meta annotation for relational annotations, to be used on an annotation.
+ * <p>
+ * The following example shows how a relational annotation can be created and
+ * used. The {@code Orderid} annotation indicates there is a relation between
+ * {@code OrderEvent} and {@code OrderLineEvent}. if they have the same ID,
+ * the order line belongs to the order.
+ *
+ * {@snippet class="Snippets" region="RelationalOverview"}
  *
  * @since 9
  */

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

@@ -42,6 +42,7 @@ import jdk.jfr.consumer.RecordingFile;
 import jdk.jfr.Configuration;
 import jdk.jfr.SettingDefinition;
 import jdk.jfr.SettingControl;
+import jdk.jfr.Timestamp;
 import jdk.jfr.FlightRecorder;
 import jdk.jfr.consumer.RecordedEvent;
 
@@ -260,6 +261,45 @@ public class Snippets {
     }
     // @end
 
+    // @start region="RelationalOverview"
+    @MetadataDefinition
+    @Relational
+    @Name("com.example.OrderId")
+    @Label("Order ID")
+    @Retention(RetentionPolicy.RUNTIME)
+    @Target(ElementType.FIELD)
+    public @interface OrderId {
+    }
+
+    @Name("com.example.Order")
+    @Label("Order")
+    @Category("Orders")
+    class OrderEvent extends Event {
+        @Label("Order ID")
+        @OrderId
+        long orderId;
+
+        @Label("Order Date")
+        @Timestamp
+        long orderDate;
+    }
+
+    @Name("com.example.OrderLine")
+    @Label("Order Line")
+    @Category("Orders")
+    class OrderLineEvent extends Event {
+        @Label("Order ID")
+        @OrderId
+        long orderId;
+
+        @Label("Quantity")
+        long quantity;
+
+        @Label("Product")
+        String product;
+    }
+    // @end
+
  void RecordingnOverview() throws Exception {
      // @start region="RecordingOverview"
      Configuration c = Configuration.getConfiguration("default");