Hello Steve,
Comments below:
--Gordon
On 31/01/2013 9:10 AM, Steve Ebersole wrote:
> Sorry for being dense about this (but honestly I have asked others in
> the group and they are just as confused by this graph stuff)...
>
> Can you explain the "multiple key subgraphs and multiple subgraphs can
> exist for any attribute" part?
Because for a polymorphic relationship there may be additional subgraphs
defined for a particular attribute to include attributes of the target's
subclass types. This functionality is the reason "type" is on Subgraph.
>
> An attribute would be something like the "customer" attribute on an
> Account entity. So we'd have EntityGraph<Account>, with
> AttributeNode<Customer> as part of that EntityGraph<Account>'s
> getAttributeNodes() collection. The mere presence of
> AttributeNode<Customer> would indicate that Account.customer is
> supposed to be fetched, yes?
Yes
>
> As I understood it from yesterday's replies from yourself and Linda
> the intent in the above case would be that Account.customer could be
> represented by either AttributeNode<Customer> or Subgraph<Customer>
> depending on whether the user intended to further qualify the fetch
> graph "below" Customer.
Yes, in order to keep the interface model as simple as possible.
> Your new suggestion seems to indicate a fundamentally different view
> of this. Now, an attribute reference is aways going to be an
> AttributeNode. Under that we'd just have further possible
> qualifications of that fetch subgraph. Yes? If so, OK I can buy that
> as an improvement (the old deal was VERY counter-intuitive IMHO).
Yes, the interfaces need to be expanded to capture the complicated
nature of the AttributeNode.
>
> Going back to the quote "multiple key subgraphs and multiple subgraphs
> can exist for any attribute", especially confusing to me is the
> "multiple key subgraphs" portion. How can an attribute (a
> representation of the Map attribute) have multiple subgraphs *at that
> level* representing the map key? There is something fundamental I am
> missing here...
See first comment. It is because entity graphs support subclass
specific definitions for each type within a polymorphic attribute.
>
>
> On 01/30/2013 02:51 PM, Gordon Yorke wrote:
>> The issue is multiple key subgraphs and multiple subgraphs can exist
>> for any attribute. If we do not organize the subgraphs under an
>> AttributeNode just like the annotations are structured it gets very
>> difficult to convey the contents of an entity graph to a user in a
>> manageable way. if we were to add getKeySubgraphs to EntityManager
>> the return would have to be List<Map<Class,Subgraph>> at the least.
>> Any other structure(ie. List<Subgraph>) and the user would need to
>> organize the results to make the information meaningful. Also if
>> get*Subgraphs methods were added to the EntityGraph the user would
>> need to check all three collections to determine what attributes were
>> present in the entity graph.
>> --Gordon
>>
>> On 30/01/2013 3:02 PM, Steve Ebersole wrote:
>>> Oh, I misunderstood. I thought you were suggesting that
>>> getSubgraphs and getKeySubgraphs would become part of EntityGraph
>>> and Subgraph. Putting them on AttributeNode does not make sense to
>>> me. At least not as I was understanding the intention/breakdown
>>> between AttributeNode and Subgraph from your and Linda's replies
>>> from yesterday.
>>>
>>>
>>> On Wed 30 Jan 2013 01:29:17 PM CST, 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.
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>
>>>>
>>
>