Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Relationship Mappings/Common Relationship Configurations/JoinFetch"

m
m
Line 1: Line 1:
−
{{EclipseLink_UserGuide|toc=y|api=y
+
{{EclipseLink_UserGuide|toc=y|api=n
 
|1=javax.persitence.FetchType
 
|1=javax.persitence.FetchType
 
}}
 
}}
Line 7: Line 7:
 
You are not required to provide value for this attribute.
 
You are not required to provide value for this attribute.
  
−
==How to Configure Default Fetch Group Behavior==
+
==How to Use the @JoinFetch Annotation==
−
You can optionally designate at most one fetch group as the default fetch group for a descriptor's reference class.
+
  
−
If you execute a <tt>ReadObjectQuery</tt> or <tt>ReadAllQuery</tt> without specifying a fetch group, EclipseLink will use the default fetch group unless you configure the query otherwise, as this example shows.
+
You can specify the <tt>@JoinFetch</tt> annotation for the following mappings:
  
−
 
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@OneToOne|@OneToOne]]</tt>
−
<span id="Example 107-3"></span>
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@OneToMany|@OneToMany]]</tt>
−
''''' Configuring Default Fetch Group Behavior'''''
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@ManyToOne|@ManyToOne]]</tt>
−
<source lang="java">
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@ManyToMany|@ManyToMany]]</tt>
−
// at the descriptor level
+
* <tt>[[#How to Use the @BasicCollection Annotation|@BasicCollection]]</tt>
−
FetchGroup group = new FetchGroup("nameOnly");
+
* <tt>[[#How to Use the @BasicMap Annotation|@BasicMap]]</tt>
−
group.addAttribute("firstName");
+
−
group.addAttribute("lastName");
+
−
employeeDescriptor.getFetchGroupManager().addFetchGroup(group);
+
−
// set the default fetch group'''
+
−
employeeDescriptor.getFetchGroupManager().setDefaultFetchGroup(group);
+
−
+
−
// when query1 is executed, the default fetch group applies
+
−
ReadAllQuery query1 = new ReadAllQuery(Employee.class);
+
−
+
−
// when query2 is executed, the default fetch group does not apply
+
−
ReadAllQuery query2 = new ReadAllQuery(Employee.class);
+
−
query2.setShouldUsedefaultFetchGroup(false);
+
−
</source>
+
−
 
+
−
==How to Query with a Static Fetch Group==
+
−
 
+
−
[[#Example 107-4|Configuring a Query with a FetchGroup Using the FetchGroupManager]] shows how to configure a <tt>ReadObjectQuery</tt> for the <tt>Employee</tt> class with a <tt>FetchGroup</tt> named <tt>nameOnly</tt> previously stored in the <tt>FetchGroupManager</tt> owned by the <tt>Employee</tt> class's descriptor.
+
−
 
+
−
 
+
−
<span id="'Example 107-4"></span>
+
−
''''' Configuring a Query with a FetchGroup Using the FetchGroupManager'''''
+
−
 
+
−
In this example, only the <tt>Employee</tt> attributes <tt>firstName</tt> and <tt>lastName</tt> are fetched. If you call the <tt>Employee</tt> method <tt>get</tt> for any other attribute, EclipseLink executes another query to retrieve all unfetched attribute values. Thereafter, calling that <tt>get</tt> method will return the value directly from the object.
+
  
 
<source lang="java">  
 
<source lang="java">  
−
  // create static fetch group at the descriptor level
+
  @Target({METHOD, FIELD})
−
FetchGroup group = new FetchGroup("nameOnly");
+
  @Retention(RUNTIME)
−
  group.addAttribute("firstName");
+
  public @interface JoinFetch {
−
  group.addAttribute("lastName");
+
    JoinFetchType value() default JoinFetchType.INNER;
−
descriptor.getFetchGroupManager().addFetchGroup(group);
+
  }
−
   
+
−
// use static fetch group at query level
+
−
ReadAllQuery query = new ReadAllQuery(Employee.class);
+
−
query.setFetchGroupName("nameOnly");
+
 
</source>
 
</source>
 +
Using the <tt>@JoinFetch</tt> annotation, you can enable the joining and reading of the related objects in the same query as the source object.
 +
{{EclipseLink_Note
 +
|note=We recommend setting join fetching at the query level, as not all queries require joining. For more information, see [[Using%20Basic%20Query%20API%20(ELUG)#Using Join Reading with ObjectLevelReadQuery|Using Join Reading with ObjectLevelReadQuery]].
 +
}}
  
−
==How to Query with a Dynamic Fetch Group==
+
Alternatively, you can use batch reading, especially for collection relationships. For more information, see [[Using%20Basic%20Query%20API%20(ELUG)#Using_Batch_Reading|Using Batch Reading]].
  
−
[[#Example 107-5|Configuring a Query with a FetchGroup Dynamically]] shows how to create a <tt>FetchGroup</tt> instance dynamically, at the time you create and execute a query, and configure the query with that <tt>FetchGroup</tt> directly.
+
{{EclipseLink_AttributeTable
 +
|caption=<span id="Table 19-4">This table lists attributes of the <tt>@JoinFetch</tt> annotation.</span>
 +
|content=<tr>
 +
<td>'''<tt>value</tt>'''</td>
 +
<td>Set this attribute to the <tt>org.eclipse.persistence.annotations.JoinFetchType</tt> enumerated type of the fetch that you will be using.
  
−
In this example, only the <tt>firstName</tt>, <tt>lastName</tt>, and <tt>salary</tt> attributes are fetched. If you call the <tt>Employee</tt> method <tt>get</tt> for any other attribute, EclipseLink executes another query to retrieve all unfetched attribute values. Thereafter, calling that <tt>get</tt> method will return the value directly from the object.
+
The following are the valid values for the <tt>JoinFetchType</tt><nowiki>:</nowiki>
 +
* <tt>INNER</tt> – This option provides the inner join fetching of the related object.<br>Note: Inner joining does not allow for null or empty values.
 +
* <tt>OUTER</tt> – This option provides the outer join fetching of the related object.<br>Note: Outer joining allows for null or empty values.<br>
  
 +
For more information, see the following:
 +
* [[Introduction%20to%20EclipseLink%20Expressions%20(ELUG)#What You May Need to Know About Joins|What You May Need to Know About Joins]]
 +
* [[Using%20Basic%20Query%20API%20(ELUG)#Using Join Reading with ObjectLevelReadQuery|Using Join Reading with ObjectLevelReadQuery]]
 +
* [[Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring Joining at the Mapping Level|Configuring Joining at the Mapping Level]]
 +
</td>
 +
<td><tt>JoinFetchType.INNER</tt></td>
 +
<td>No</td>
 +
</tr>
 +
}}
  
−
<span id="Example 107-5"></span>
+
This example shows how to use the <tt>@JoinFetch</tt> annotation to specify <tt>Employee</tt> field <tt>managedEmployees</tt>.
−
''''' Configuring a Query with a FetchGroup Dynamically'''''
+
  
 +
<span id="Example 19-5"></span>
 +
''''' Usage of the @JoinFetch Annotation'''''
 
<source lang="java">
 
<source lang="java">
−
  // dynamic fetch group query
+
  @Entity
−
  ReadAllQuery query = new ReadAllQuery(Employee.class);
+
  public class Employee implements Serializable {
−
FetchGroup group = new FetchGroup("nameAndSalary");
+
    ...
−
group.addAttribute("firstName");
+
    @OneToMany(cascade=ALL, mappedBy="owner")
−
group.addAttribute("lastName");
+
    @JoinFetch(value=OUTER)
−
group.addAttribute("salary");
+
    public Collection<Employee> getManagedEmployees() {
−
  query. setFetchGroup(group);
+
        return managedEmployees;
 +
    }
 +
    ...
 +
  }
 
</source>
 
</source>
 +
  
  

Revision as of 10:04, 21 June 2010



Fetch Type

By default, EclipseLink persistence provider uses a fetch type of javax.persitence.FetchType.EAGER: this is a requirement on the persistence provider runtime that data must be eagerly fetched.If the default is inappropriate for your application or a particular persistent field, set fetch to FetchType.LAZY: this is a hint to the persistence provider that data should be fetched lazily when it is first accessed (if possible). We recommend using the FetchType.LAZY on all relationships.

You are not required to provide value for this attribute.

How to Use the @JoinFetch Annotation

You can specify the @JoinFetch annotation for the following mappings: 

 
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface JoinFetch {
    JoinFetchType value() default JoinFetchType.INNER;
 }

Using the @JoinFetch annotation, you can enable the joining and reading of the related objects in the same query as the source object.

Elug note icon.png

Note: We recommend setting join fetching at the query level, as not all queries require joining. For more information, see Using Join Reading with ObjectLevelReadQuery.

Alternatively, you can use batch reading, especially for collection relationships. For more information, see Using Batch Reading.

This table lists attributes of the @JoinFetch annotation.
Attribute Description Default Required?
value Set this attribute to the org.eclipse.persistence.annotations.JoinFetchType enumerated type of the fetch that you will be using.

The following are the valid values for the JoinFetchType:

  • INNER – This option provides the inner join fetching of the related object.
    Note: Inner joining does not allow for null or empty values.
  • OUTER – This option provides the outer join fetching of the related object.
    Note: Outer joining allows for null or empty values.

For more information, see the following:

JoinFetchType.INNER No

This example shows how to use the @JoinFetch annotation to specify Employee field managedEmployees.

Usage of the @JoinFetch Annotation 

 @Entity
 public class Employee implements Serializable {
     ...
     @OneToMany(cascade=ALL, mappedBy="owner")
     @JoinFetch(value=OUTER)
     public Collection<Employee> getManagedEmployees() {
         return managedEmployees;
     }
     ...
 }


Eclipselink-logo.gif
Version: 2.1.0
Other versions...

Retrieved from "https://wiki.eclipse.org/index.php?title=EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Relationship_Mappings/Common_Relationship_Configurations/JoinFetch&oldid=207960"

Copyright © Eclipse Foundation, Inc. All Rights Reserved.