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