8265356: need code example for getting canonical constructor of a Record

Reviewed-by: smarks

Author: amaembo

src/java.base/share/classes/java/lang/Class.java

@@ -1631,7 +1631,7 @@ public Class<?> getEnclosingClass() throws SecurityException {
      * in source code, can have a non-empty name including special
      * characters, such as "{@code $}".
      *
-     * <p>The simple name of an {@linkplain isArray() array class} is the simple name of the
+     * <p>The simple name of an {@linkplain #isArray() array class} is the simple name of the
      * component type with "[]" appended.  In particular the simple
      * name of an array class whose component type is anonymous is "[]".
      *
@@ -2361,6 +2361,19 @@ public Field[] getDeclaredFields() throws SecurityException {
      * Conversely, if {@link #isRecord()} returns {@code true}, then this method
      * returns a non-null value.
      *
+     * @apiNote
+     * <p> The following method can be used to find the record canonical constructor:
+     *
+     * <pre>{@code
+     * static <T extends Record> Constructor<T> getCanonicalConstructor(Class<T> cls)
+     *     throws NoSuchMethodException {
+     *   Class<?>[] paramTypes =
+     *     Arrays.stream(cls.getRecordComponents())
+     *           .map(RecordComponent::getType)
+     *           .toArray(Class<?>[]::new);
+     *   return cls.getDeclaredConstructor(paramTypes);
+     * }}</pre>
+     *
      * @return  An array of {@code RecordComponent} objects representing all the
      *          record components of this record class, or {@code null} if this
      *          class is not a record class
@@ -3113,15 +3126,15 @@ static <T> boolean casReflectionData(Class<?> clazz,
             return unsafe.compareAndSetReference(clazz, reflectionDataOffset, oldData, newData);
         }
 
-        static <T> boolean casAnnotationType(Class<?> clazz,
-                                             AnnotationType oldType,
-                                             AnnotationType newType) {
+        static boolean casAnnotationType(Class<?> clazz,
+                                         AnnotationType oldType,
+                                         AnnotationType newType) {
             return unsafe.compareAndSetReference(clazz, annotationTypeOffset, oldType, newType);
         }
 
-        static <T> boolean casAnnotationData(Class<?> clazz,
-                                             AnnotationData oldData,
-                                             AnnotationData newData) {
+        static boolean casAnnotationData(Class<?> clazz,
+                                         AnnotationData oldData,
+                                         AnnotationData newData) {
             return unsafe.compareAndSetReference(clazz, annotationDataOffset, oldData, newData);
         }
     }

src/java.base/share/classes/java/lang/Record.java

@@ -79,6 +79,10 @@
  * <cite>Java Object Serialization Specification,</cite> Section 1.13,
  * "Serialization of Records"</a>.
  *
+ * @apiNote
+ * A record class structure can be obtained at runtime via reflection.
+ * See {@link Class#isRecord()} and {@link Class#getRecordComponents()} for more details.
+ *
  * @jls 8.10 Record Types
  * @since 16
  */