org.apache.openjpa.kernel
Interface FetchConfiguration

All Superinterfaces:
Cloneable, LockLevels, QueryFlushModes, Serializable
All Known Subinterfaces:
JDBCFetchConfiguration
All Known Implementing Classes:
DelegatingFetchConfiguration, DelegatingJDBCFetchConfiguration, FetchConfigurationImpl, JDBCFetchConfigurationImpl

public interface FetchConfiguration
extends Serializable, Cloneable, LockLevels, QueryFlushModes

Allows configuration and optimization of how objects are loaded from the data store.

Since:
0.3.0
Author:
Abe White, Pinaki Poddar

Field Summary
static int DEFAULT
          Constant to revert any setting back to its default value.
static int FETCH_LOAD
          Constant indicating that a field requires a fetch and load of fetched data.
static int FETCH_NONE
          Constant indicating that a field does not require fetching.
static int FETCH_REF
          Constant indicating that a reference to the field's value must be fetched, but loading data is not necessary.
 
Fields inherited from interface org.apache.openjpa.kernel.LockLevels
LOCK_NONE, LOCK_READ, LOCK_WRITE
 
Fields inherited from interface org.apache.openjpa.kernel.QueryFlushModes
FLUSH_FALSE, FLUSH_TRUE, FLUSH_WITH_CONNECTION
 
Method Summary
 FetchConfiguration addFetchGroup(String group)
          Adds group to the set of fetch group names to use when loading objects.
 FetchConfiguration addFetchGroups(Collection groups)
          Adds groups to the set of fetch group names to use when loading objects.
 FetchConfiguration addField(String field)
          Adds field to the set of fully-qualified field names to use when loading objects.
 FetchConfiguration addFields(Collection fields)
          Adds fields to the set of fully-qualified field names to use when loading objects.
 FetchConfiguration clearFetchGroups()
          Clears the set of fetch group names to use when loading data.
 FetchConfiguration clearFields()
          Clears the set of field names to use when loading data.
 Object clone()
          Clone this instance.
 void copy(FetchConfiguration fetch)
          Copy the state from the given fetch configuration to this one.
 StoreContext getContext()
          Return the context assiciated with this configuration; may be null if it has not been set or this object has been serialized.
 int getFetchBatchSize()
          Return the fetch batch size for large result set support.
 Set getFetchGroups()
          Returns immutable set of names of the fetch groups that this component will use when loading objects.
 Set getFields()
          Returns the set of fully-qualified field names that this component will use when loading objects.
 int getFlushBeforeQueries()
          The query automatic flush configuration.
 Object getHint(String name)
          Returns the hint for the specific key, or null if the hint is not specified.
 int getLockTimeout()
          The number of milliseconds to wait for an object lock, or -1 for no limit.
 int getMaxFetchDepth()
          Return the maximum depth of fetched instance graph.
 boolean getQueryCacheEnabled()
          Return whether or not query caching is enabled.
 int getReadLockLevel()
          The lock level to use for locking loaded objects.
 Set getRootClasses()
          Root classes for recursive operations.
 Set getRootInstances()
          Root instances for recursive operations.
 int getWriteLockLevel()
          The lock level to use for locking dirtied objects.
 boolean hasFetchGroup(String group)
          Return true if the given fetch group has been added.
 boolean hasField(String field)
          Return true if the given fully-qualified field has been added.
 void lock()
          Synchronize on internal lock if multithreaded is true.
 ResultList newResultList(ResultObjectProvider rop)
          Return a new result list for the current fetch configuration.
 FetchConfiguration removeFetchGroup(String group)
          Remove the given fetch group.
 FetchConfiguration removeFetchGroups(Collection groups)
          Removes groups from the set of fetch group names to use when loading objects.
 FetchConfiguration removeField(String field)
          Remove the given fully-qualified field.
 FetchConfiguration removeFields(Collection fields)
          Removes fields from the set of fully-qualified field names to use when loading objects.
 int requiresFetch(FieldMetaData fm)
          Affirms if the given field requires to be fetched in the context of current fetch operation.
 boolean requiresLoad()
          Return false if we know that the object being fetched with this configuration does not require a load, because this configuration came from a traversal of a FETCH_REF field.
 FetchConfiguration resetFetchGroups()
          Resets the set of fetch groups to the list in the global configuration.
 void setContext(StoreContext ctx)
          Called automatically by the system to associate the fetch configuration with a context before use.
 FetchConfiguration setFetchBatchSize(int fetchBatchSize)
          Set the fetch batch size for large result set support.
 FetchConfiguration setFlushBeforeQueries(int flush)
          The query automatic flush configuration.
 void setHint(String name, Object value)
          Sets an arbitrary query hint that may be utilized during execution.
 FetchConfiguration setLockTimeout(int timeout)
          The number of milliseconds to wait for an object lock, or -1 for no limit.
 FetchConfiguration setMaxFetchDepth(int max)
          Set the maximum depth of the fetched instance graph.
 FetchConfiguration setQueryCacheEnabled(boolean cache)
          Control whether or not query caching is enabled.
 FetchConfiguration setReadLockLevel(int level)
          The lock level to use for locking loaded objects.
 FetchConfiguration setRootClasses(Collection classes)
          Root classes for recursive operations.
 FetchConfiguration setRootInstances(Collection roots)
          Root instances for recursive operations.
 FetchConfiguration setWriteLockLevel(int level)
          The lock level to use for locking dirtied objects.
 FetchConfiguration traverse(FieldMetaData fm)
          Traverse the given field to generate (possibly) a new configuration state.
 void unlock()
          Release internal lock if multithreaded is true.
 

Field Detail

DEFAULT

static final int DEFAULT
Constant to revert any setting back to its default value.

See Also:
Constant Field Values

FETCH_NONE

static final int FETCH_NONE
Constant indicating that a field does not require fetching.

See Also:
requiresFetch(org.apache.openjpa.meta.FieldMetaData), Constant Field Values

FETCH_LOAD

static final int FETCH_LOAD
Constant indicating that a field requires a fetch and load of fetched data.

See Also:
requiresFetch(org.apache.openjpa.meta.FieldMetaData), Constant Field Values

FETCH_REF

static final int FETCH_REF
Constant indicating that a reference to the field's value must be fetched, but loading data is not necessary. Used when we know the data will be loaded anyway, such as when traversing the back-ptr of a bidirectional relation where the other side is also being fetched.

See Also:
requiresFetch(org.apache.openjpa.meta.FieldMetaData), Constant Field Values
Method Detail

getContext

StoreContext getContext()
Return the context assiciated with this configuration; may be null if it has not been set or this object has been serialized.


setContext

void setContext(StoreContext ctx)
Called automatically by the system to associate the fetch configuration with a context before use. The fetch configuration properties should be synchronized with the context's configuration object. Subclasses for specific back ends cannot rely on the context's configuration implementing their back end's configuration sub-interface.


clone

Object clone()
Clone this instance.


copy

void copy(FetchConfiguration fetch)
Copy the state from the given fetch configuration to this one.


getFetchBatchSize

int getFetchBatchSize()
Return the fetch batch size for large result set support. Defaults to the openjpa.FetchBatchSize setting. Note that this property will be ignored under some data stores.


setFetchBatchSize

FetchConfiguration setFetchBatchSize(int fetchBatchSize)
Set the fetch batch size for large result set support. Defaults to the openjpa.FetchBatchSize setting. Note that this property will be ignored under some data stores.


getMaxFetchDepth

int getMaxFetchDepth()
Return the maximum depth of fetched instance graph. Defaults to 1


setMaxFetchDepth

FetchConfiguration setMaxFetchDepth(int max)
Set the maximum depth of the fetched instance graph.

Parameters:
max - denotes limiting length of traversal path from a root instance. -1 implies no limit. 0 is not permissible.

getQueryCacheEnabled

boolean getQueryCacheEnabled()
Return whether or not query caching is enabled. If this returns true but the datacache plugin is not installed, caching will not be enabled. If this returns false, query caching will not be used even if the datacache plugin is installed.


setQueryCacheEnabled

FetchConfiguration setQueryCacheEnabled(boolean cache)
Control whether or not query caching is enabled. This has no effect if the datacache plugin is not installed, or if the query cache size is set to zero.


getFlushBeforeQueries

int getFlushBeforeQueries()
The query automatic flush configuration.


setFlushBeforeQueries

FetchConfiguration setFlushBeforeQueries(int flush)
The query automatic flush configuration.


getFetchGroups

Set getFetchGroups()
Returns immutable set of names of the fetch groups that this component will use when loading objects. Defaults to the openjpa.FetchGroups setting. This set is not thread safe.


hasFetchGroup

boolean hasFetchGroup(String group)
Return true if the given fetch group has been added.


addFetchGroup

FetchConfiguration addFetchGroup(String group)
Adds group to the set of fetch group names to use when loading objects.


addFetchGroups

FetchConfiguration addFetchGroups(Collection groups)
Adds groups to the set of fetch group names to use when loading objects.


removeFetchGroup

FetchConfiguration removeFetchGroup(String group)
Remove the given fetch group.


removeFetchGroups

FetchConfiguration removeFetchGroups(Collection groups)
Removes groups from the set of fetch group names to use when loading objects.


clearFetchGroups

FetchConfiguration clearFetchGroups()
Clears the set of fetch group names to use when loading data. After this operation is invoked, only those fields in the default fetch group (and any requested field) will be loaded when loading an object.


resetFetchGroups

FetchConfiguration resetFetchGroups()
Resets the set of fetch groups to the list in the global configuration.


getFields

Set getFields()
Returns the set of fully-qualified field names that this component will use when loading objects. Defaults to the empty set. This set is not thread safe.


hasField

boolean hasField(String field)
Return true if the given fully-qualified field has been added.


addField

FetchConfiguration addField(String field)
Adds field to the set of fully-qualified field names to use when loading objects.


addFields

FetchConfiguration addFields(Collection fields)
Adds fields to the set of fully-qualified field names to use when loading objects.


removeField

FetchConfiguration removeField(String field)
Remove the given fully-qualified field.


removeFields

FetchConfiguration removeFields(Collection fields)
Removes fields from the set of fully-qualified field names to use when loading objects.


clearFields

FetchConfiguration clearFields()
Clears the set of field names to use when loading data. After this operation is invoked, only those fields in the configured fetch groups will be loaded when loading an object.


getLockTimeout

int getLockTimeout()
The number of milliseconds to wait for an object lock, or -1 for no limit.

Since:
0.3.1

setLockTimeout

FetchConfiguration setLockTimeout(int timeout)
The number of milliseconds to wait for an object lock, or -1 for no limit.

Since:
0.3.1

getReadLockLevel

int getReadLockLevel()
The lock level to use for locking loaded objects.

Since:
0.3.1

setReadLockLevel

FetchConfiguration setReadLockLevel(int level)
The lock level to use for locking loaded objects.

Since:
0.3.1

getWriteLockLevel

int getWriteLockLevel()
The lock level to use for locking dirtied objects.

Since:
0.3.1

setWriteLockLevel

FetchConfiguration setWriteLockLevel(int level)
The lock level to use for locking dirtied objects.

Since:
0.3.1

newResultList

ResultList newResultList(ResultObjectProvider rop)
Return a new result list for the current fetch configuration.


setHint

void setHint(String name,
             Object value)
Sets an arbitrary query hint that may be utilized during execution. The hint may be datastore-specific.

Parameters:
name - the name of the hint
value - the value of the hint
Since:
0.4.0

getHint

Object getHint(String name)
Returns the hint for the specific key, or null if the hint is not specified.

Parameters:
name - the hint name
Since:
0.4.0

getRootClasses

Set getRootClasses()
Root classes for recursive operations. This set is not thread safe.


setRootClasses

FetchConfiguration setRootClasses(Collection classes)
Root classes for recursive operations.


getRootInstances

Set getRootInstances()
Root instances for recursive operations. This set is not thread safe.


setRootInstances

FetchConfiguration setRootInstances(Collection roots)
Root instances for recursive operations.


lock

void lock()
Synchronize on internal lock if multithreaded is true.


unlock

void unlock()
Release internal lock if multithreaded is true.


requiresFetch

int requiresFetch(FieldMetaData fm)
Affirms if the given field requires to be fetched in the context of current fetch operation. Returns one of FETCH_NONE, FETCH_LOAD, FETCH_REF.

Since:
0.4.1

requiresLoad

boolean requiresLoad()
Return false if we know that the object being fetched with this configuration does not require a load, because this configuration came from a traversal of a FETCH_REF field.


traverse

FetchConfiguration traverse(FieldMetaData fm)
Traverse the given field to generate (possibly) a new configuration state.

Returns:
a new configuration state resulting out of traversal
Since:
0.4.1


Copyright © 2006-2007 Apache Software Foundation. All Rights Reserved.