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