View Javadoc

1   /*
2    * Copyright 2005 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at 
7    * 
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software 
11   * distributed under the License is distributed on an "AS IS" BASIS, 
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
13   * See the License for the specific language governing permissions and 
14   * limitations under the License.
15   */
16  
17  /*
18   * FetchPlan.java
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