FetchPlan


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 #addGroup}, {@link #removeGroup}, and the
59       * various {@link #setGroups} calls. Value: <code>values</code>.
60       * @since 2.0
61       */
62      public static final String   VALUES = "values";
63  
64      /**
65       * For use with {@link #addGroup}, {@link #removeGroup}, and the
66       * various {@link #setGroups} calls. Value: <code>none</code>.
67       * ### this is not mentioned in 12.7.2. It is referred to in 12.7's text.
68       * @since 2.0
69       */
70      public static final String   NONE = "none";
71  
72      /**
73       * For use with {@link #setFetchSize}. Value: -1.
74       * @since 2.0
75       */
76      public static final int FETCH_SIZE_GREEDY = -1;
77  
78      /**
79       * For use with {@link #setFetchSize}. Value: 0.
80       * @since 2.0
81       */
82      public static final int FETCH_SIZE_OPTIMAL = 0;
83  
84      /** 
85       * Add the fetch group to the set of active fetch groups.
86       * @return the FetchPlan
87       * @since 2.0
88       */
89      FetchPlan addGroup(String   fetchGroupName);
90  
91      /** 
92       * Remove the fetch group from the set active fetch groups. 
93       * @return the FetchPlan
94       * @since 2.0
95       */
96      FetchPlan removeGroup(String   fetchGroupName);
97  
98      /** 
99       * Remove all active groups leaving no active fetch group.
100      * @return the FetchPlan
101      * @since 2.0
102      */ 
103     FetchPlan clearGroups();
104 
105     /** 
106      * Return the names of all active fetch groups.
107      * @return the names of active fetch groups
108      * @return the FetchPlan
109      * @since 2.0
110      */
111     Collection   getGroups();
112 
113     /** 
114      * Set a collection of groups.
115      * @param fetchGroupNames a collection of names of fetch groups
116      * @return the FetchPlan
117      * @since 2.0
118      */
119     FetchPlan setGroups(Collection   fetchGroupNames);
120 
121     /** 
122      * Set a collection of groups.
123      * @param fetchGroupNames a String array of names of fetch groups
124      * @return the FetchPlan
125      * @since 2.0
126      */
127     FetchPlan setGroups(String  []fetchGroupNames);
128 
129     /** 
130      * Set the active fetch groups to the single named fetch group.
131      * @param fetchGroupName the single fetch group
132      * @return the FetchPlan
133      * @since 2.0
134      */
135     FetchPlan setGroup(String   fetchGroupName);
136 
137     /**
138      * Set the fetch size for large result set support. Use
139      * {@link #FETCH_SIZE_OPTIMAL} to unset, and {@link #FETCH_SIZE_GREEDY}
140      * to force loading of everything.
141      * @param fetchSize the fetch size
142      * @return the FetchPlan
143      * @since 2.0
144      */
145     FetchPlan setFetchSize(int fetchSize);
146 
147     /**
148      * Return the fetch size, or {@link #FETCH_SIZE_OPTIMAL} if not set,
149      * or {@link #FETCH_SIZE_GREEDY} to fetch all.
150      * @return the fetch size
151      * @since 2.0
152      */
153     int getFetchSize(); 
154 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags