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  
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