FetchConfiguration (OpenJPA Parent POM 2.4.3 API)

All Superinterfaces:

Cloneable, LockLevels, LockScopes, QueryFlushModes, Serializable

All Known Subinterfaces:

JDBCFetchConfiguration

All Known Implementing Classes:

DelegatingFetchConfiguration, DelegatingJDBCFetchConfiguration, FetchConfigurationImpl, JDBCFetchConfigurationImpl, TargetFetchConfiguration
```
public interface FetchConfiguration
extends Serializable, Cloneable, LockLevels, LockScopes, 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

Fields
Modifier and Type	Field and Description
`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.LockScopes
LOCKSCOPE_EXTENDED, LOCKSCOPE_NORMAL

Fields inherited from interface org.apache.openjpa.kernel.QueryFlushModes
FLUSH_FALSE, FLUSH_TRUE, FLUSH_WITH_CONNECTION

Method Summary

Methods
Modifier and Type	Method and Description
`FetchConfiguration`	`addFetchGroup(String group)` Adds `group` to the set of fetch group names to use when loading objects.
`FetchConfiguration`	`addFetchGroups(Collection<String> 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<String> 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.
`DataCacheRetrieveMode`	`getCacheRetrieveMode()` Gets the current retrieve mode for data cache.
`DataCacheStoreMode`	`getCacheStoreMode()` Gets the current storage mode for data cache.
`StoreContext`	`getContext()` Return the context associated with this configuration; may be null if it has not been set or this object has been serialized.
`boolean`	`getExtendedPathLookup()` Affirms if extended path lookup feature is active.
`int`	`getFetchBatchSize()` Return the fetch batch size for large result set support.
`Set<String>`	`getFetchGroups()` Returns immutable set of names of the fetch groups that this component will use when loading objects.
`Set<String>`	`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 key)` Get the hint value for the specific key as originally set by the caller, or null if the hint is not specified.
`Map<String,Object>`	`getHints()` Get an immutable view of the currently active hints and their values.
`int`	`getLockScope()` The lock scope for next fetch.
`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`	`getQueryTimeout()` The number of milliseconds to wait for a query, or -1 for no limit.
`int`	`getReadLockLevel()` The lock level to use for locking loaded objects.
`Set<Class<?>>`	`getRootClasses()` Root classes for recursive operations.
`Set<Object>`	`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.
`boolean`	`isDefaultPUFetchGroupConfigurationOnly()` Affirm if the Fetch Plan currently matches the Persistence Unit's configured default.
`boolean`	`isFetchConfigurationSQLCacheAdmissible()` Whether SQL generated by the FetchConfiguration's current configuration should be cached.
`boolean`	`isHintSet(String key)` Affirm if the given hint has been set in this receiver.
`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<String> 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<String> 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`	`setCacheRetrieveMode(DataCacheRetrieveMode mode)` Sets the current retrieve mode for data cache.
`void`	`setCacheStoreMode(DataCacheStoreMode mode)` Sets the current storage mode for data cache.
`void`	`setContext(StoreContext ctx)` Called automatically by the system to associate the fetch configuration with a context before use.
`FetchConfiguration`	`setExtendedPathLookup(boolean flag)` Sets extended path lookup feature.
`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 key, Object value)` Sets an arbitrary query hint that may be utilized during execution.
`void`	`setHint(String name, Object value, Object original)` Sets an arbitrary query hint that may be utilized during execution.
`FetchConfiguration`	`setLockScope(int scope)` The lock scope for next fetch.
`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`	`setQueryTimeout(int timeout)` The number of milliseconds to wait for a query, or -1 for no limit.
`FetchConfiguration`	`setReadLockLevel(int level)` The lock level to use for locking loaded objects.
`FetchConfiguration`	`setRootClasses(Collection<Class<?>> 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 associated 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.
  - getExtendedPathLookup
```
boolean getExtendedPathLookup()
```
    Affirms if extended path lookup feature is active.
    
    Since:
    
    2.0.0
  - setExtendedPathLookup
```
FetchConfiguration setExtendedPathLookup(boolean flag)
```
    Sets extended path lookup feature.
    
    Since:
    
    2.0.0
  - getFetchGroups
```
Set<String> 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<String> 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<String> 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<String> 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<String> 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<String> 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
  - getLockScope
```
int getLockScope()
```
    The lock scope for next fetch.
    
    Since:
    
    2.0.0
  - setLockScope
```
FetchConfiguration setLockScope(int scope)
```
    The lock scope for next fetch.
    
    Since:
    
    2.0.0
  - getQueryTimeout
```
int getQueryTimeout()
```
    The number of milliseconds to wait for a query, or -1 for no limit.
    
    Since:
    
    2.0.0
  - setQueryTimeout
```
FetchConfiguration setQueryTimeout(int timeout)
```
    The number of milliseconds to wait for a query, or -1 for no limit.
    
    Since:
    
    2.0.0
  - 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
  - getCacheStoreMode
```
DataCacheStoreMode getCacheStoreMode()
```
    Gets the current storage mode for data cache.
    
    Since:
    
    2.0.0
  - setCacheStoreMode
```
void setCacheStoreMode(DataCacheStoreMode mode)
```
    Sets the current storage mode for data cache.
    
    Since:
    
    2.0.0
  - getCacheRetrieveMode
```
DataCacheRetrieveMode getCacheRetrieveMode()
```
    Gets the current retrieve mode for data cache.
    
    Since:
    
    2.0.0
  - setCacheRetrieveMode
```
void setCacheRetrieveMode(DataCacheRetrieveMode mode)
```
    Sets the current retrieve mode for data cache.
    
    Since:
    
    2.0.0
  - 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,
           Object original)
```
    Sets an arbitrary query hint that may be utilized during execution. The hint may be specific to a particular database. A hint, if known to this receiver, may have a corresponding setter method, then the hint sets the value. Otherwise the hint is stored opaquely by the receiver.
    
    Parameters:
    name - the name of the hint
    value - the value of the hint. If the hint has a corresponding setter, then the type of value must be same as the setter argument.
    original - the value of the hint as specified by the user.
    Since:
    
    2.0.0
  - setHint
```
void setHint(String key,
           Object value)
```
    Sets an arbitrary query hint that may be utilized during execution. The hint may be specific to a particular database. A hint, if known to this receiver, may have a corresponding setter method, then the hint sets the value. Otherwise the hint is stored opaquely by the receiver.
    This is same as calling setHint(String, Object, Object) with the third argument being the same as the second.
    
    Parameters:
    name - the name of the hint
    value - the value of the hint. If the hint has a corresponding setter, then the type of value must be same as the setter argument.
    Since:
    
    2.0.0
  - getHint
```
Object getHint(String key)
```
    Get the hint value for the specific key as originally set by the caller, or null if the hint is not specified.
    
    Parameters:
    name - the hint name
    Since:
    
    0.4.0
  - getHints
```
Map<String,Object> getHints()
```
    Get an immutable view of the currently active hints and their values. The values are as specified by the user.
    
    Since:
    
    2.0.0
  - isHintSet
```
boolean isHintSet(String key)
```
    Affirm if the given hint has been set in this receiver.
  - isDefaultPUFetchGroupConfigurationOnly
```
boolean isDefaultPUFetchGroupConfigurationOnly()
```
    Affirm if the Fetch Plan currently matches the Persistence Unit's configured default.
  - getRootClasses
```
Set<Class<?>> getRootClasses()
```
    Root classes for recursive operations. This set is not thread safe.
  - setRootClasses
```
FetchConfiguration setRootClasses(Collection<Class<?>> classes)
```
    Root classes for recursive operations.
  - getRootInstances
```
Set<Object> 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
  - isFetchConfigurationSQLCacheAdmissible
```
boolean isFetchConfigurationSQLCacheAdmissible()
```
    Whether SQL generated by the FetchConfiguration's current configuration should be cached.

Interface FetchConfiguration

Field Summary

Fields inherited from interface org.apache.openjpa.kernel.LockLevels

Fields inherited from interface org.apache.openjpa.kernel.LockScopes

Fields inherited from interface org.apache.openjpa.kernel.QueryFlushModes

Method Summary

Field Detail

DEFAULT

FETCH_NONE

FETCH_LOAD

FETCH_REF

Method Detail

getContext

setContext

clone

copy

getFetchBatchSize

setFetchBatchSize

getMaxFetchDepth

setMaxFetchDepth

getQueryCacheEnabled

setQueryCacheEnabled

getFlushBeforeQueries

setFlushBeforeQueries

getExtendedPathLookup

setExtendedPathLookup

getFetchGroups

hasFetchGroup

addFetchGroup

addFetchGroups

removeFetchGroup

removeFetchGroups

clearFetchGroups

resetFetchGroups

getFields

hasField

addField

addFields

removeField

removeFields

clearFields

getLockTimeout

setLockTimeout

getLockScope

setLockScope

getQueryTimeout

setQueryTimeout

getReadLockLevel

setReadLockLevel

getWriteLockLevel

getCacheStoreMode

setCacheStoreMode

getCacheRetrieveMode

setCacheRetrieveMode

setWriteLockLevel

newResultList

setHint

setHint

getHint

getHints

isHintSet

isDefaultPUFetchGroupConfigurationOnly

getRootClasses

setRootClasses

getRootInstances

setRootInstances

lock

unlock

requiresFetch

requiresLoad

traverse

isFetchConfigurationSQLCacheAdmissible