View Javadoc

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