Hello Oliver,
A couple responses to your suggestions.
> As all this stuff is "Named", does it make sense to get rid of the prefix? There are attribute nodes only right now, so what about @EntityGraph, @SubGraph, and @Node? This would keep the graph/node semantics in the name. One might argue this leads to much to a graph datastore impression so @Attribute instead of @Node could be a choice as well. In general I think we can shorten the names a bit to reduce the noise an annotation based approach has to introduce.
The "Named" prefix was added as a solution to a package naming
issue. If the interfaces and the annotations have the same names what
packages will they be placed in?
> 2. Will there be an externalizable version (XML) of the annotation model?
Yes,
--Gordon
On 28/11/2012 6:59 AM, Oliver Gierke wrote:
> Hi all,
>
> thanks Gordon, Linda and Michael for this really extensive proposal. It looks really thought through. I've taken a look at it mostly from the usability point of as you'll probably get a lot of useful feedback on the implementation challenges from the vendor representatives.
>
> 1. I felt a bit overwhelmed seeing the annotation based declaration the first time. Assuming I have 2 or three of these plans defined on my entity, I'll probably end up with more annotations than actual Java code. Have you thought about adding a String[] property (let's say "attributes") to the Graph annotations that allow simply listing the attributes instead of wrapping them into a nested annotation:
>
> @NamedEntityGraph(
> attributeNodes = {
> @NamedAttributeNode("projects"),
> @NamedAttributeNode("phoneNumbers")
> }
> )
>
> could become:
>
> @NamedEntityGraph(attributes = { "projects", "phoneNumbers" })
>
> The more complex example you showed below would become.
>
> @NamedEntityGraph(
> subGraphs = {
> @NamedSubGraph(name = "projects", attributes = "requirements"),
> @NamedSubGraph(name = "projects", type = LargeProject.class, attributes = "approver")
> }
> )
>
> Essentially it's about being able to use a plain property name over the nested @NamedAttributeNode annotation in case you only need to define the property name anyway.
>
> A similar scenario applies to the actual API. Although you can already add nodes just by providing a name, I think we can significantly reduce the number of codes needed to be written by equipping methods like ….addAttributeNode(…) with varargs so that you don't have to repeat the call over and over again.
>
> As all this stuff is "Named", does it make sense to get rid of the prefix? There are attribute nodes only right now, so what about @EntityGraph, @SubGraph, and @Node? This would keep the graph/node semantics in the name. One might argue this leads to much to a graph datastore impression so @Attribute instead of @Node could be a choice as well. In general I think we can shorten the names a bit to reduce the noise an annotation based approach has to introduce.
>
> 2. Will there be an externalizable version (XML) of the annotation model?
> 3. Is there a chance we allow @NamedEntityGraph being used on a method declaration as well? This can be handy in case you have infrastructure that can apply the entity graph defined on a method to all queries executed by that method. The CDI query extension [0] or Spring Data JPA [1] expose a programming model like this to users.
>
> Thanks again for all the effort you put into this!
> Ollie
>
> [0] https://github.com/ctpconsulting/query
> [1] https://github.com/SpringSource/spring-data-jpa
>
> Am 27.11.2012 um 22:20 schrieb Gordon Yorke <gordon.yorke_at_oracle.com>:
>
>> Hello all,
>> Please find below a proposal for EntityGraphs and their use to define entity graph fetching, loading, merging and copying. I have been working with Mike Keith and Linda DeMichiel on this proposal and we feel it is time to present to the expert group. Please have a look and provide feedback as the intention is to integrate this within the 2.1 spec.
>> Thank you,
>> Gordon
>>
>> ----
>> A common functional request has been to enable users to dynamically define how an EntityManager operation or query should apply to an entity graph. This may more commonly be known as “merge groups” or “fetch plans”. This functionality can be especially important when detached entities must be serialized and then merged into an active Persistence Context.
>>
>> An entity graph is a template defined in the form of metadata or an object created by the dynamic EntityGraph API that captures the path and boundaries for an operation or a query For static metadata the NamedEntityGraph annotation defines the attribute nodes and boundaries of the grouping.
>>
>> @Target({TYPE})
>> @Retention(RUNTIME)
>> public @interface NamedEntityGraphs{
>> NamedEntityGraph[] value();
>> }
>>
>> @Target({TYPE})
>> @Retention(RUNTIME)
>> public @interface NamedEntityGraph{
>> /**
>> * (Optional) The name of the sub-graph.
>> * Defaults to the entity name of the root entity.
>> */
>> String name() default "";
>>
>> /**
>> * (Required) list of attributes that are included in in this sub-graph.
>> */
>> NamedAttributeNode[] attributeNodes();
>>
>> /**
>> * (Optional) Lists all of the attributes of this Entity class to be listed in
>> * the NamedEntityGraph without the need to explicitly list them. Included
>> * attributes can still be fully specified by an attribute node referencing a
>> * sub-graph.
>> */
>> boolean includeAllAttributes() default false;
>>
>> /**
>> * (Optional) This is a list of sub-graphs that are included in the
>> * entity graph. They are referenced by name from NamedAttributeNode
>> * definitions.
>> */
>>
>> NamedSubGraph[] subGraphs() default {};
>>
>> /**
>> * (Optional) This is a list of sub-graphs that will add additional attributes
>> * for subclasses of the entity represented by this NamedEntityGraph to this
>> * entity graph. Specified attributes from superclasses are included in
>> * subclasses.
>> */
>>
>> NamedSubGraph[] subclassSubGraphs() default {};
>> }
>>
>> The NamedEntityGraph annotation is applied to an Entity class that is defined as the root of a group of attributes, relationships and related entity classes. The NamedAttributeNode annotations are embedded within the NamedEntityGraph metadata and define the attributes of the entity that are included in the grouping. When a NamedAttributeNode represents an Entity or an Embedded (including a collection-valued relationship or an element collection of embeddables), the referenced type’s attributes can be included as a NamedSubGraph entry of the entity graph and referenced by name, creating a multi-level entity graph. If the sub-graph represents an entity with inheritance multiple NamedSubGraph entries can be made with the same name to extend the sub-graph for specific subclasses. The class type that is being extended is required in the NamedSubGraph.
>>
>> /**
>> * A NamedAttributeNode is a member attribute of a NamedEntityGraph.
>> *
>> * @see javax.persistence.NamedEntityGraph
>> * @see javax.persistence.NamedSubGraph
>>
>> */
>> @Target({})
>> @Retention(RUNTIME)
>> public @interface NamedAttributeNode {
>> /**
>> * (Required) the name of the attribute that must be in the sub-graph.
>> */
>> String value();
>>
>> /**
>> * (Optional) if this attribute references a managed type that has its own
>> * AttributeNodes then this refers to that NamedSubGraph definition. If the
>> * target type has inheritance than multiple sub graphs can be specified.
>> * These additional sub-graphs are intended to add additional attributes from
>> * subclasses. Superclass sub-graph entries will be merged into subclasses
>> * sub-graphs.
>> */
>> String subGraph() default “”;
>>
>> /**
>> * (Optional) if the attribute references a Map type this can be used to specify
>> * a subGraph for the Key in the case of an Entity key type. A
>> * keySubGraph can not be specified without the Map attribute also being
>> * specified. If the target type has inheritance than multiple sub-graphs can
>> * be specified. These additional sub-graphs are intended to add additional
>> * attributes from subclasses. Superclass sub-graph entries will be merged
>> * into subclasses sub-graphs.
>> */
>> String keySubGraph() default "";
>>
>> }
>>
>> /**
>> * A NamedSubGraph is a member of a NamedEntityGraph that represents a managed
>> * type. The NamedSubGraph is only referenced from within a NamedEntityGraph and
>> * can not be referenced on its own. It is referenced by name from a
>> * NamedAttributeNode of the NamedEntityGraph.
>> *
>> * @see javax.persistence.NamedEntityGraph
>> * @see javax.persistence.NamedAttributeNode
>> */
>> @Target({})
>> @Retention(RUNTIME)
>> public @interface NamedSubGraph {
>> /**
>> * (Required) the name of the sub-graph as referenced from a
>> * NamedAttributeNode.
>> */
>> String name();
>>
>> /**
>> * (Optional) the type represented by this subgraph. Required when this
>> * subgraph is extending a subclass’ definition.
>> */
>> Class type default void.class;
>>
>> /** (Required)
>> * if this NamedAttributeNode references a managed type then this list is
>> * the attributes of that type that must be included.
>> */
>> NamedAttributeNode[] attributeNodes();
>>
>> }
>>
>> For example:
>> @Entity
>> public class Employee{
>>
>> @Id
>> @GeneratedValue
>> protected long id;
>>
>> @Basic
>> protected String name;
>>
>> @Basic
>> protected String employeeNumber;
>>
>> @OneToMany()
>> protected List<Dependants> dependants;
>>
>> @OneToMany()
>> protected List<Project> projects;
>>
>> @OneToMany()
>> protected List<PhoneNumber> phoneNumbers;
>> ...
>> }
>>
>> @Entity
>> @Inheritance
>> public class Project{
>> @Id
>> @GeneratedValue
>> protected long id;
>>
>> @OneToOne(fetch=FetchType.EAGER)
>> protected Requirements doc;
>> ...
>> }
>>
>> @Entity
>> public class LargeProject extends Project{
>>
>> @OneToOne(fetch=FetchType.LAZY)
>> protected Employee approver;
>> ...
>> }
>>
>> @Entity
>> public class Phonenumber{
>> @Id
>> protected String number;
>>
>> protected PhoneTypeEnum type;
>> ...
>> }
>>
>> @Entity
>> public class Requirements{
>> @Id
>> protected long id;
>>
>> @Lob
>> protected String description;
>>
>> @OneToOne(fetch=FetchType.LAZY)
>> protected Approval approval
>> ...
>> }
>>
>> @NamedEntityGraph(
>> attributeNodes={
>> @NamedAttributeNode(
>> value="projects",
>> subGraph=”projects”
>> ),
>> @NamedttributeNode(name = "phoneNumbers"),
>> },
>> subGraphs={
>> @NamedSubGraph(
>> name=”projects”,
>> attributeNodes={
>> @NamedAttributeNode("requirements")
>> }
>> ),
>> @NamedSubGraph(
>> name=”projects”,
>> type=LargeProject.class,
>> attributeNodes={
>> @NamedAttributeNode("approver")
>> }
>> )
>> }
>> )
>>
>> @NamedEntityGraph(
>> name-”Project”,
>> attributeNodes={
>> @NamedAttributeNode("requirements")
>> },
>> subclassSubGraphs={
>> @NamedSubGraph(
>> type=LargeProject.class,
>> attributeNodes={
>> @NamedAttributeNode("approver")
>> }
>> )
>> }
>> )
>>
>> @NamedEntityGraph(
>> name="EmployeeProjectRequirements"
>> attributeNodes={
>> @NamedAttributeNode(
>> value="projects",
>> subGraph=”projects”
>> ),
>> @NamedttributeNode(name = "phoneNumbers"),
>> },
>> subGraphs={
>> @NamedSubGraph(
>> name=”projects”,
>> attributeNodes={
>> @NamedAttributeNode(
>> value ="requirements",
>> subGraph=”requirements”
>> )
>> }
>> ),
>> @NamedSubGraph(
>> name=”requirements”,
>> attributeNodes={
>> @NamedAttributeNode("description"),
>> @NamedAttributeNode("approval")
>> }
>> )
>> }
>> )
>>
>> The entity graph could also be created dynamically through the following APIs:
>>
>> /**
>> * This type represents the root of an entity graph that will be used as a
>> * template to define the attribute nodes and boundaries of a graph of entities and
>> * entity relationships. The root must be an Entity type.
>> *
>> * @param <T>
>> * the type of the root entity.
>> */
>>
>> public interface EntityGraph<T> {
>>
>> /**
>> * Returns the name of the static EntityGraph. Will return null if the
>> * EntityGraph is not a named EntityGraph.
>> */
>> public String getName();
>>
>> /*
>> * Add an AttributeNode attribute to the entity graph.
>> *
>> * @throws IllegalArgumentException if the attribute is not an attribute of
>> * this entity.
>> * @throws IllegalStateException if this EntityGraph has been statically
>> * defined
>> */
>> public <X> void addAttributeNodes(String ... attributeName);
>>
>> /*
>> * Add an AttributeNode attribute to the entity graph.
>> *
>> * @throws IllegalStateException if this EntityGraph has been statically
>> * defined
>> */
>> public <X> void addAttributeNodes(Attribute<T, X> ... attribute);
>>
>> /*
>> * Used to add a node of the graph that corresponds to a managed type. This
>> * allows for construction of multi-node Entity graphs that include related
>> * managed types.
>> *
>> * @throws IllegalArgumentException if the attribute's target type is not a
>> * managed type
>> *
>> * @throws IllegalStateException if this EntityGraph has been statically
>> * defined
>> */
>> public <X> SubGraph<X> addSubGraph(Attribute<T, X> attribute);
>>
>> /**
>> * Used to add a node of the graph that corresponds to a managed type with
>> * inheritance. This allows for multiple subclass sub-graphs to be defined
>> * for this node of the entity graph. Subclass sub-graphs will include the
>> * specified attributes of superclass sub-graphs
>> *
>> * @throws IllegalArgumentException
>> * if the attribute's target type is not a managed type
>> * @throws IllegalStateException
>> * if this EntityGraph has been statically defined
>> */
>> public <X> SubGraph<? extends X> addSubGraph(Attribute<T, X> attribute, Class<? extends X> type);
>>
>> /*
>> * Used to add a node of the graph that corresponds to a managed type. This
>> * allows for construction of multi-node Entity graphs that include related
>> * managed types.
>> *
>> * @throws IllegalArgumentException if the attribute is not an attribute of
>> * this entity.
>> * @throws IllegalArgumentException if the attribute's target type is not a
>> * managed type
>> *
>> * @throws IllegalStateException if this EntityGraph has been statically
>> * defined
>> */
>> public <X> SubGraph<X> addSubGraph(String attribute);
>>
>> /**
>> * Used to add a node of the graph that corresponds to a managed type with
>> * inheritance. This allows for multiple subclass sub-graphs to be defined
>> * for this node of the entity graph. Subclass sub-graphs will include the
>> * specified attributes of superclass sub-graphs
>> *
>> * @throws IllegalArgumentException if the attribute is not an attribute of
>> * this managed type.
>> * @throws IllegalArgumentException
>> * if the attribute's target type is not a managed type
>> * @throws IllegalStateException
>> * if this EntityGraph has been statically defined
>> */
>> public <X> SubGraph<X> addSubGraph(String attribute, Class<X> type);
>>
>> /*
>> * Used to add a node of the graph that corresponds to a map key that is a
>> * managed type. This allows for construction of multi-node Entity graphs that
>> * include related managed types.
>> *
>> * @throws IllegalArgumentException if the attribute's target type is not a
>> * managed type entity
>> *
>> * @throws IllegalStateException if this EntityGraph has been statically
>> * defined
>> */
>> public <X> SubGraph<X> addKeySubGraph(Attribute<T, X> attribute);
>>
>> /*
>> * Used to add a node of the graph that corresponds to a map key that is a
>> * managed type with inheritance. This allows for construction of multi-
>> * node Entity graphs that include related managed types. Subclass sub-graphs
>> * will include the specified attributes of superclass sub-graphs
>> *
>> * @throws IllegalArgumentException if the attribute's target type is not a
>> * managed type entity
>>
>> *
>> * @throws IllegalStateException if this EntityGraph has been statically
>> * defined
>> */
>> public <X> SubGraph<? Extends X> addKeySubGraph(Attribute<T, X> attribute, Class<? Extends X> type);
>>
>> /*
>> * Used to add a node of the graph that corresponds to a map key that is a
>> * managed type. This allows for construction of multi-node Entity graphs that
>> * include related managed types.
>> *
>> * @throws IllegalArgumentException if the attribute is not an attribute of
>> * this entity.
>> * @throws IllegalArgumentException if the attribute's target type is not a
>> * managed type
>> *
>> * @throws IllegalStateException if this EntityGraph has been statically
>> * defined
>> */
>> public <X> SubGraph<X> addKeySubGraph(String attribute);
>>
>> /*
>> * Used to add a node of the graph that corresponds to a map key that is a
>> * managed type with inheritance. This allows for construction of multi-
>> * node Entity graphs that include related managed types. Subclass sub-graphs
>> * will include the specified attributes of superclass sub-graphs
>> *
>> * @throws IllegalArgumentException if the attribute is not an attribute of
>> * this entity.
>> * @throws IllegalArgumentException if the attribute's target type is not a
>> * managed type
>> *
>> * @throws IllegalStateException if this EntityGraph has been statically
>> * defined
>> */
>> public <X> SubGraph<X> addKeySubGraph(String attribute, Class<X> type);
>>
>> /*
>> * returns the attributes of this entity that are included in the entity
>> * graph
>> */
>> public List<AttributeNode<?>> getAttributeNodes();
>>
>> }
>>
>> /**
>> * Represents an AttributeNode of an entity graph.
>> */
>> public interface AttributeNode<T> {
>>
>> /*
>> * returns the Type of the AttributeNode.
>> */
>>
>>
>> public Type<T> getType();
>>
>> /*
>> * returns the name of the referencing attribute.
>> */
>> public String getAttributeName();
>> }
>>
>> /**
>> * This type represents a AttributeNode of an EntityGraph that corresponds to a
>> * Managed Type. Using this class an entity graph can be embedded within an
>> * EntityGraph.
>> *
>> * @param <T>
>> * the Class type of the AttributeNode.
>> */
>>
>> public interface SubGraph<T> extends AttributeNode<T> {
>>
>> /**
>> * Add an AttributeNode attribute to the entity graph.
>> *
>> * @throws IllegalArgumentException if the attribute is not an attribute of
>> * this managed type.
>> * @throws IllegalStateException
>> * if this EntityGraph has been statically defined
>> */
>> public <X> void addAttributeNodes(String ... attributeName);
>>
>> /**
>> * Add an AttributeNode attribute to the entity graph.
>> *
>> * @throws IllegalStateException
>> * if this EntityGraph has been statically defined
>> */
>> public <X> void addAttributeNodes(Attribute<T, X> ... attribute);
>>
>> /**
>> * Used to add a node of the graph that corresponds to a managed type. This
>> * allows for construction of multi-node Entity graphs that include related
>> * managed types.
>>
>> *
>> * @throws IllegalArgumentException
>> * if the attribute's target type is not a managed type
>> * @throws IllegalStateException
>> * if this EntityGraph has been statically defined
>> */
>> public <X> SubGraph<X> addSubGraph(Attribute<T, X> attribute);
>>
>> /**
>> * Used to add a node of the graph that corresponds to a managed type with
>> * inheritance. This allows for multiple subclass sub-graphs to be defined
>> * for this node of the entity graph. Subclass sub-graphs will include the
>> * specified attributes of superclass sub-graphs
>> *
>> * @throws IllegalArgumentException
>> * if the attribute's target type is not a managed type
>> * @throws IllegalStateException
>> * if this EntityGraph has been statically defined
>> */
>> public <X> SubGraph<? extends X> addSubGraph(Attribute<T, X> attribute, Class<? extends X> type);
>>
>> /**
>> * Used to add a node of the graph that corresponds to a managed type. This
>> * allows for construction of multi-node Entity graphs that include related
>> * managed types.
>> *
>> * @throws IllegalArgumentException if the attribute is not an attribute of
>> * this managed type.
>> * @throws IllegalArgumentException
>> * if the attribute's target type is not a managed type
>> * @throws IllegalStateException
>> * if this EntityGraph has been statically defined
>> */
>> public <X> SubGraph<X> addSubGraph(String attribute);
>>
>> /**
>> * Used to add a node of the graph that corresponds to a managed type with
>> * inheritance. This allows for multiple subclass sub-graphs to be defined
>> * for this node of the entity graph. Subclass sub-graphs will include the
>> * specified attributes of superclass sub-graphs
>> *
>> * @throws IllegalArgumentException if the attribute is not an attribute of
>> * this managed type.
>> * @throws IllegalArgumentException
>> * if the attribute's target type is not a managed type
>> * @throws IllegalStateException
>> * if this EntityGraph has been statically defined
>> */
>> public <X> SubGraph<X> addSubGraph(String attribute, Class<X> type);
>>
>> /*
>> * Used to add a node of the graph that corresponds to a map key that is a
>> * managed type. This allows for construction of multi-node Entity graphs that
>> * include related managed types.
>> *
>> * @throws IllegalArgumentException if the attribute's target type is not a
>> * managed type entity
>>
>> *
>> * @throws IllegalStateException if this EntityGraph has been statically
>> * defined
>> */
>> public <X> SubGraph<X> addKeySubGraph(Attribute<T, X> attribute);
>>
>> /*
>> * Used to add a node of the graph that corresponds to a map key that is a
>> * managed type with inheritance. This allows for construction of multi-
>> * node Entity graphs that include related managed types. Subclass sub-graphs
>> * will include the specified attributes of superclass sub-graphs
>> *
>> * @throws IllegalArgumentException if the attribute's target type is not a
>> * managed type entity
>>
>> *
>> * @throws IllegalStateException if this EntityGraph has been statically
>> * defined
>> */
>> public <X> SubGraph<? Extends X> addKeySubGraph(Attribute<T, X> attribute, Class<? Extends X> type);
>>
>> /*
>> * Used to add a node of the graph that corresponds to a map key that is a
>> * managed type. This allows for construction of multi-node Entity graphs that
>> * include related managed types.
>> *
>> * @throws IllegalArgumentException if the attribute is not an attribute of
>> * this entity.
>> * @throws IllegalArgumentException if the attribute's target type is not a
>> * managed type
>> *
>> * @throws IllegalStateException if this EntityGraph has been statically
>> * defined
>> */
>> public <X> SubGraph<X> addKeySubGraph(String attribute);
>>
>> /*
>> * Used to add a node of the graph that corresponds to a map key that is a
>> * managed type with inheritance. This allows for construction of multi-
>> * node Entity graphs that include related managed types. Subclass sub-graphs
>> * will include the specified attributes of superclass sub-graphs
>> *
>> * @throws IllegalArgumentException if the attribute is not an attribute of
>> * this entity.
>> * @throws IllegalArgumentException if the attribute's target type is not a
>> * managed type
>> *
>> * @throws IllegalStateException if this EntityGraph has been statically
>> * defined
>> */
>> public <X> SubGraph<X> addKeySubGraph(String attribute, Class<X> type);
>>
>> /**
>> * returns the attributes of this managed type that are included in the
>> * sub-graph
>> */
>> public List<AttributeNode<?>> getAttributeNodes();
>>
>> /**
>> * returns the attribute that references this sub-graph.
>> /
>> public <T> Attribute<T,X> getReferencingAttribute();
>>
>> /**
>> * returns the type of this sub-graph if it was used to extend a superclass’
>> * sub-graph definition.
>> */
>> public Class<X> getClassType();
>> }
>>
>> public interface EntityManagerFactory {
>> ...
>> /**
>> * returns any named EntityGraph that has been created through static
>> * metadata. Returned EntityGraphs should be considered immutable.
>> */
>> public <T> EntityGraph<T> getEntityGraph(String graphName);
>>
>> /**
>> * add a named copy of the EntityGraph to the EntityManagerFactory
>> */
>> public void addNamedEntityGraph(String graphName, EntityGraph entityGraph);
>>
>> /**
>> * returns a mutable EntityGraph that can be used to dynamically create an
>> * EntityGraph.
>> */
>> public <T> EntityGraph<T> createEntityGraph(Class<T> rootType);
>>
>> /**
>> * returns a mutable copy of the named EntityGraph
>> */
>> public EntityGraph<?> createEntityGraph(String graphName);
>>
>> Example:
>>
>> EntityGroup employee = emf.createEntityGraph(Employee.class);
>> employee.addAttributeNode("phoneNumbers");
>> SubGraph projects = employee.addSubGraph("projects");
>> projects.addAttributeNode("requirements");
>> SubGraph largeProjects = employee.addSubGraph(“projects”, LargeProject.class);
>> largeProjects.addAttributeNode(“approver”);
>>
>> EntityGroup employee = emf.createEntityGraph(Employee.class);
>> employee.addAttributeNode("phoneNumbers");
>> SubGraph requirements = employee.addSubGraph("projects")
>> .addSubGraph("requirements");
>> requirements.addAttributeNode("description");
>> requirements.addAttributeNode("approval");
>>
>> Once the EntityGraph is available or has been created it can be applied to operations on the EntityManager or used with queries to control eager loading of results.
>>
>> The standard property javax.persistence.fetchgraph can be used with the find operation or as a query hint to specify a EntityGraph that defines additional FetchType semantics whereby any AttributeNode of the EntityGraph is treated as FetchType.EAGER and any attribute not specified in the EntityGraph is treated as FetchType.LAZY. The primary key of an entity is always retrieved even if not present in the fetch group.
>>
>> The following characterizes the semantics of entity graphs that are used as fetch graphs.
>>
>> A fetch graph attribute node specified within an entity graph or sub-graph specifies how an attribute is to be fetched. Attributes that are not specified are treated as FetchType.LAZY.
>>
>> The following rules apply, depending on attribute type.
>>
>> A primary key attribute never needs to be specified in an attribute node. (This applies to composite primary keys as well, including embedded id primary keys.) When an entity is fetched, its primary key is always fetched. It is not incorrect, however, to specify primary key attributes.
>>
>> Attributes other than primary key attributes are not fetched unless the attribute is specified. The following rules apply to the specification of attributes:
>>
>> The default fetch graph for an entity or embeddable consists of the transitive closure of all of its attributes that are specified as FetchType.EAGER (or defaulted as such).
>>
>> If the attribute is an embedded attribute, and the attribute is specified in an attribute node, but a subgraph is not specified for the attribute, the default fetch graph for the embeddable is fetched. If a subgraph is specified for the attribute, the attributes of the embeddable are fetched according to their specification in the corresponding subgraph, and the rules of this section recursively apply.
>>
>> If the attribute is an element collection of basic type, and the attribute is specified in an attribute node, the element collection together with its basic elements is fetched.
>>
>> If the attribute is an element collection of embeddables, and the attribute is specified in an attribute node, but a subgraph is not specified for the attribute, the element collection together with the default fetch graph of its embeddable elements is fetched. If a subgraph is specified for the attribute, the attributes of the embeddable elements will be fetched according to the corresponding subgraph specification, and the rules of this section recursively apply.
>>
>> If the attribute is a one-to-one or many-to-one relationship, and the attribute is specified in an attribute node, but a subgraph is not specified for the attribute, the default fetch graph of the target entity is fetched. If a subgraph is specified for the attribute, the attributes of the target entity will be fetched according to the corresponding subgraph specification, and the rules of this section recursively apply.
>>
>> If the attribute is a one-to-many or many-to-many relationship, and the attribute is specified in an attribute node, but a subgraph is not specified, the collection will be fetched and the default fetch graphs of the referenced entities will be fetched. If a subgraph is specified for the attribute, the entities in the collection will be fetched according to the corresponding subgraph specification, and the rules of this section recursively apply.
>>
>> If the key of a map which has been specified in an attribute node is a basic type, it will always be fetched and if the key of a map which has been specified in an attribute node is an embedded type the default fetch graph will be fetched for the embeddable; otherwise, if a map key subgraph is not specified for the attribute node, the map key will be fetched according to its default fetch graph. If a key subgraph is specified for the map key attribute, the map key attribute will be fetched according to the map key subgraph specification, and the rules of this section recursively apply.
>>
>> So using the following entity graph:
>>
>> @NamedEntityGraph(
>> )
>>
>> used to load a Phonenumber only the id and the FKs would be retrieved.
>>
>> When using the following entity graph:
>> @NamedEntityGraph(
>> attributeNodes={
>> @NamedAttributeNode("projects"),
>> }
>> )
>>
>> loading an Employee the PKs and FKs would be retrieved and the “projects” attribute would be eagerly loaded.
>>
>> The standard property javax.persistence.loadgraph can be used to specify an entity graph that defines additional FetchType semantics with any attribute node of the entity graph becoming FetchType.EAGER and any unspecified attributes remain as defined in the mapping.
>>
>> The following characterizes the semantics of entity graphs that are used as load graphs.
>>
>> A load graph attribute node specified within an entity graph or sub-graph specifies how an attribute is to be fetched. Attributes that are not specified are treated according to their default FetchType.
>>
>> The following rules apply to the specification of attributes:
>>
>> A primary key attribute never needs to be specified in an attribute node. (This applies to composite primary keys as well, including embedded id primary keys.) When an entity is fetched, its primary key is always fetched. It is not incorrect, however, to specify primary key attributes.
>>
>> If the attribute is an embedded attribute, and the attribute is specified in an attribute node, but a subgraph is not specified for the attribute, the default fetch graph for the embeddable is fetched. If a subgraph is specified for the attribute, any attributes of the embeddable that are not further specified within the subgraph are treated according to their fetch type; attributes that are specified by the subgraph are also fetched; and the rules of this section recursively apply.
>>
>> If the attribute is an element collection of basic type, and the attribute is specified in an attribute node, the element collection together with its basic elements is fetched. If the attribute is an element collection of embeddables, and the attribute is specified in an attribute node, but a subgraph is not specified for the attribute, the element collection together with the default fetch graph of its embeddable elements is fetched. If a subgraph is specified for the attribute, any attributes of the embeddables that are not further specified are treated according to their fetch type; attributes that are specified by the subgraph are also fetched; and the rules of this section recursively apply.
>>
>> If the attribute is a one-to-one or many-to-one relationship, and the attribute is specified in an attribute node, but a subgraph is not specified for the attribute, the default fetch graph of the target entity is fetched. If a subgraph is specified for the attribute, any attributes of the target entity that are not further specified are treated according to their fetch type; attributes that are specified by the subgraph are also fetched; and the rules of this section recursively apply.
>>
>> If the attribute is a one-to-many or many-to-many relationship, and the attribute is specified in an attribute node, but a subgraph is not specified, the collection will be fetched and the default fetch graphs of the referenced entities will be fetched. If a subgraph is specified for the attribute, any entities in the collection will be treated according to their fetch type; attributes that are specified by the subgraph are also fetched; and the rules of this section recursively apply.
>>
>> If a collection-valued attribute is a map, keys that are basic or embeddable types will be fetched when the map is fetched; entity map key attributes will be fetched according to their fetch type and, if a key subgraph is specified, additional entity attributes are fetched as specified in the subgraph; and the rules of this section recursively apply.
>>
>> So using the following entity graph:
>>
>> @NamedEntityGraph(
>> )
>>
>> used to load a Phonenumber only the id and the FKs would be retrieved. The requirements attribute would not be loaded but would be lazy.
>>
>> When using the following entity graph:
>> @NamedEntityGraph(
>> attributeNodes={
>> @NamedAttributeNode("projects"),
>> }
>> )
>>
>> loading an Employee the PKs and FKs would be retrieved and the “projects” attribute would be eagerly loaded.
>>
>> EntityManager API
>> public interface EntityManager {
>>
>> /**
>> * Copy the provided entity graph using the EntityGraph as a template to
>> specify
>> * the attributes that will be copied. Attributes not included in the entity graph will not be copied.
>> *
>> * @param entity
>> * entity instance
>> * @param EntityGraph
>> * the entity graph template for applying copy.
>> * @throws IllegalArgumentException
>> * if the instance is not an entity or the EntityGraph root is
>> * not the same class as the entity.
>> */
>> public void copy(Object entity, EntityGraph entityGraph, Map<String, Object> properties);
>> ...
>>
>> /**
>> * Merge the state of the given entity into the current persistence context
>> * using the EntityGraph as a template for applying the merge operation.
>> *
>> *
>> * @param entity
>> * entity instance
>> * @param EntityGraph
>> * the entity graph template for applying merge.
>> * @return the managed instance that the state was merged to
>> * @throws IllegalArgumentException
>> * if instance is not an entity, is a removed entity or the root
>> * of the EntityGraph is not of the same type as the entity
>> * @throws TransactionRequiredException
>> * if there is no transaction when invoked on a
>> * container-managed entity manager of that is of type
>> * <code>PersistenceContextType.TRANSACTION</code>
>> */
>> public <T> T merge(T entity, EntityGraph entityGraph, Map<String, Object> properties);
>> ...etc
>> }
>>
>> Merge
>> When using an entity graph in combination with the “merge” operation any listed attribute node will be merged and any unlisted attribute node will not be merged, this includes @Basic mappings. Any attribute that references a Map is considered to include both the key and the value. If the attribute node references a sub-graph or map key sub-graph for the relationship target then the merge will operate on that target object as well with only those attributes referenced in the sub-graph being merged and this will apply recursively.
>>
>> For example with the merge operation applied with the following entity graph :
>>
>> @NamedEntityGraph(
>> attributeNodes={
>> @NamedAttributeNode(“name”),
>> @NamedAttributeNode(
>> value="projects",
>> subGraph=”projects”
>> ),
>> @NamedAttributeNode("phoneNumbers"),
>> },
>> subGraphs={
>> @NamedSubGraph(
>> name=”projects”,
>> attributeNodes={
>> @NamedAttributeNode("requirements")
>> }
>> )
>> }
>> )
>>
>> Only the name, projects and phoneNumbers attributes of the Employee will be merged. The merge will be applied to the projects but only the requirements attribute of the Project will be merged and the merge will not be applied to the Requirement target. The PhoneNumber target will not be merged.
>>
>> Copy
>> A new operation “copy” is being introduced. This operation is intended to be used when a user wishes to disconnect a graph of entities from a larger graph. When using an entity graph in combination with the “copy” operation a copy of the provided entity is created and the attributes of the copied entity are populated based on the attributes listed in the entity graph. If an attribute node for an attribute is present then the attribute will be copied. If the attribute node represents an attribute that has a managed type as the target, element or key type then that target instance is copied as well and the copy is set in the new tree. If a sub-graph is defined for the value or key then any attributes corresponding to the attribute nodes within the sub-graph will be copied as above. If no sub-graph is defined for the attribute node then no attributes of the target are copied.
>>
>> For example with the copy operation applied with the following entity graph :
>>
>> @NamedEntityGraph(
>> attributeNodes={
>> @NamedAttributeNode(“name”),
>> @NamedAttributeNode(
>> value="projects",
>> subGraph=”projects”
>> ),
>> @NamedAttributeNode("phoneNumbers"),
>> },
>> subGraphs={
>> @NamedSubGraph(
>> name=”projects”,
>> attributeNodes={
>> @NamedAttributeNode("requirements")
>> }
>> )
>> }
>> )
>>
>> When applied to an Employee instance a new copy of the Employee will be created and the “name” , “phoneNumbers” and “projects” attributes will be copied over. For each PhoneNumber in the phoneNumbers list a new copy of the PhoneNumber will be created and used but no attributes will be copied. For each Project in the projects list a new copy of the Project will be created and used and only the requirements attribute will be copied. For each Requirement in the requirements list a new copy of the Requirement will be created but no attributes will be copied.
>>