new annotations for constructing named entity graphs

finally addresses issue jakartaee#118

Signed-off-by: Gavin King <[email protected]>

api/src/main/java/jakarta/persistence/NamedAttributeNode.java

@@ -18,7 +18,6 @@
 
 import java.lang.annotation.Target;
 import java.lang.annotation.Retention;
-import java.util.Map;
 
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
@@ -30,9 +29,12 @@
  * @see NamedSubgraph
  *
  * @since 2.1
+ *
+ * @deprecated Use {@link NamedEntityGraphAttributeNode}
  */
 @Target({})
 @Retention(RUNTIME)
+@Deprecated(since = "4.0")
 public @interface NamedAttributeNode {
 
     /**

api/src/main/java/jakarta/persistence/NamedEntityGraph.java

@@ -23,14 +23,18 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Defines a named {@linkplain EntityGraph entity graph}. This annotation
- * must be applied to the root entity of the graph, and specifies the
- * limits of the graph of associated attributes and entities fetched when
- * an operation which retrieves an instance or instances of the root entity
- * is executed.
+ * Declares a named {@linkplain EntityGraph entity graph} or subgraph
+ * of a named entity graph. This annotation must be applied to the root
+ * entity of the graph.
+ *
+ * <p>The annotations {@link NamedEntityGraphAttributeNode} and
+ * {@link NamedEntityGraphSubgraph} control the limits of the graph of
+ * associated attributes and entities fetched when an operation which
+ * retrieves an instance or instances of the root entity is executed.
  *
  * <p> A reference to a named entity graph may be obtained by calling
- * {@link EntityManager#getEntityGraph(String)}, and may be passed to
+ * {@link EntityManagerFactory#getNamedEntityGraphs(Class)} or
+ * {@link EntityManager#getEntityGraph(String)} and may be passed to
  * {@link EntityManager#find(EntityGraph, Object, FindOption...)}.
  *
  * @since 2.1
@@ -44,14 +48,21 @@
      * (Optional) The name used to identify the entity graph in calls to
      * {@link EntityManager#getEntityGraph(String)}. If no name is explicitly
      * specified, the name defaults to the entity name of the annotated root
-     * entity. Entity graph names must be unique within the persistence unit.
+     * entity.
+     * <p>Entity graph names must be unique within a given persistence unit.
+     * If two {@link NamedEntityGraph @NamedEntityGraph} annotations declare
+     * the same name, then one must be a subgraph of the other, as specified
+     * via the {@link NamedEntityGraphSubgraph} annotations.
      */
     String name() default "";
 
     /**
      * (Optional) A list of attributes of the entity that are included in
      * this graph.
+     *
+     * @deprecated Use {@link NamedEntityGraphAttributeNode}
      */
+    @Deprecated(since = "4.0")
     NamedAttributeNode[] attributeNodes() default {};
 
     /**
@@ -67,15 +78,22 @@
      * (Optional) A list of subgraphs that are included in the
      * entity graph. These are referenced by name from NamedAttributeNode
      * definitions.
+     *
+     * @deprecated Use {@link NamedEntityGraphSubgraph}
      */
+    @Deprecated(since = "4.0")
     NamedSubgraph[] subgraphs() default {};
 
     /**
      * (Optional) A list of subgraphs that will add additional
      * attributes for subclasses of the annotated entity class to the
      * entity graph.  Specified attributes from superclasses are
      * included in subclasses.
+     *
+     * @deprecated Since {@code EntityGraph.addSubclassSubgraph}
+     *             was removed
      */
+    @Deprecated(since = "4.0", forRemoval = true)
     NamedSubgraph[] subclassSubgraphs() default {};
 }
 

api/src/main/java/jakarta/persistence/NamedEntityGraphAttributeNode.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) 2011, 2023 Oracle and/or its affiliates. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0,
+ * or the Eclipse Distribution License v. 1.0 which is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
+ */
+
+// Contributors:
+//     Gavin King - 4.0
+
+package jakarta.persistence;
+
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * Declares that the annotated attribute is an attribute node
+ * in a {@linkplain NamedEntityGraph named entity graph}. The
+ * {@link #graph} member must specify the name of the graph.
+ *
+ * @see EntityGraph#addAttributeNode
+ * 
+ * @since 4.0
+ */
+@Repeatable(NamedEntityGraphAttributeNodes.class)
+@Target({FIELD, METHOD})
+@Retention(RUNTIME)
+public @interface NamedEntityGraphAttributeNode {
+    /**
+     * The name of the containing entity graph, as specified by
+     * {@link NamedEntityGraph#name}. If no name is explicitly
+     * specified, the name defaults to the entity name of the
+     * annotated root entity.
+     */
+    String graph() default "";
+}
+

api/src/main/java/jakarta/persistence/NamedEntityGraphAttributeNodes.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2011, 2023 Oracle and/or its affiliates. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0,
+ * or the Eclipse Distribution License v. 1.0 which is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
+ */
+
+// Contributors:
+//     Gavin King - 4.0
+
+
+package jakarta.persistence;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * Used to group {@link NamedEntityGraphAttributeNode} annotations.
+ *
+ * @see NamedEntityGraphAttributeNode
+ * @since 4.0
+ */
+@Target({FIELD, METHOD})
+@Retention(RUNTIME)
+public @interface NamedEntityGraphAttributeNodes {
+    NamedEntityGraphAttributeNode[] value();
+}

api/src/main/java/jakarta/persistence/NamedEntityGraphSubgraph.java

@@ -0,0 +1,67 @@
+/*
+ * Copyright (c) 2011, 2023 Oracle and/or its affiliates. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0,
+ * or the Eclipse Distribution License v. 1.0 which is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
+ */
+
+// Contributors:
+//     Gavin King - 4.0
+
+package jakarta.persistence;
+
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * Declares that the annotated association is the root of a
+ * subgraph of a {@linkplain NamedEntityGraph named entity
+ * graph}.
+ * <ul>
+ * <li>The {@link #graph} member must specify the name of
+ *      the containing graph.
+ * <li>The {@link #subgraph} member specifies the name of
+ *     a named entity graph whose root is the associated
+ *     entity.
+ * </ul>
+ *
+ * @see EntityGraph#addSubgraph
+ * @see EntityGraph#addElementSubgraph
+ * 
+ * @since 4.0
+ */
+@Repeatable(NamedEntityGraphSubgraphs.class)
+@Target({FIELD, METHOD})
+@Retention(RUNTIME)
+public @interface NamedEntityGraphSubgraph {
+    /**
+     * The name of the containing entity graph, as specified by
+     * {@link NamedEntityGraph#name}. If no name is explicitly
+     * specified, the name defaults to the entity name of the
+     * annotated root entity.
+     */
+    String graph() default "";
+
+    /**
+     * The name of an entity graph whose root is the associated
+     * entity, as specified by {@link NamedEntityGraph#name}.
+     * If no subgraph name is explicitly specified, the subgraph
+     * name defaults to the {@linkplain #graph name of the
+     * containing graph}.
+     * <p>The target subgraph must be explicitly declared via a
+     * {@link NamedEntityGraph} annotation of the target entity
+     * of the annotated association.
+     */
+    String subgraph() default "";
+}
+

api/src/main/java/jakarta/persistence/NamedEntityGraphSubgraphs.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2011, 2023 Oracle and/or its affiliates. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0,
+ * or the Eclipse Distribution License v. 1.0 which is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
+ */
+
+// Contributors:
+//     Gavin King - 4.0
+
+
+package jakarta.persistence;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * Used to group {@link NamedEntityGraphSubgraph} annotations.
+ *
+ * @see NamedEntityGraphSubgraph
+ * @since 4.0
+ */
+@Target({FIELD, METHOD})
+@Retention(RUNTIME)
+public @interface NamedEntityGraphSubgraphs {
+    NamedEntityGraphSubgraph[] value();
+}

api/src/main/java/jakarta/persistence/NamedSubgraph.java

@@ -30,9 +30,12 @@
  * @see NamedAttributeNode
  *
  * @since 2.1
+ *
+ * @deprecated Use {@link NamedEntityGraphSubgraph}
  */
 @Target({})
 @Retention(RUNTIME)
+@Deprecated(since = "4.0")
 public @interface NamedSubgraph {
 
     /**

spec/src/main/asciidoc/ch03-entity-operations.adoc

@@ -1987,9 +1987,7 @@ In the above example, only the `number` attribute would be eagerly fetched.
 
 [source,java]
 ----
-@NamedEntityGraph(
-    attributeNodes={@NamedAttributeNode("projects")}
-)
+@NamedEntityGraph
 @Entity
 public class Employee {
     @Id
@@ -2002,13 +2000,14 @@ public class Employee {
     @Basic
     protected String employeeNumber;
 
-    @OneToMany()
+    @OneToMany
     protected List<Dependents> dependents;
 
-    @OneToMany()
+    @OneToMany
+    @NamedEntityGraphAttributeNode
     protected List<Project> projects;
 
-    @OneToMany()
+    @OneToMany
     protected List<PhoneNumber> phoneNumbers;
 
     // ...
@@ -2135,9 +2134,7 @@ In the above example, the `number` and `type` attributes are fetched.
 
 [source,java]
 ----
-@NamedEntityGraph(
-    attributeNodes={@NamedAttributeNode("projects")}
-)
+@NamedEntityGraph
 @Entity
 public class Employee {
     @Id
@@ -2150,13 +2147,14 @@ public class Employee {
     @Basic
     protected String employeeNumber;
 
-    @OneToMany()
+    @OneToMany
     protected List<Dependents> dependents;
 
-    @OneToMany()
+    @OneToMany
     protected List<Project> projects;
 
-    @OneToMany()
+    @OneToMany
+    @NamedEntityGraphAttributeNode
     protected List<PhoneNumber> phoneNumbers;
 
     // ...