1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23 package javax.jdo;
24
25 import java.util.Collection;
26 import java.util.Set;
27
28 /**
29 * Fetch groups are activated using methods on this interface. An
30 * instance of this interface can be obtained from {@link
31 * PersistenceManager#getFetchPlan}, {@link Extent#getFetchPlan}, and
32 * {@link Query#getFetchPlan}. When a <code>Query</code> or
33 * <code>Extent</code> is retrieved from a
34 * <code>PersistenceManager</code>, its <code>FetchPlan</code> is
35 * initialized to the same settings as that of the
36 * <code>PersistenceManager</code>. Subsequent modifications of the
37 * <code>Query</code> or <code>Extent</code>'s <code>FetchPlan</code>
38 * are not reflected in the <code>FetchPlan</code> of the
39 * <code>PersistenceManager</code>.
40 * @version 2.0
41 * @since 2.0
42 */
43 public interface FetchPlan {
44
45 /**
46 * For use with {@link #addGroup}, {@link #removeGroup}, and the
47 * various {@link #setGroups} calls. Value: <code>default</code>.
48 * @since 2.0
49 */
50 public static final String DEFAULT = "default";
51
52 /**
53 * For use with {@link #addGroup}, {@link #removeGroup}, and the
54 * various {@link #setGroups} calls. Value: <code>all</code>.
55 * @since 2.0
56 */
57 public static final String ALL = "all";
58
59 /**
60 * For use with {@link PersistenceManager#detachCopy} and
61 * {@link #setDetachmentOptions}. Specifies that
62 * fields that are loaded but not in the current fetch plan should
63 * be unloaded prior to detachment.
64 * @since 2.0
65 */
66 public static final int DETACH_UNLOAD_FIELDS = 2;
67
68 /**
69 * For use with {@link PersistenceManager#detachCopy} and
70 * {@link #setDetachmentOptions}. Specifies that
71 * fields that are not loaded but are in the current fetch plan should
72 * be loaded prior to detachment.
73 * @since 2.0
74 */
75 public static final int DETACH_LOAD_FIELDS = 1;
76
77 /**
78 * For use with {@link #setFetchSize}. Value: -1.
79 * @since 2.0
80 */
81 public static final int FETCH_SIZE_GREEDY = -1;
82
83 /**
84 * For use with {@link #setFetchSize}. Value: 0.
85 * @since 2.0
86 */
87 public static final int FETCH_SIZE_OPTIMAL = 0;
88
89 /**
90 * Add the fetch group to the set of active fetch groups.
91 * @return the FetchPlan
92 * @since 2.0
93 */
94 FetchPlan addGroup(String fetchGroupName);
95
96 /**
97 * Remove the fetch group from the set active fetch groups.
98 * @return the FetchPlan
99 * @since 2.0
100 */
101 FetchPlan removeGroup(String fetchGroupName);
102
103 /**
104 * Remove all active groups leaving no active fetch group.
105 * @return the FetchPlan
106 * @since 2.0
107 */
108 FetchPlan clearGroups();
109
110 /**
111 * Return an immutable Set containing the names
112 * of all active fetch groups. The Set is a copy of
113 * the currently active groups and will not change
114 * based on subsequent changes to the groups.
115 * @return an immutable Set containing the names
116 * of all currently active fetch groups
117 * @since 2.0
118 */
119 Set getGroups();
120
121 /**
122 * Set a collection of groups.
123 * @param fetchGroupNames a collection of names of fetch groups
124 * @return the FetchPlan
125 * @since 2.0
126 */
127 FetchPlan setGroups(Collection fetchGroupNames);
128
129 /**
130 * Set a collection of groups.
131 * @param fetchGroupNames a String array of names of fetch groups
132 * @return the FetchPlan
133 * @since 2.0
134 */
135 FetchPlan setGroups(String... fetchGroupNames);
136
137 /**
138 * Set the active fetch groups to the single named fetch group.
139 * @param fetchGroupName the single fetch group
140 * @return the FetchPlan
141 * @since 2.0
142 */
143 FetchPlan setGroup(String fetchGroupName);
144
145 /**
146 * Set the maximum fetch depth when fetching.
147 * A value of 0 has no meaning and will throw a JDOUserException.
148 * A value of -1 means that no limit is placed on fetching.
149 * A positive integer will result in that number of references from the
150 * initial object to be fetched.
151 * @param fetchDepth the depth
152 * @return the FetchPlan
153 * @since 2.0
154 */
155 FetchPlan setMaxFetchDepth(int fetchDepth);
156
157 /**
158 * Return the maximum fetch depth used when fetching instances.
159 * @return the maximum fetch depth
160 * @since 2.0
161 */
162 int getMaxFetchDepth();
163
164 /**
165 * Set the roots for DetachAllOnCommit.
166 * @param roots Collection of the detachment roots.
167 * @since 2.0
168 */
169 FetchPlan setDetachmentRoots(Collection roots);
170
171 /**
172 * Get the roots for DetachAllOnCommit.
173 * @return Collection of detachment roots.
174 * @since 2.0
175 */
176 Collection getDetachmentRoots();
177
178 /**
179 * Set the root classes for DetachAllOnCommit.
180 * @param rootClasses The root classes.
181 * @since 2.0
182 */
183 FetchPlan setDetachmentRootClasses(Class... rootClasses);
184
185 /**
186 * Get the root classes for DetachAllOnCommit.
187 * @return The detachment root classes
188 * @since 2.0
189 */
190 Class[] getDetachmentRootClasses();
191
192 /**
193 * Set the fetch size for large result set support. Use
194 * {@link #FETCH_SIZE_OPTIMAL} to unset, and {@link #FETCH_SIZE_GREEDY}
195 * to force loading of everything.
196 * @param fetchSize the fetch size
197 * @return the FetchPlan
198 * @since 2.0
199 */
200 FetchPlan setFetchSize(int fetchSize);
201
202 /**
203 * Return the fetch size, or {@link #FETCH_SIZE_OPTIMAL} if not set,
204 * or {@link #FETCH_SIZE_GREEDY} to fetch all.
205 * @return the fetch size
206 * @since 2.0
207 */
208 int getFetchSize();
209
210 /**
211 * Set options to be used during detachment. Options are {@link
212 * #DETACH_LOAD_FIELDS} and {@link #DETACH_UNLOAD_FIELDS}.
213 */
214 FetchPlan setDetachmentOptions(int options);
215
216 /**
217 * Get options used during detachment.
218 */
219 int getDetachmentOptions();
220
221 }
222