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. * *
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. + *
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,7 +78,10 @@ * (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 {}; /** @@ -75,7 +89,11 @@ * 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 {}; } diff --git a/api/src/main/java/jakarta/persistence/NamedEntityGraphAttributeNode.java b/api/src/main/java/jakarta/persistence/NamedEntityGraphAttributeNode.java new file mode 100644 index 00000000..cf5af1db --- /dev/null +++ b/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 ""; +} + diff --git a/api/src/main/java/jakarta/persistence/NamedEntityGraphAttributeNodes.java b/api/src/main/java/jakarta/persistence/NamedEntityGraphAttributeNodes.java new file mode 100644 index 00000000..783e52c4 --- /dev/null +++ b/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(); +} diff --git a/api/src/main/java/jakarta/persistence/NamedEntityGraphSubgraph.java b/api/src/main/java/jakarta/persistence/NamedEntityGraphSubgraph.java new file mode 100644 index 00000000..a0548446 --- /dev/null +++ b/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}. + *
The target subgraph must be explicitly declared via a
+ * {@link NamedEntityGraph} annotation of the target entity
+ * of the annotated association.
+ */
+ String subgraph() default "";
+}
+
diff --git a/api/src/main/java/jakarta/persistence/NamedEntityGraphSubgraphs.java b/api/src/main/java/jakarta/persistence/NamedEntityGraphSubgraphs.java
new file mode 100644
index 00000000..d2f008bf
--- /dev/null
+++ b/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();
+}
diff --git a/api/src/main/java/jakarta/persistence/NamedSubgraph.java b/api/src/main/java/jakarta/persistence/NamedSubgraph.java
index a2648f64..c7aed796 100644
--- a/api/src/main/java/jakarta/persistence/NamedSubgraph.java
+++ b/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 {
/**
diff --git a/spec/src/main/asciidoc/ch03-entity-operations.adoc b/spec/src/main/asciidoc/ch03-entity-operations.adoc
index 830e397b..cb2556af 100644
--- a/spec/src/main/asciidoc/ch03-entity-operations.adoc
+++ b/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