I never said to have a Map as the return type. I am talking about
internally (impl detail) using a Map. Honestly, to me the return ought
to be Collection<AttributeNode<?>> rather than List<AttributeNode<?>>
On Wed 30 Jan 2013 10:42:51 AM CST, Gordon Yorke wrote:
> The list order is undefined. Having a Map as the return type adds
> the complication of specifying a key as users of the untyped String
> API are not going to expect or want the keys to be Attribute types and
> vice versa for other users.
> --Gordon
>
> On 30/01/2013 9:51 AM, Steve Ebersole wrote:
>> In regards to getAttributeNodes returning a List, why a List exactly?
>> What is the intending ordering of this List? Insertion order?
>>
>> The reason I ask is that obviously the behavior you lay out
>> (replacing) would be most easily served by usnig a Map. But using a
>> Map for the storage makes it awkward for returning Lists. And
>> conversely using Lists for the storage makes it awkward to test for
>> the replacement condition. True, this is a implementation
>> detail/difficulty, but its caused by using a List in the API when I
>> am not sure that is necessary.
>>
>> On Wed 30 Jan 2013 08:46:05 AM CST, Steve Ebersole wrote:
>>> Based on on your responses then, I think its is much more feasible to
>>> include the 2 new methods (getSubgraphs and getKeySubgraphs) in
>>> addition to getAttributeNodes in this release then. Otherwise the
>>> API, IMHO is very confusing in this regard.
>>>
>>> Also, I'd like to suggest that this notion of "key subgraphs" be
>>> renamed to "map key subgraphs". I see key here and continually think
>>> of database keys (as in maybe references to composite primary key
>>> embeddables).
>>>
>>> On Wed 30 Jan 2013 08:32:04 AM CST, Gordon Yorke wrote:
>>>> Yes it should be allowed, the subsequent addition would replace the
>>>> existing definition. Otherwise there is no way for users to modify
>>>> existing entity graphs.
>>>> --Gordon
>>>>
>>>> On 29/01/2013 9:34 PM, Steve Ebersole wrote:
>>>>> Is adding the same attribute (by name) using both addAttributeNode
>>>>> and addSubgraph allowed?
>>>>>
>>>>> accountEntityGraph.addAttributeNode( "customer" );
>>>>> ...
>>>>> accountEntityGraph.addSubgraph( "customer" )...;
>>>>>
>>>>>
>>>>>
>>>>> On Tue 29 Jan 2013 07:30:58 PM CST, Linda DeMichiel wrote:
>>>>>>
>>>>>>
>>>>>> On 1/29/2013 2:42 PM, Steve Ebersole wrote:
>>>>>>> Also related... Do EntityGraph.getAttributeNodes /
>>>>>>> Subgraph.getAttributeNodes return Subgraphs in the AttributeNode
>>>>>>> list?
>>>>>>>
>>>>>>
>>>>>> Yes
>>>>>>
>>>>>>> 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.
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>
>