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.kernel;
020:
021: import java.io.Serializable;
022: import java.util.Collection;
023: import java.util.Set;
024:
025: import org.apache.openjpa.lib.rop.ResultList;
026: import org.apache.openjpa.lib.rop.ResultObjectProvider;
027: import org.apache.openjpa.meta.FieldMetaData;
028:
029: /**
030: * Allows configuration and optimization of how objects are loaded from
031: * the data store.
032: *
033: * @since 0.3.0
034: * @author Abe White
035: * @author Pinaki Poddar
036: */
037: public interface FetchConfiguration extends Serializable, Cloneable,
038: LockLevels, QueryFlushModes {
039:
040: /**
041: * Constant to revert any setting back to its default value.
042: */
043: public static final int DEFAULT = -99;
044:
045: /**
046: * Constant indicating that a field does not require fetching.
047: *
048: * @see #requiresFetch
049: */
050: public static final int FETCH_NONE = 0;
051:
052: /**
053: * Constant indicating that a field requires a fetch and load of fetched
054: * data.
055: *
056: * @see #requiresFetch
057: */
058: public static final int FETCH_LOAD = 1;
059:
060: /**
061: * Constant indicating that a reference to the field's value must be
062: * fetched, but loading data is not necessary. Used when we know the
063: * data will be loaded anyway, such as when traversing the back-ptr of
064: * a bidirectional relation where the other side is also being fetched.
065: *
066: * @see #requiresFetch
067: */
068: public static final int FETCH_REF = 2;
069:
070: /**
071: * Return the context assiciated with this configuration;
072: * may be null if it has not been set or this object has been serialized.
073: */
074: public StoreContext getContext();
075:
076: /**
077: * Called automatically by the system to associate the fetch configuration
078: * with a context before use. The fetch configuration properties should
079: * be synchronized with the context's configuration object. Subclasses
080: * for specific back ends cannot rely on the context's configuration
081: * implementing their back end's configuration sub-interface.
082: */
083: public void setContext(StoreContext ctx);
084:
085: /**
086: * Clone this instance.
087: */
088: public Object clone();
089:
090: /**
091: * Copy the state from the given fetch configuration to this one.
092: */
093: public void copy(FetchConfiguration fetch);
094:
095: /**
096: * Return the fetch batch size for large result set support.
097: * Defaults to the <code>openjpa.FetchBatchSize</code> setting. Note
098: * that this property will be ignored under some data stores.
099: */
100: public int getFetchBatchSize();
101:
102: /**
103: * Set the fetch batch size for large result set support.
104: * Defaults to the <code>openjpa.FetchBatchSize</code> setting. Note
105: * that this property will be ignored under some data stores.
106: */
107: public FetchConfiguration setFetchBatchSize(int fetchBatchSize);
108:
109: /**
110: * Return the maximum depth of fetched instance graph.
111: * Defaults to <code>1</code>
112: */
113: public int getMaxFetchDepth();
114:
115: /**
116: * Set the maximum depth of the fetched instance graph.
117: *
118: * @param max denotes limiting length of traversal path from a root
119: * instance. <code>-1</code> implies no limit. <code>0</code> is not
120: * permissible.
121: */
122: public FetchConfiguration setMaxFetchDepth(int max);
123:
124: /**
125: * Return whether or not query caching is enabled. If this returns
126: * <code>true</code> but the datacache plugin is not installed, caching
127: * will not be enabled. If this
128: * returns <code>false</code>, query caching will not be used
129: * even if the datacache plugin is installed.
130: */
131: public boolean getQueryCacheEnabled();
132:
133: /**
134: * Control whether or not query caching is enabled. This has no effect
135: * if the datacache plugin is not installed, or if the query cache size
136: * is set to zero.
137: */
138: public FetchConfiguration setQueryCacheEnabled(boolean cache);
139:
140: /**
141: * The query automatic flush configuration.
142: */
143: public int getFlushBeforeQueries();
144:
145: /**
146: * The query automatic flush configuration.
147: */
148: public FetchConfiguration setFlushBeforeQueries(int flush);
149:
150: /**
151: * Returns immutable set of names of the fetch groups that this component
152: * will use when loading objects. Defaults to the
153: * <code>openjpa.FetchGroups</code> setting. This set is not thread safe.
154: */
155: public Set getFetchGroups();
156:
157: /**
158: * Return true if the given fetch group has been added.
159: */
160: public boolean hasFetchGroup(String group);
161:
162: /**
163: * Adds <code>group</code> to the set of fetch group names to
164: * use when loading objects.
165: */
166: public FetchConfiguration addFetchGroup(String group);
167:
168: /**
169: * Adds <code>groups</code> to the set of fetch group names to
170: * use when loading objects.
171: */
172: public FetchConfiguration addFetchGroups(Collection groups);
173:
174: /**
175: * Remove the given fetch group.
176: */
177: public FetchConfiguration removeFetchGroup(String group);
178:
179: /**
180: * Removes <code>groups</code> from the set of fetch group names
181: * to use when loading objects.
182: */
183: public FetchConfiguration removeFetchGroups(Collection groups);
184:
185: /**
186: * Clears the set of fetch group names to use when loading
187: * data. After this operation is invoked, only those fields in
188: * the default fetch group (and any requested field) will be
189: * loaded when loading an object.
190: */
191: public FetchConfiguration clearFetchGroups();
192:
193: /**
194: * Resets the set of fetch groups to the list in the global configuration.
195: */
196: public FetchConfiguration resetFetchGroups();
197:
198: /**
199: * Returns the set of fully-qualified field names that this component
200: * will use when loading objects. Defaults to the empty set. This set is
201: * not thread safe.
202: */
203: public Set getFields();
204:
205: /**
206: * Return true if the given fully-qualified field has been added.
207: */
208: public boolean hasField(String field);
209:
210: /**
211: * Adds <code>field</code> to the set of fully-qualified field names to
212: * use when loading objects.
213: */
214: public FetchConfiguration addField(String field);
215:
216: /**
217: * Adds <code>fields</code> to the set of fully-qualified field names to
218: * use when loading objects.
219: */
220: public FetchConfiguration addFields(Collection fields);
221:
222: /**
223: * Remove the given fully-qualified field.
224: */
225: public FetchConfiguration removeField(String field);
226:
227: /**
228: * Removes <code>fields</code> from the set of fully-qualified field names
229: * to use when loading objects.
230: */
231: public FetchConfiguration removeFields(Collection fields);
232:
233: /**
234: * Clears the set of field names to use when loading
235: * data. After this operation is invoked, only those fields in
236: * the configured fetch groups will be loaded when loading an object.
237: */
238: public FetchConfiguration clearFields();
239:
240: /**
241: * The number of milliseconds to wait for an object lock, or -1 for no
242: * limit.
243: *
244: * @since 0.3.1
245: */
246: public int getLockTimeout();
247:
248: /**
249: * The number of milliseconds to wait for an object lock, or -1 for no
250: * limit.
251: *
252: * @since 0.3.1
253: */
254: public FetchConfiguration setLockTimeout(int timeout);
255:
256: /**
257: * The lock level to use for locking loaded objects.
258: *
259: * @since 0.3.1
260: */
261: public int getReadLockLevel();
262:
263: /**
264: * The lock level to use for locking loaded objects.
265: *
266: * @since 0.3.1
267: */
268: public FetchConfiguration setReadLockLevel(int level);
269:
270: /**
271: * The lock level to use for locking dirtied objects.
272: *
273: * @since 0.3.1
274: */
275: public int getWriteLockLevel();
276:
277: /**
278: * The lock level to use for locking dirtied objects.
279: *
280: * @since 0.3.1
281: */
282: public FetchConfiguration setWriteLockLevel(int level);
283:
284: /**
285: * Return a new result list for the current fetch configuration.
286: */
287: public ResultList newResultList(ResultObjectProvider rop);
288:
289: /**
290: * Sets an arbitrary query hint that may be utilized during
291: * execution. The hint may be datastore-specific.
292: *
293: * @param name the name of the hint
294: * @param value the value of the hint
295: * @since 0.4.0
296: */
297: public void setHint(String name, Object value);
298:
299: /**
300: * Returns the hint for the specific key, or null if the hint
301: * is not specified.
302: *
303: * @param name the hint name
304: * @since 0.4.0
305: */
306: public Object getHint(String name);
307:
308: /**
309: * Root classes for recursive operations. This set is not thread safe.
310: */
311: public Set getRootClasses();
312:
313: /**
314: * Root classes for recursive operations.
315: */
316: public FetchConfiguration setRootClasses(Collection classes);
317:
318: /**
319: * Root instances for recursive operations. This set is not thread safe.
320: */
321: public Set getRootInstances();
322:
323: /**
324: * Root instances for recursive operations.
325: */
326: public FetchConfiguration setRootInstances(Collection roots);
327:
328: /**
329: * Synchronize on internal lock if multithreaded is true.
330: */
331: public void lock();
332:
333: /**
334: * Release internal lock if multithreaded is true.
335: */
336: public void unlock();
337:
338: /**
339: * Affirms if the given field requires to be fetched in the context
340: * of current fetch operation. Returns one of {@link #FETCH_NONE},
341: * {@link #FETCH_LOAD}, {@link FETCH_REF}.
342: *
343: * @since 0.4.1
344: */
345: public int requiresFetch(FieldMetaData fm);
346:
347: /**
348: * Return false if we know that the object being fetched with this
349: * configuration does not require a load, because this configuration came
350: * from a traversal of a {@link #FETCH_REF} field.
351: */
352: public boolean requiresLoad();
353:
354: /**
355: * Traverse the given field to generate (possibly) a new configuration
356: * state.
357: *
358: * @return a new configuration state resulting out of traversal
359: * @since 0.4.1
360: */
361: public FetchConfiguration traverse(FieldMetaData fm);
362: }
| 