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.
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>