Difference between revisions of "EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Relationship Mappings/Collection Mappings/ManyToMany"

From Eclipsepedia

Jump to: navigation, search
m
(Example: @ManyToMany Annotation - Project Class with Generics)
 
(22 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{EclipseLink_UserGuide|info=y}}
+
{{EclipseLink_UserGuide
=ManyToMany=
+
|info=y
 +
|toc=n
 +
|eclipselink=y
 +
|eclipselinktype=JPA
 +
|api=y
 +
|apis=
 +
*[http://www.eclipse.org/eclipselink/api/latest/javax/persistence/ManyToMany.html @ManyToMany]
 +
| examples=y
 +
|example=
 +
*[[EclipseLink/Examples/JPA/MappingSelectionCriteria|Mapping with Selection Criteria]]
 +
}}
 +
=Many-to-Many Mapping=
 +
Many-to-many mappings represent the relationships between a collection of source objects and a collection of target objects. They require the creation of an intermediate table for managing the associations between the source and target records.
 +
 
 +
This figure illustrates a many-to-many mapping in Java and in relational database tables.
 +
 
 +
 
 +
<span id="Figure 32-5"></span>
 +
''''' Many-to-many Relationships'''''
 +
 
 +
[[Image:mmmapfig.gif|Many-to-many Relationships]]
 +
 
 +
{{EclipseLink_Note
 +
|note=For the <tt>projects</tt> attribute shown in the [[#Figure 32-5|Many-to-many Relationships]] you can use a <tt>Collection</tt> interface (or any class that implements the <tt>Collection</tt> interface) for declaring the collection attribute. }}
 +
 
 +
=JPA Mapping=
 
By default, JPA automatically defines a <tt>ManyToMany</tt> mapping for a many-valued association with many-to-many multiplicity.
 
By default, JPA automatically defines a <tt>ManyToMany</tt> mapping for a many-valued association with many-to-many multiplicity.
  
Line 9: Line 34:
 
* configure the operations that must be cascaded to the target of the association (for example, if the owning entity is removed, ensure that the target of the association is also removed).
 
* configure the operations that must be cascaded to the target of the association (for example, if the owning entity is removed, ensure that the target of the association is also removed).
  
The <tt>@ManyToMany</tt> annotation has the following attributes:
+
{{EclipseLink_AttributeTable
* <tt>cascade</tt> – By default, JPA does not cascade any persistence operations to the target of the association. Thus, the default value of this attribute is an empty <tt>javax.persitence.CascadeType</tt> array.<br>If you want some or all persistence operations cascaded to the target of the association, set the value of this attribute to one or more <tt>CascadeType</tt> instances, including the following:
+
|caption=@ManyToMany Annotation Attributes
** <tt>ALL</tt> – Any persistence operation performed on the owning entity is cascaded to the target of the association.
+
|content=<tr>
** <tt>MERGE</tt> – If the owning entity is merged, the merge is cascaded to the target of the association.
+
<td>'''<tt>cascade</tt>'''</td>
** <tt>PERSIST</tt> – If the owning entity is persisted, the persist is cascaded target of the association.
+
<td> – By default, JPA does not cascade any persistence operations to the target of the association.If you want some or all persistence operations cascaded to the target of the association, set the value of this attribute to one or more <tt>CascadeType</tt> instances, including the following:
** <tt>REFRESH</tt> – If the owning entity is refreshed, the refresh is cascaded target of the association.
+
* <tt>ALL</tt> – Any persistence operation performed on the owning entity is cascaded to the target of the association.
** <tt>REMOVE</tt> – If the owning entity is removed, the target of the association is also removed.<br><br>You are not required to provide value for this attribute.
+
* <tt>MERGE</tt> – If the owning entity is merged, the merge is cascaded to the target of the association.
* <tt>fetch</tt> – By default, EclipseLink persistence provider uses a [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Relationship_Mappings/Common_Relationship_Configurations/Fetch_Type|fetch type]] of <tt>javax.persitence.FetchType.LAZY</tt><nowiki>: this is a hint to the persistence provider that data should be fetched lazily when it is first accessed (if possible).</nowiki><br>If the default is inappropriate for your application or a particular persistent field, set <tt>fetch</tt> to <tt>FetchType.EAGER</tt><nowiki>: this is a requirement on the persistence provider runtime that data must be eagerly fetched.</nowiki><br><br>You are not required to provide value for this attribute.<br>For more information, see [[Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#What You May Need to Know About EclipseLink JPA Lazy Loading|What You May Need to Know About EclipseLink JPA Lazy Loading]].
+
* <tt>PERSIST</tt> – If the owning entity is persisted, the persist is cascaded target of the association.
* <tt>mappedBy</tt> By default, if the relationship is unidirectional, EclipseLink persistence provider determines the field that owns the relationship.<br>If the relationship is bidirectional, then set the <tt>mappedBy</tt> element on the inverse (non-owning) side of the association to the name of the field or property that owns the relationship, as the [[#Example 18-23|Usage of @ManyToMany Annotation - Project Class with Generics]] example shows.<br><br>You are not required to specify the value of this attribute.
+
* <tt>REFRESH</tt> – If the owning entity is refreshed, the refresh is cascaded target of the association.
* <tt>targetEntity</tt> By default, if you are using a <tt>Collection</tt> defined using generics, then the persistence provider infers the associated target entity from the type of the object being referenced. Thus, the default is the parameterized type of the <tt>Collection</tt> when defined using generics.<br>If your <tt>Collection</tt> does not use generics, then you must specify the entity class that is the target of the association: set the <tt>targetEntity</tt> element on owning side of the association to the <tt>Class</tt> of the entity that is the target of the relationship.<br><br>You are not required to specify the value of this attribute.
+
* <tt>REMOVE</tt> – If the owning entity is removed, the target of the association is also removed.</td>
 +
<td>An empty <tt>javax.persitence.CascadeType</tt> array</td>
 +
<td>No</td>
 +
</tr>
 +
<tr>
 +
<td>'''<tt>fetch</tt>'''</td>
 +
<td> – By default, EclipseLink persistence provider uses a [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Relationship_Mappings/Common_Relationship_Configurations/Fetch_Type|fetch type]] of <tt>javax.persitence.FetchType.LAZY</tt><nowiki>: this is a hint to the persistence provider that data should be fetched lazily when it is first accessed (if possible).</nowiki><br>If the default is inappropriate for your application or a particular persistent field, set <tt>fetch</tt> to <tt>FetchType.EAGER</tt><nowiki>: this is a requirement on the persistence provider runtime that data must be eagerly fetched.</nowiki>.</td>
 +
<td><tt>javax.persitence.FetchType.LAZY</tt></td>
 +
<td>No</td>
 +
</tr>
 +
<tr>
 +
<td>'''<tt>mappedBy</tt>'''</td>
 +
<td>By default, if the relationship is unidirectional, EclipseLink persistence provider determines the field that owns the relationship.<br>If the relationship is bidirectional, then set the <tt>mappedBy</tt> element on the inverse (non-owning) side of the association to the name of the field or property that owns the relationship, as the [[#@ManyToMany Annotation - Project Class with Generics|@ManyToMany Annotation - Project Class with Generics]] example shows.</td>
 +
<td></td>
 +
<td>No</td>
 +
</tr>
 +
<tr>
 +
<td>'''<tt>targetEntity</tt>'''</td>
 +
<td>By default, if you are using a <tt>Collection</tt> defined using generics, then the persistence provider infers the associated target entity from the type of the object being referenced. Thus, the default is the parameterized type of the <tt>Collection</tt> when defined using generics.<br>If your <tt>Collection</tt> does not use generics, then you must specify the entity class that is the target of the association: set the <tt>targetEntity</tt> element on owning side of the association to the <tt>Class</tt> of the entity that is the target of the relationship.</td>
 +
<td></td>
 +
<td>No</td>
 +
</tr>}}
  
The [[#Example 18-22|Usage of @ManyToMany Annotation - Employee Class with Generics]] and [[#Example 18-23|Usage of @ManyToMany Annotation - Project Class with Generics]] examples show how to use this annotation to configure a many-to-many mapping between <tt>Employee</tt> and <tt>Project</tt> using generics.
+
The [[#@ManyToMany Annotation - Employee Class with Generics|@ManyToMany Annotation - Employee Class with Generics]] example and the [[#@ManyToMany Annotation - Project Class with Generics|@ManyToMany Annotation - Project Class with Generics]] example show how to use this annotation to configure a many-to-many mapping between <tt>Employee</tt> and <tt>Project</tt> using generics.
  
  
<span id="Example 18-22"></span>
+
<span id="@ManyToMany Annotation - Employee Class with Generics"></span>
''''' Usage of @ManyToMany Annotation - Employee Class with Generics'''''
+
======''Example: @ManyToMany Annotation - Employee Class with Generics''======
 
<source lang="java">
 
<source lang="java">
 
  @Entity
 
  @Entity
Line 36: Line 82:
 
                       @JoinColumn(name="EMP_ID"),
 
                       @JoinColumn(name="EMP_ID"),
 
                 inverseJoinColumns=
 
                 inverseJoinColumns=
                       @JoinColumn(name="PROJ_ID)
+
                       @JoinColumn(name="PROJ_ID")
 
     )
 
     )
 
     private Collection<Project> projects;
 
     private Collection<Project> projects;
Line 46: Line 92:
 
|note=Use a <tt>@JoinTable</tt> annotation to define a many-to-many join table; if you do not specify this annotation, EclipseLink will default to <tt>@JoinTable</tt> with the join table name format of <tt><source-table-name>_<target-table-name></tt> in uppercase characters, and with columns format of <tt><source-entity-alias>_<source-primary-key-column></tt>, <tt><source-field-name>_ <target-primary-key-column></tt> (or <source-property-name>_ <target-primary-key-column>) in uppercase characters.
 
|note=Use a <tt>@JoinTable</tt> annotation to define a many-to-many join table; if you do not specify this annotation, EclipseLink will default to <tt>@JoinTable</tt> with the join table name format of <tt><source-table-name>_<target-table-name></tt> in uppercase characters, and with columns format of <tt><source-entity-alias>_<source-primary-key-column></tt>, <tt><source-field-name>_ <target-primary-key-column></tt> (or <source-property-name>_ <target-primary-key-column>) in uppercase characters.
  
{{EclipseLink_Spec|section=Section 9.1.25 "JoinTable Annotation"}}
+
{{EclipseLink_Spec|section=Section 11.1.23 "JoinTable Annotation"}}
 
}}
 
}}
  
 
<br>
 
<br>
  
<span id="Example 18-23"></span>
+
<span id="@ManyToMany Annotation - Project Class with Generics"></span>
''''' Usage of @ManyToMany Annotation - Project Class with Generics'''''
+
======''Example: @ManyToMany Annotation - Project Class with Generics''======
 
<source lang="java">
 
<source lang="java">
 
  @Entity
 
  @Entity
Line 65: Line 111:
 
</source>
 
</source>
  
{{EclipseLink_Spec|section=Section 9.1.26 "ManyToMany Annotation"}}
 
 
For more information on EclipseLink direct mappings and relationship mappings, see [[Introduction%20to%20Relational%20Mappings%20(ELUG)#Relational Mapping Types|Relational Mapping Types]].
 
 
For more information on EclipseLink one-to-one mappings, see [[Introduction%20to%20Relational%20Mappings%20(ELUG)#Many-to-Many Mapping|Many-to-Many Mapping]], and for information on how to configure these mappings, see [[Configuring a Relational Many-to-Many Mapping (ELUG)|Configuring a Relational Many-to-Many Mapping]].
 
  
 +
{{EclipseLink_Spec|section=Section 11.1.25 "ManyToMany Annotation"}}
  
 
{{EclipseLink_JPA
 
{{EclipseLink_JPA
|previous= [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Relationship_Mappings/Collection_Mappings/OneToMany|OneToMany]]
+
|previous= [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Relationship_Mappings/Collection_Mappings/OneToMany|One-to-Many Mapping]]
|next=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Locking|Locking]]
+
|next= [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Locking|Locking]]
|up=[[EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Relationship_Mappings/Collection Mappings|Collection Mappings]]}}
+
|up=[[EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Relationship_Mappings/Collection Mappings|Collection Mappings]]
 +
|version=2.2.0 DRAFT}}

Latest revision as of 11:13, 25 April 2012

EclipseLink JPA

link="http://wiki.eclipse.org/EclipseLink"
EclipseLink
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse Source

Elug api package icon.png Key API

[edit] Many-to-Many Mapping

Many-to-many mappings represent the relationships between a collection of source objects and a collection of target objects. They require the creation of an intermediate table for managing the associations between the source and target records.

This figure illustrates a many-to-many mapping in Java and in relational database tables.


Many-to-many Relationships

Many-to-many Relationships

Elug note icon.png

Note: For the projects attribute shown in the Many-to-many Relationships you can use a Collection interface (or any class that implements the Collection interface) for declaring the collection attribute.

[edit] JPA Mapping

By default, JPA automatically defines a ManyToMany mapping for a many-valued association with many-to-many multiplicity.

Use the @ManyToMany annotation to do the following:

  • configure the Fetch Type to EAGER;
  • configure the mapping to forbid null values (for nonprimitive types) in case null values are inappropriate for your application;
  • configure the associated target entity because the Collection used is not defined using generics;
  • configure the operations that must be cascaded to the target of the association (for example, if the owning entity is removed, ensure that the target of the association is also removed).
@ManyToMany Annotation Attributes
Attribute Description Default Required?
cascade – By default, JPA does not cascade any persistence operations to the target of the association.If you want some or all persistence operations cascaded to the target of the association, set the value of this attribute to one or more CascadeType instances, including the following:
  • ALL – Any persistence operation performed on the owning entity is cascaded to the target of the association.
  • MERGE – If the owning entity is merged, the merge is cascaded to the target of the association.
  • PERSIST – If the owning entity is persisted, the persist is cascaded target of the association.
  • REFRESH – If the owning entity is refreshed, the refresh is cascaded target of the association.
  • REMOVE – If the owning entity is removed, the target of the association is also removed.
An empty javax.persitence.CascadeType array No
fetch – By default, EclipseLink persistence provider uses a fetch type of javax.persitence.FetchType.LAZY: this is a hint to the persistence provider that data should be fetched lazily when it is first accessed (if possible).
If the default is inappropriate for your application or a particular persistent field, set fetch to FetchType.EAGER: this is a requirement on the persistence provider runtime that data must be eagerly fetched..
javax.persitence.FetchType.LAZY No
mappedBy By default, if the relationship is unidirectional, EclipseLink persistence provider determines the field that owns the relationship.
If the relationship is bidirectional, then set the mappedBy element on the inverse (non-owning) side of the association to the name of the field or property that owns the relationship, as the @ManyToMany Annotation - Project Class with Generics example shows.
No
targetEntity By default, if you are using a Collection defined using generics, then the persistence provider infers the associated target entity from the type of the object being referenced. Thus, the default is the parameterized type of the Collection when defined using generics.
If your Collection does not use generics, then you must specify the entity class that is the target of the association: set the targetEntity element on owning side of the association to the Class of the entity that is the target of the relationship.
No

The @ManyToMany Annotation - Employee Class with Generics example and the @ManyToMany Annotation - Project Class with Generics example show how to use this annotation to configure a many-to-many mapping between Employee and Project using generics.


[edit] Example: @ManyToMany Annotation - Employee Class with Generics
 @Entity
 public class Employee implements Serializable {
     @Id
     private int id;
     private String name;
     @ManyToMany
     @JoinTable(name="EMP_PROJ",
                 joinColumns=
                      @JoinColumn(name="EMP_ID"),
                 inverseJoinColumns=
                      @JoinColumn(name="PROJ_ID")
     )
     private Collection<Project> projects;
     ...
 }

Elug note icon.png

Note: Use a @JoinTable annotation to define a many-to-many join table; if you do not specify this annotation, EclipseLink will default to @JoinTable with the join table name format of <source-table-name>_<target-table-name> in uppercase characters, and with columns format of <source-entity-alias>_<source-primary-key-column>, <source-field-name>_ <target-primary-key-column> (or <source-property-name>_ <target-primary-key-column>) in uppercase characters.

Elug javaspec icon.gif

For more information, see Section 11.1.23 "JoinTable Annotation" in the JPA Specification.


[edit] Example: @ManyToMany Annotation - Project Class with Generics
 @Entity
 public class Project implements Serializable {
     ...
     @ManyToMany(mappedBy="projects")
     public Set<Employee> getEmployees() { 
         return employees;
     }
     ...
 }


Elug javaspec icon.gif

For more information, see Section 11.1.25 "ManyToMany Annotation" in the JPA Specification.

Eclipselink-logo.gif
Version: 2.2.0 DRAFT
Other versions...