Hi Gordon,
On Tue, Nov 27, 2012 at 10:20 PM, Gordon Yorke <gordon.yorke_at_oracle.com>wrote:
> Attributes other than primary key attributes are not fetched unless the
> attribute is specified.
This reads a bit like that the non-specified attributes must not be loaded,
in difference to the FetchType.LAZY
semantics, which is "need not be loaded".
I would prefer to have this aligned (maybe that was even the intention?)
with the FetchType.LAZY semantics, as
in our implementation we do always load full objects, and never load
objects partially (i.e. only a subset of attributes)
Christian
On Tue, Nov 27, 2012 at 10:20 PM, Gordon Yorke <gordon.yorke_at_oracle.com>wrote:
> 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 asFetchType.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.
>
>
--
Christian von Kutzleben
Chief Engineer | Versant GmbH
(T) +49 40 60990-0
(F) +49 40 60990-113
(E) cvkutzleben_at_versant.com <cromberg_at_versant.com>
www.versant.com | www.db4o.com
--
Versant
GmbH is incorporated in Germany. Company registration number: HRB
54723, Amtsgericht Hamburg. Registered Office: Halenreie 42, 22359
Hamburg, Germany. Geschäftsführer: Bernhard Wöbker, Volker John
CONFIDENTIALITY
NOTICE: This e-mail message, including any attachments, is for the sole
use of the intended recipient(s) and may contain confidential or
proprietary information. Any unauthorized review, use, disclosure or
distribution is prohibited. If you are not the intended recipient,
immediately contact the sender by reply e-mail and destroy all copies of
the original message.