getAttributeNodes() should only return the nodes explicitly added by the
user.
--Gordon
On 15/02/2013 10:32 AM, Steve Ebersole wrote:
> I guess the larger question here is about the intent of
> getAttributeNodes(). Is the expectation for it to return just the
> attribute nodes explicitly added by the user, or nodes for all the
> attributes that the persistence provider will actually be fetching?
>
> That distinction goes beyond just id and version attributes. As the
> spec says, a "persistence provider is permitted to fetch additional
> entity state beyond that specified by a fetch graph or load graph" as
> long as the provider at the least fetches any explicitly added
> attribute nodes. So given a call like:
>
> em.createEntityGraph( SomeEntity.class )
>
> a provider is free to fetch all attributes of SomeEntity.
>
> So which truth should getAttributeNodes() return?
>
>
>
> On Thu 14 Feb 2013 04:17:46 PM CST, Steve Ebersole wrote:
>> Quick clarification question...
>>
>> In regards to entity graphs the spec says that an entity's identifier
>> and version attributes are automatically considered to be part of the
>> fetch graph. Does that mean, specifically, that:
>>
>> em.createEntityGraph( SomeEntity.class ).getAttributeNodes()
>>
>> should contain AttributeNodes for SomeEntity's identifier and version
>> (if any) attributes? Or is the "automatically" more considered
>> implicit?
>>
>>
>> On Fri 01 Feb 2013 01:32:08 PM CST, Linda DeMichiel wrote:
>>> Available now on the project Downloads area.
>>>
>>> On 2/1/2013 11:17 AM, Linda DeMichiel wrote:
>>>> Since there seems to be agreement on this, I have proceeded to update
>>>> the spec.
>>>> I'll be posting the updated javadocs shortly.
>>>>
>>>> thanks,
>>>>
>>>> -Linda
>>>>
>>>>
>>>> On 1/30/2013 11:29 AM, Gordon Yorke wrote:
>>>>> The original plan was to simplify the interfaces and eliminate the
>>>>> AttributeNode as an artifact the user needed, however
>>>>> as the structure of the Subgraph became more complex to support the
>>>>> more complex scenarios I no longer think this is an
>>>>> option as we should support inspection in the future. I am proposing
>>>>> that Subgraph interface no longer extends from
>>>>> AttributeNode and that AttributeNode would be updated to be :
>>>>> public interface AttributeNode<T> {
>>>>>
>>>>> /**
>>>>> * Return the name of the attribute corresponding to the
>>>>> * attribute node.
>>>>> * @return name of the attribute
>>>>> */
>>>>> public String getAttributeName();
>>>>>
>>>>> /**
>>>>> * Return the Map<Class, Subgraph> of Subgraphs associated with this
>>>>> AttributeNode
>>>>> * @return Map of Subgraphs associated with this AttribureNode
>>>>> */
>>>>> public Map<Class, Subgraph> getSubgraphs();
>>>>>
>>>>> /**
>>>>> * Return the Map<Class, Subgraph> of Subgraphs associated with this
>>>>> AttributeNode's map key
>>>>> * @return Map of Subgraphs associated with this AttribureNode's map
>>>>> key
>>>>> */
>>>>> public Map<Class, Subgraph> getKeySubgraphs();
>>>>> }
>>>>>
>>>>> This would allow for easier inspection of the EntityGraph and easily
>>>>> allow the user to differentiate between map key
>>>>> subgraphs and element subgraphs.
>>>>> --Gordon
>>>>>
>>>>> On 30/01/2013 12:35 PM, Linda DeMichiel wrote:
>>>>>> Hi Gordon,
>>>>>>
>>>>>> Could you propose the specific methods that you think should be
>>>>>> added in this release?
>>>>>>
>>>>>> thanks,
>>>>>>
>>>>>> -Linda
>>>>>>
>>>>>>
>>>>>> On 1/30/2013 6:29 AM, Gordon Yorke wrote:
>>>>>>> Yes, they should although it may be easier to support more
>>>>>>> inspection in the future if AttributeNode.getSubgraps()
>>>>>>> AttributeNode.getKeySubgraphs() were to exist or planned to exist.
>>>>>>> The alternate pattern that will be needed of
>>>>>>> isKeySubgraph() is not a great pattern. I think we should add this
>>>>>>> simple methods to this release if possible.
>>>>>>> --Gordon
>>>>>>>
>>>>>>>
>>>>>>> On 29/01/2013 5:42 PM, Steve Ebersole wrote:
>>>>>>>> Also related... Do EntityGraph.getAttributeNodes /
>>>>>>>> Subgraph.getAttributeNodes return Subgraphs in the AttributeNode
>>>>>>>> list?
>>>>>>>>
>>>>>>>> On Tue 29 Jan 2013 04:14:13 PM CST, Steve Ebersole wrote:
>>>>>>>>> What is the proposed behavior of EntityGraph or Subgraph when
>>>>>>>>> addAttributeNodes is called with non-basic attribute types (a
>>>>>>>>> ManyToOne for example)? Is that considered an exception
>>>>>>>>> condition?
>>>>>>>>> And if so, what exception (IllegalArgumentException)? Or do
>>>>>>>>> providers
>>>>>>>>> simply interpret it as a call to addSubgraph?
>>>>>>>>>
>>>>>>>>> Also, a minor edit to report in the spec, at least as of the
>>>>>>>>> Public
>>>>>>>>> Review Draft. In the definition of the NamedEntityGraph
>>>>>>>>> annotation,
>>>>>>>>> the type of subclassSubgraphs is defined as NamedSubGraph[]
>>>>>>>>> rather
>>>>>>>>> than NamedSubgraph[]
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> On Sun 09 Dec 2012 05:04:55 PM CST, Linda DeMichiel wrote:
>>>>>>>>>> I've spec'd out a more detailed version of the proposal. Please
>>>>>>>>>> review and comment.
>>>>>>>>>>
>>>>>>>>>> thanks,
>>>>>>>>>>
>>>>>>>>>> -Linda
>>>>>>>>>>
>>>>>>>>>> -------------------------------
>>>>>>>>>>
>>>>>>>>>> Section: Entity Graphs
>>>>>>>>>>
>>>>>>>>>> An entity graph is a template that is defined in the form of
>>>>>>>>>> metadata
>>>>>>>>>> or an object created by the dynamic EntityGraph API and that
>>>>>>>>>> captures
>>>>>>>>>> the path and boundaries for an operation or query.
>>>>>>>>>>
>>>>>>>>>> Entity graphs are used in the specification of "fetch plans" for
>>>>>>>>>> query or find operations and as specifications for the
>>>>>>>>>> boundaries
>>>>>>>>>> of merge or copy operations.
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> Subsection: Use of Entity Graphs in find and query operations
>>>>>>>>>>
>>>>>>>>>> An entity graph can be used with the find operation or as a
>>>>>>>>>> query
>>>>>>>>>> hint to override or augment FetchType semantics.
>>>>>>>>>>
>>>>>>>>>> The standard properties javax.persistence.fetchgraph and
>>>>>>>>>> javax.persistence.loadgraph are used to specify such graphs to
>>>>>>>>>> queries
>>>>>>>>>> and find operations.
>>>>>>>>>>
>>>>>>>>>> The default fetch graph for an entity or embeddable is
>>>>>>>>>> defined to
>>>>>>>>>> consist of the transitive closure of all of its attributes that
>>>>>>>>>> are
>>>>>>>>>> specified as FetchType.EAGER (or defaulted as such).
>>>>>>>>>>
>>>>>>>>>> The persistence provider is permitted to fetch additional
>>>>>>>>>> entity state
>>>>>>>>>> beyond that specified by a fetch graph or load graph. It is
>>>>>>>>>> required,
>>>>>>>>>> however, that the persistence provider fetch all state
>>>>>>>>>> specified by the
>>>>>>>>>> fetch or load graph.
>>>>>>>>>>
>>>>>>>>>> Subsectionsection: Fetch graph semantics
>>>>>>>>>>
>>>>>>>>>> When the javax.persistence.fetchgraph property is used to
>>>>>>>>>> specify an
>>>>>>>>>> entity graph, attributes that are specified by attribute nodes
>>>>>>>>>> of the
>>>>>>>>>> entity graph are treated as FetchType.EAGER and attributes that
>>>>>>>>>> are
>>>>>>>>>> not specified are treated as FetchType.LAZY. The primary key and
>>>>>>>>>> version attributes of an entity are always retrieved, even if
>>>>>>>>>> not
>>>>>>>>>> specified by the fetch graph.
>>>>>>>>>>
>>>>>>>>>> The following rules apply, depending on attribute type. The
>>>>>>>>>> rules of
>>>>>>>>>> this section are applied recursively.
>>>>>>>>>>
>>>>>>>>>> A primary key or version attribute never needs to be specified
>>>>>>>>>> in an
>>>>>>>>>> attribute node of a fetch graph. (This applies to composite
>>>>>>>>>> primary
>>>>>>>>>> keys as well, including embedded id primary keys.) When an
>>>>>>>>>> entity is
>>>>>>>>>> fetched, its primary key and version attributes are always
>>>>>>>>>> fetched.
>>>>>>>>>> It is not incorrect, however, to specify primary key
>>>>>>>>>> attributes or
>>>>>>>>>> version attributes.
>>>>>>>>>>
>>>>>>>>>> Attributes other than primary key and version attributes are
>>>>>>>>>> assumed
>>>>>>>>>> not to be fetched unless the attribute is specified. The
>>>>>>>>>> following
>>>>>>>>>> rules apply to the specification of 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, the attributes of
>>>>>>>>>> the
>>>>>>>>>> embeddable are fetched according to their specification in the
>>>>>>>>>> corresponding subgraph.
>>>>>>>>>>
>>>>>>>>>> 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.
>>>>>>>>>>
>>>>>>>>>> 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.
>>>>>>>>>>
>>>>>>>>>> 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.
>>>>>>>>>>
>>>>>>>>>> If the key of a map which has been specified in an attribute
>>>>>>>>>> node is a
>>>>>>>>>> basic type, it will always be fetched. 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
>>>>>>>>>> the key
>>>>>>>>>> of the map is an entity, and 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.
>>>>>>>>>>
>>>>>>>>>> Example:
>>>>>>>>>>
>>>>>>>>>> @NamedEntityGraph
>>>>>>>>>> @Entity
>>>>>>>>>> public class Phonenumber{
>>>>>>>>>> @Id
>>>>>>>>>> protected String number;
>>>>>>>>>>
>>>>>>>>>> protected PhoneTypeEnum type;
>>>>>>>>>> ...
>>>>>>>>>> }
>>>>>>>>>>
>>>>>>>>>> In this example, only the number attribute would be eagerly
>>>>>>>>>> fetched.
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> Example:
>>>>>>>>>>
>>>>>>>>>> @NamedEntityGraph(
>>>>>>>>>> attributeNodes={
>>>>>>>>>> @NamedAttributeNode("projects")
>>>>>>>>>> }
>>>>>>>>>> )
>>>>>>>>>> @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;
>>>>>>>>>>
>>>>>>>>>> String name;
>>>>>>>>>>
>>>>>>>>>> @OneToOne(fetch=FetchType.EAGER)
>>>>>>>>>> protected Requirements doc;
>>>>>>>>>> ...
>>>>>>>>>> }
>>>>>>>>>>
>>>>>>>>>> @Entity
>>>>>>>>>> public class LargeProject extends Project{
>>>>>>>>>>
>>>>>>>>>> @OneToOne(fetch=FetchType.LAZY)
>>>>>>>>>> protected Employee approver;
>>>>>>>>>> ...
>>>>>>>>>> }
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> @Entity
>>>>>>>>>> public class Requirements{
>>>>>>>>>> @Id
>>>>>>>>>> protected long id;
>>>>>>>>>>
>>>>>>>>>> @Lob
>>>>>>>>>> protected String description;
>>>>>>>>>>
>>>>>>>>>> @OneToOne(fetch=FetchType.LAZY)
>>>>>>>>>> protected Approval approval
>>>>>>>>>> ...
>>>>>>>>>> }
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> In the above example, the Employee entity's primary key will be
>>>>>>>>>> fetched as well as the related project instances, whose default
>>>>>>>>>> fetch
>>>>>>>>>> graph (id, name, and doc attributes) will be fetched. The
>>>>>>>>>> related
>>>>>>>>>> Requirements object will be fetched according to its default
>>>>>>>>>> fetch
>>>>>>>>>> graph.
>>>>>>>>>>
>>>>>>>>>> If the approver attribute of LargeProject were FetchType.EAGER,
>>>>>>>>>> and
>>>>>>>>>> if any of the projects were instances of LargeProject, their
>>>>>>>>>> approver
>>>>>>>>>> attributes would also be fetched. Since the type of the approver
>>>>>>>>>> attribute is Employee, the approver's default fetch graph (id,
>>>>>>>>>> name,
>>>>>>>>>> and employeeNumber attributes) would also be fetched.
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> Subsubsection: Load graph semantics:
>>>>>>>>>>
>>>>>>>>>> When the javax.persistence.loadgraph property is used to
>>>>>>>>>> specify an
>>>>>>>>>> entity graph, attributes that are specified by attribute nodes
>>>>>>>>>> of the
>>>>>>>>>> entity graph are treated as FetchType.EAGER and attributes that
>>>>>>>>>> are
>>>>>>>>>> not specified are treated according to their specified or
>>>>>>>>>> default
>>>>>>>>>> FetchType. The primary key and version attributes of an entity
>>>>>>>>>> are
>>>>>>>>>> always retrieved.
>>>>>>>>>>
>>>>>>>>>> The following rules apply. The rules of this section are applied
>>>>>>>>>> recursively.
>>>>>>>>>>
>>>>>>>>>> A primary key or version attribute never needs to be specified
>>>>>>>>>> in an
>>>>>>>>>> attribute node of a load graph. (This applies to composite
>>>>>>>>>> primary
>>>>>>>>>> keys as well, including embedded id primary keys.) When an
>>>>>>>>>> entity is
>>>>>>>>>> fetched, its primary key and version attributes are always
>>>>>>>>>> fetched.
>>>>>>>>>> It is not incorrect, however, to specify primary key
>>>>>>>>>> attributes or
>>>>>>>>>> version attributes.
>>>>>>>>>>
>>>>>>>>>> If the attribute is an embedded attribute, and the attribute is
>>>>>>>>>> specified in an attribute node, the default fetch graph for the
>>>>>>>>>> embeddable is fetched. If a subgraph is specified for the
>>>>>>>>>> attribute,
>>>>>>>>>> attributes that are specified by the subgraph are also fetched.
>>>>>>>>>>
>>>>>>>>>> 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, the element
>>>>>>>>>> collection
>>>>>>>>>> together with the default fetch graph of its embeddable
>>>>>>>>>> elements is
>>>>>>>>>> fetched. If a subgraph is specified for the attribute,
>>>>>>>>>> attributes
>>>>>>>>>> that are specified by the subgraph are also fetched.
>>>>>>>>>>
>>>>>>>>>> If the attribute is a one-to-one or many-to-one relationship,
>>>>>>>>>> and the
>>>>>>>>>> attribute is specified in an attribute node, the default fetch
>>>>>>>>>> graph
>>>>>>>>>> of the target entity is fetched. If a subgraph is specified for
>>>>>>>>>> the
>>>>>>>>>> attribute, attributes that are specified by the subgraph are
>>>>>>>>>> also
>>>>>>>>>> fetched.
>>>>>>>>>>
>>>>>>>>>> If the attribute is a one-to-many or many-to-many relationship,
>>>>>>>>>> and
>>>>>>>>>> the attribute is specified in an attribute node, 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,
>>>>>>>>>> attributes that are specified by the subgraph are also fetched.
>>>>>>>>>>
>>>>>>>>>> If a collection-valued attribute is a map, and the map-valued
>>>>>>>>>> attribute is specified in an attribute node, keys that are
>>>>>>>>>> basic or
>>>>>>>>>> embeddable types will be fetched when the map is fetched;
>>>>>>>>>> entity map
>>>>>>>>>> key attributes will be fetched according to the default fetch
>>>>>>>>>> graph
>>>>>>>>>> and, if a key subgraph is specified, additional entity
>>>>>>>>>> attributes are
>>>>>>>>>> fetched as specified in the subgraph.
>>>>>>>>>>
>>>>>>>>>> Example:
>>>>>>>>>>
>>>>>>>>>> @NamedEntityGraph
>>>>>>>>>> @Entity
>>>>>>>>>> public class Phonenumber{
>>>>>>>>>> @Id
>>>>>>>>>> protected String number;
>>>>>>>>>>
>>>>>>>>>> protected PhoneTypeEnum type;
>>>>>>>>>> ...
>>>>>>>>>> }
>>>>>>>>>>
>>>>>>>>>> In the above example, the number and type attributes are loaded.
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> Example:
>>>>>>>>>>
>>>>>>>>>> @NamedEntityGraph(
>>>>>>>>>> attributeNodes={
>>>>>>>>>> @NamedAttributeNode("projects")
>>>>>>>>>> }
>>>>>>>>>> )
>>>>>>>>>> @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;
>>>>>>>>>>
>>>>>>>>>> String name;
>>>>>>>>>>
>>>>>>>>>> @OneToOne(fetch=FetchType.EAGER)
>>>>>>>>>> protected Requirements doc;
>>>>>>>>>> ...
>>>>>>>>>> }
>>>>>>>>>>
>>>>>>>>>> @Entity
>>>>>>>>>> public class LargeProject extends Project{
>>>>>>>>>>
>>>>>>>>>> @OneToOne(fetch=FetchType.LAZY)
>>>>>>>>>> protected Employee approver;
>>>>>>>>>> ...
>>>>>>>>>> }
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> @Entity
>>>>>>>>>> public class Requirements{
>>>>>>>>>> @Id
>>>>>>>>>> protected long id;
>>>>>>>>>>
>>>>>>>>>> @Lob
>>>>>>>>>> protected String description;
>>>>>>>>>>
>>>>>>>>>> @OneToOne(fetch=FetchType.LAZY)
>>>>>>>>>> protected Approval approval
>>>>>>>>>> ...
>>>>>>>>>> }
>>>>>>>>>>
>>>>>>>>>> In the above example, the default fetch graph (id, name, and
>>>>>>>>>> employeeNumber) of Employee is loaded. The default fetch
>>>>>>>>>> graphs of
>>>>>>>>>> the related Project instances (id, name, and doc attributes)
>>>>>>>>>> and their
>>>>>>>>>> Requirements instances (id and description attributes) are also
>>>>>>>>>> loaded.
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> Subsection: Merge graph semantics
>>>>>>>>>>
>>>>>>>>>> An entity graph may be used as a "merge graph" and passed as an
>>>>>>>>>> argument to the merge method.
>>>>>>>>>>
>>>>>>>>>> The following semantics apply to entity graphs that are used as
>>>>>>>>>> merge
>>>>>>>>>> graphs.
>>>>>>>>>>
>>>>>>>>>> A merge graph attribute node specified within an entity graph or
>>>>>>>>>> subgraph specifies how an attribute is to be merged. Primary
>>>>>>>>>> key and
>>>>>>>>>> version attributes do not need to be specified in the merge
>>>>>>>>>> graph. If
>>>>>>>>>> other attributes are not specified, they are not merged. Note
>>>>>>>>>> that
>>>>>>>>>> cascade=MERGE specifications are ignored.
>>>>>>>>>>
>>>>>>>>>> The persistence provider must observe the scope and boundaries
>>>>>>>>>> of a
>>>>>>>>>> merge graph specification exactly.
>>>>>>>>>>
>>>>>>>>>> The following additional rules apply for attributes that are
>>>>>>>>>> specified in attribute nodes. These rules are applied
>>>>>>>>>> recursively.
>>>>>>>>>>
>>>>>>>>>> If the attribute is an embedded attribute and a subgraph is not
>>>>>>>>>> specified for the attribute, the embedded attribute is merged
>>>>>>>>>> but the
>>>>>>>>>> attributes of the embeddable are not merged. If a subgraph is
>>>>>>>>>> specified for the attribute, the attributes of the embeddable
>>>>>>>>>> are
>>>>>>>>>> merged according to their specification in the corresponding
>>>>>>>>>> subgraph.
>>>>>>>>>>
>>>>>>>>>> If the attribute is an element collection of basic type, the
>>>>>>>>>> element
>>>>>>>>>> collection is merged. The values in the element collection are
>>>>>>>>>> replaced.
>>>>>>>>>>
>>>>>>>>>> If the attribute is an element collection of embeddables and a
>>>>>>>>>> subgraph is not specified for the attribute, the element
>>>>>>>>>> collection is
>>>>>>>>>> merged. The values in the element collection are replaced and
>>>>>>>>>> all
>>>>>>>>>> attributes of the embeddables are included. If a subgraph is
>>>>>>>>>> specified for the attribute, the values in the element
>>>>>>>>>> collection are
>>>>>>>>>> replaced and all attributes of the embeddables are included,
>>>>>>>>>> and the
>>>>>>>>>> attributes specified in the subgraph are processed according to
>>>>>>>>>> the
>>>>>>>>>> subgraph specification.
>>>>>>>>>>
>>>>>>>>>> If the attribute is a one-to-one or many-to-one relationship
>>>>>>>>>> and a
>>>>>>>>>> subgraph is not specified for the attribute, the attribute is
>>>>>>>>>> merged,
>>>>>>>>>> but the attributes of the target entity are not merged. If a
>>>>>>>>>> subgraph
>>>>>>>>>> is specified for the attribute, the attributes of the target
>>>>>>>>>> entity
>>>>>>>>>> will be merged according to the corresponding subgraph
>>>>>>>>>> specification.
>>>>>>>>>>
>>>>>>>>>> If the attribute is a one-to-many or many-to-many relationship
>>>>>>>>>> and a
>>>>>>>>>> subgraph is not specified for the attribute, the attribute is
>>>>>>>>>> merged,
>>>>>>>>>> but the attributes of the target entity are not merged. If a
>>>>>>>>>> subgraph
>>>>>>>>>> is specified for the attribute, the entities in the collection
>>>>>>>>>> will be
>>>>>>>>>> merged according to the corresponding subgraph specification.
>>>>>>>>>>
>>>>>>>>>> In both of the two relationship cases above, note that if a new
>>>>>>>>>> entity (entity in the "new" state) was added to the
>>>>>>>>>> relationship and
>>>>>>>>>> only a subset of its attributes is specified in the subgraph,
>>>>>>>>>> only
>>>>>>>>>> those specified attributes are copied.
>>>>>>>>>>
>>>>>>>>>> If the attribute is a map, the map key will be merged. If the
>>>>>>>>>> map key
>>>>>>>>>> is an embeddable, all attributes of the embeddable are
>>>>>>>>>> included. If
>>>>>>>>>> the map key is an entity, the attribute is merged, but the
>>>>>>>>>> attributes
>>>>>>>>>> of the target entity are not merged. If a subgraph is specified
>>>>>>>>>> for
>>>>>>>>>> the attribute, the target entity is merged according to the
>>>>>>>>>> corresponding
>>>>>>>>>> subgraph specification.
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> Example:
>>>>>>>>>>
>>>>>>>>>> @NamedEntityGraph(
>>>>>>>>>> attributeNodes={
>>>>>>>>>> @NamedAttributeNode("name"),
>>>>>>>>>> @NamedAttributeNode(
>>>>>>>>>> value="projects",
>>>>>>>>>> subGraph="projects"
>>>>>>>>>> ),
>>>>>>>>>> @NamedAttributeNode("phoneNumbers"),
>>>>>>>>>> },
>>>>>>>>>> subGraphs={
>>>>>>>>>> @NamedSubGraph(
>>>>>>>>>> name="projects",
>>>>>>>>>> attributeNodes={
>>>>>>>>>> @NamedAttributeNode("doc")
>>>>>>>>>> }
>>>>>>>>>> )
>>>>>>>>>> }
>>>>>>>>>> )
>>>>>>>>>> @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
>>>>>>>>>> public class Phonenumber{
>>>>>>>>>> @Id
>>>>>>>>>> protected String number;
>>>>>>>>>>
>>>>>>>>>> protected PhoneTypeEnum type;
>>>>>>>>>> ...
>>>>>>>>>> }
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> @Entity
>>>>>>>>>> @Inheritance
>>>>>>>>>> public class Project{
>>>>>>>>>> @Id
>>>>>>>>>> @GeneratedValue
>>>>>>>>>> protected long id;
>>>>>>>>>>
>>>>>>>>>> String name;
>>>>>>>>>>
>>>>>>>>>> @OneToOne(fetch=FetchType.EAGER)
>>>>>>>>>> protected Requirements doc;
>>>>>>>>>> ...
>>>>>>>>>> }
>>>>>>>>>>
>>>>>>>>>> In the above example, the name attribute and the projects and
>>>>>>>>>> phoneNumbers
>>>>>>>>>> collections will be merged. Within projects, only the doc
>>>>>>>>>> attribute
>>>>>>>>>> will
>>>>>>>>>> be merged. No attributes of phoneNumbers will be merged.
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> Subsection: Copy graph semantics
>>>>>>>>>>
>>>>>>>>>> An entity graph may be used as a "copy graph" and passed as an
>>>>>>>>>> argument to the copy method.
>>>>>>>>>>
>>>>>>>>>> The copy method is intended for use in disconnecting a graph of
>>>>>>>>>> entities from a larger graph. When using an entity graph in
>>>>>>>>>> combination with the copy operation, a copy of the entity is
>>>>>>>>>> created
>>>>>>>>>> and the attributes of the copied entity are populated based on
>>>>>>>>>> copies
>>>>>>>>>> of the attributes listed in the entity graph.
>>>>>>>>>>
>>>>>>>>>> The following semantics apply to entity graphs that are used as
>>>>>>>>>> copy
>>>>>>>>>> graphs.
>>>>>>>>>>
>>>>>>>>>> The persistence provider must observe the scope and boundaries
>>>>>>>>>> of a
>>>>>>>>>> copy graph specification exactly.
>>>>>>>>>>
>>>>>>>>>> OPEN ISSUE: If a copy graph specifies an attribute that has not
>>>>>>>>>> yet been loaded, should it be loaded?
>>>>>>>>>>
>>>>>>>>>> The following rules apply to the specification of attributes.
>>>>>>>>>> The
>>>>>>>>>> rules of this section are applied recursively.
>>>>>>>>>>
>>>>>>>>>> Primary key and version attributes are always copied.
>>>>>>>>>> Attributes are otherwise not copied unless they are specified.
>>>>>>>>>>
>>>>>>>>>> If the attribute is an embedded attribute and an attribute
>>>>>>>>>> node is
>>>>>>>>>> specified for the attribute but a subgraph is not specified for
>>>>>>>>>> the
>>>>>>>>>> attribute, a new instance of the embeddable is inserted into the
>>>>>>>>>> resulting copy of the entity graph, but no state is copied. If a
>>>>>>>>>> subgraph is specified for the attribute, the attributes of the
>>>>>>>>>> embeddable are copied according to their specification in the
>>>>>>>>>> corresponding subgraph.
>>>>>>>>>>
>>>>>>>>>> If the attribute is an element collection of basic type, the
>>>>>>>>>> element
>>>>>>>>>> collection and its contents are copied.
>>>>>>>>>>
>>>>>>>>>> If the attribute is an element collection of embeddables and an
>>>>>>>>>> attribute node is specified for the attribute but a subgraph is
>>>>>>>>>> not
>>>>>>>>>> specified, a new collection is created and new embeddables
>>>>>>>>>> instances
>>>>>>>>>> are inserted into it, but no state is copied. If a subgraph is
>>>>>>>>>> specified for the attribute, the embeddables are copied
>>>>>>>>>> according to
>>>>>>>>>> their specification in the subgraph.
>>>>>>>>>>
>>>>>>>>>> If the attribute is a one-to-one or many-to-one relationship
>>>>>>>>>> and an
>>>>>>>>>> attribute node is specified for the attribute, but a subgraph
>>>>>>>>>> is not
>>>>>>>>>> specified, a copy of the entity is created and inserted. Only
>>>>>>>>>> the
>>>>>>>>>> primary key and version attributes of the entity are copied.
>>>>>>>>>> If a
>>>>>>>>>> subgraph is specified for the attribute, a copy of the entity is
>>>>>>>>>> created and inserted and the attributes of the target entity are
>>>>>>>>>> copied according to the corresponding subgraph specification
>>>>>>>>>> along
>>>>>>>>>> with the primary key and version attributes.
>>>>>>>>>>
>>>>>>>>>> If the attribute is a one-to-many or many-to-many relationship
>>>>>>>>>> and an
>>>>>>>>>> attribute node is specified for the attribute, but a subgraph
>>>>>>>>>> is not
>>>>>>>>>> specified, a new collection is created and inserted, and copies
>>>>>>>>>> of the
>>>>>>>>>> referenced entities are created and inserted into the
>>>>>>>>>> collection.
>>>>>>>>>> Only the primary key and version attributes of these entities
>>>>>>>>>> are
>>>>>>>>>> copied. If a subgraph is specified for the attribute, the
>>>>>>>>>> entities in
>>>>>>>>>> the collection will be copied according to the corresponding
>>>>>>>>>> subgraph
>>>>>>>>>> specification along with the primary key and version attributes.
>>>>>>>>>>
>>>>>>>>>> If the attribute is a map and an attribute node has been
>>>>>>>>>> specified for
>>>>>>>>>> the attribute:
>>>>>>>>>> if the map key attribute is a basic type, it is copied;
>>>>>>>>>> if the map key attribute is an embedded attribute, a new
>>>>>>>>>> instance
>>>>>>>>>> of the
>>>>>>>>>> embeddable is inserted but no state is copied;
>>>>>>>>>> if the map key attribute is an entity, a copy of the entity is
>>>>>>>>>> created,
>>>>>>>>>> and only the primary key and version attributes of the entity
>>>>>>>>>> are copied.
>>>>>>>>>> If a subgraph is specified for the embeddable or entity, the
>>>>>>>>>> attributes
>>>>>>>>>> of the target are copied according to the corresponding map key
>>>>>>>>>> subgraph specification.
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> Example:
>>>>>>>>>>
>>>>>>>>>> @NamedEntityGraph(
>>>>>>>>>> attributeNodes={
>>>>>>>>>> @NamedAttributeNode("name"),
>>>>>>>>>> @NamedAttributeNode(
>>>>>>>>>> value="projects",
>>>>>>>>>> subGraph="projects"
>>>>>>>>>> ),
>>>>>>>>>> @NamedAttributeNode("phoneNumbers"),
>>>>>>>>>> },
>>>>>>>>>> subGraphs={
>>>>>>>>>> @NamedSubGraph(
>>>>>>>>>> name="projects",
>>>>>>>>>> attributeNodes={
>>>>>>>>>> @NamedAttributeNode("doc")
>>>>>>>>>> }
>>>>>>>>>> )
>>>>>>>>>> }
>>>>>>>>>> )
>>>>>>>>>> @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
>>>>>>>>>> public class Phonenumber{
>>>>>>>>>> @Id
>>>>>>>>>> protected String number;
>>>>>>>>>>
>>>>>>>>>> protected PhoneTypeEnum type;
>>>>>>>>>> ...
>>>>>>>>>> }
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> @Entity
>>>>>>>>>> @Inheritance
>>>>>>>>>> public class Project{
>>>>>>>>>> @Id
>>>>>>>>>> @GeneratedValue
>>>>>>>>>> protected long id;
>>>>>>>>>>
>>>>>>>>>> String name;
>>>>>>>>>>
>>>>>>>>>> @OneToOne(fetch=FetchType.EAGER)
>>>>>>>>>> protected Requirements doc;
>>>>>>>>>> ...
>>>>>>>>>> }
>>>>>>>>>>
>>>>>>>>>> In the above example, a new Employee instance will be created
>>>>>>>>>> and the
>>>>>>>>>> values of the id and name attributes copied. The projects and
>>>>>>>>>> phoneNumbers collections are recreated and populated in the
>>>>>>>>>> copy. For
>>>>>>>>>> the entities within the new projects collection, the id
>>>>>>>>>> attributes are
>>>>>>>>>> copied and new Requirements objects created. Only the id
>>>>>>>>>> attribute of
>>>>>>>>>> the Requirement entity is copied. For the entities within the
>>>>>>>>>> new
>>>>>>>>>> phoneNumbers collection, only the number attribute is copied.
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>
>>>>>