001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one
003: * or more contributor license agreements. See the NOTICE file
004: * distributed with this work for additional information
005: * regarding copyright ownership. The ASF licenses this file
006: * to you under the Apache License, Version 2.0 (the
007: * "License"); you may not use this file except in compliance
008: * with the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing,
013: * software distributed under the License is distributed on an
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015: * KIND, either express or implied. See the License for the
016: * specific language governing permissions and limitations
017: * under the License.
018: */
019: package org.apache.openjpa.persistence;
020:
021: import java.util.Collection;
022: import javax.persistence.LockModeType;
023:
024: import org.apache.openjpa.kernel.FetchConfiguration;
025: import org.apache.openjpa.meta.FetchGroup;
026:
027: /**
028: * The fetch plan allows you to dynamically alter eager fetching
029: * configuration and other aspects of data loading.
030: *
031: * @author Abe White
032: * @author Pinaki Poddar
033: * @since 0.4.1
034: * @published
035: */
036: public interface FetchPlan {
037:
038: /**
039: * Fetch group representing all fields.
040: */
041: public static final String GROUP_ALL = FetchGroup.NAME_ALL;
042:
043: /**
044: * The default fetch group.
045: */
046: public static final String GROUP_DEFAULT = FetchGroup.NAME_DEFAULT;
047:
048: /**
049: * Infinite fetch depth.
050: */
051: public static final int DEPTH_INFINITE = FetchGroup.DEPTH_INFINITE;
052:
053: /**
054: * Constant to revert any setting to its default value.
055: */
056: public static final int DEFAULT = FetchConfiguration.DEFAULT;
057:
058: /**
059: * The maximum fetch depth when loading an object.
060: */
061: public int getMaxFetchDepth();
062:
063: /**
064: * The maximum fetch depth when loading an object.
065: */
066: public FetchPlan setMaxFetchDepth(int depth);
067:
068: /**
069: * Return the fetch batch size for large result set support.
070: * Defaults to the <code>openjpa.FetchBatchSize</code> setting. Note
071: * that this property will be ignored under some data stores.
072: */
073: public int getFetchBatchSize();
074:
075: /**
076: * Set the fetch batch size for large result set support.
077: * Defaults to the <code>openjpa.FetchBatchSize</code> setting. Note
078: * that this property will be ignored under some data stores.
079: */
080: public FetchPlan setFetchBatchSize(int fetchBatchSize);
081:
082: /**
083: * Return whether or not query caching is enabled. If this returns
084: * <code>true</code> but the datacache plugin is not installed, caching
085: * will not be enabled. If this
086: * returns <code>false</code>, query caching will not be used
087: * even if the datacache plugin is installed.
088: *
089: * @since 1.0.0
090: */
091: public boolean getQueryResultCacheEnabled();
092:
093: /**
094: * Control whether or not query caching is enabled. This has no effect
095: * if the datacache plugin is not installed, or if the query cache size
096: * is set to zero.
097: *
098: * @since 1.0.0
099: */
100: public FetchPlan setQueryResultCacheEnabled(boolean cache);
101:
102: /**
103: * @deprecated use {@link #getQueryResultCacheEnabled()} instead.
104: */
105: public boolean getQueryResultCache();
106:
107: /**
108: * @deprecated use {@link #setQueryResultCacheEnabled} instead.
109: */
110: public FetchPlan setQueryResultCache(boolean cache);
111:
112: /**
113: * Returns the names of the fetch groups that this component will use
114: * when loading objects. Defaults to the
115: * <code>openjpa.FetchGroups</code> setting.
116: */
117: public Collection<String> getFetchGroups();
118:
119: /**
120: * Adds <code>group</code> to the set of fetch group to
121: * use when loading objects.
122: */
123: public FetchPlan addFetchGroup(String group);
124:
125: /**
126: * Adds <code>groups</code> to the set of fetch group names to
127: * use when loading objects.
128: */
129: public FetchPlan addFetchGroups(String... groups);
130:
131: /**
132: * Adds <code>groups</code> to the set of fetch group names to
133: * use when loading objects.
134: */
135: public FetchPlan addFetchGroups(Collection groups);
136:
137: /**
138: * Remove the given fetch group.
139: */
140: public FetchPlan removeFetchGroup(String group);
141:
142: /**
143: * Removes <code>groups</code> from the set of fetch group names
144: * to use when loading objects.
145: */
146: public FetchPlan removeFetchGroups(String... groups);
147:
148: /**
149: * Removes <code>groups</code> from the set of fetch group names
150: * to use when loading objects.
151: */
152: public FetchPlan removeFetchGroups(Collection groups);
153:
154: /**
155: * Clears the set of fetch group names to use wen loading
156: * data. After this operation is invoked, only those fields in
157: * the default fetch group (and any requested field) will be
158: * loaded when loading an object.
159: */
160: public FetchPlan clearFetchGroups();
161:
162: /**
163: * Resets the set of fetch groups to the list in the global configuration.
164: */
165: public FetchPlan resetFetchGroups();
166:
167: /**
168: * Returns the fully qualified names of the fields that this component
169: * will use when loading objects. Defaults to the empty set.
170: */
171: public Collection<String> getFields();
172:
173: /**
174: * Return true if the given field has been added.
175: */
176: public boolean hasField(String field);
177:
178: /**
179: * Return true if the given field has been added.
180: */
181: public boolean hasField(Class cls, String field);
182:
183: /**
184: * Adds <code>field</code> to the set of fully-qualified field names to
185: * use when loading objects.
186: */
187: public FetchPlan addField(String field);
188:
189: /**
190: * Adds <code>field</code> to the set of field names to
191: * use when loading objects.
192: */
193: public FetchPlan addField(Class cls, String field);
194:
195: /**
196: * Adds <code>fields</code> to the set of fully-qualified field names to
197: * use when loading objects.
198: */
199: public FetchPlan addFields(String... fields);
200:
201: /**
202: * Adds <code>fields</code> to the set of field names to
203: * use when loading objects.
204: */
205: public FetchPlan addFields(Class cls, String... fields);
206:
207: /**
208: * Adds <code>fields</code> to the set of fully-qualified field names to
209: * use when loading objects.
210: */
211: public FetchPlan addFields(Collection fields);
212:
213: /**
214: * Adds <code>fields</code> to the set of field names to
215: * use when loading objects.
216: */
217: public FetchPlan addFields(Class cls, Collection fields);
218:
219: /**
220: * Remove the given fully-qualified field.
221: */
222: public FetchPlan removeField(String field);
223:
224: /**
225: * Remove the given field.
226: */
227: public FetchPlan removeField(Class cls, String field);
228:
229: /**
230: * Removes <code>fields</code> from the set of fully-qualified field names
231: * to use when loading objects.
232: */
233: public FetchPlan removeFields(String... fields);
234:
235: /**
236: * Removes <code>fields</code> from the set of field names
237: * to use when loading objects.
238: */
239: public FetchPlan removeFields(Class cls, String... fields);
240:
241: /**
242: * Removes <code>fields</code> from the set of fully-qualified field names
243: * to use when loading objects.
244: */
245: public FetchPlan removeFields(Collection fields);
246:
247: /**
248: * Removes <code>fields</code> from the set of field names
249: * to use when loading objects.
250: */
251: public FetchPlan removeFields(Class cls, Collection fields);
252:
253: /**
254: * Clears the set of field names to use wen loading
255: * data. After this operation is invoked, only those fields in
256: * the configured fetch groups will be loaded when loading an object.
257: */
258: public FetchPlan clearFields();
259:
260: /**
261: * The number of milliseconds to wait for an object lock, or -1 for no
262: * limit.
263: */
264: public int getLockTimeout();
265:
266: /**
267: * The number of milliseconds to wait for an object lock, or -1 for no
268: * limit.
269: */
270: public FetchPlan setLockTimeout(int timeout);
271:
272: /**
273: * The lock level to use for locking loaded objects.
274: */
275: public LockModeType getReadLockMode();
276:
277: /**
278: * The lock level to use for locking loaded objects.
279: */
280: public FetchPlan setReadLockMode(LockModeType mode);
281:
282: /**
283: * The lock level to use for locking dirtied objects.
284: */
285: public LockModeType getWriteLockMode();
286:
287: /**
288: * The lock level to use for locking dirtied objects.
289: */
290: public FetchPlan setWriteLockMode(LockModeType mode);
291:
292: /**
293: * @deprecated cast to {@link FetchPlanImpl} instead. This
294: * method pierces the published-API boundary, as does the SPI cast.
295: */
296: public org.apache.openjpa.kernel.FetchConfiguration getDelegate();
297: }
|