kodo.runtime
Interface FetchConfiguration

All Superinterfaces:

Cloneable, Serializable

All Known Subinterfaces:

JDBCFetchConfiguration

public interface FetchConfiguration

extends Serializable, Cloneable

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

Since:

3.0

Field Summary

static int	DEFAULT Constant to revert any setting back to its default value.
static int	EAGER_FETCH_MULTIPLE Deprecated. Use EAGER_PARALLEL
static int	EAGER_FETCH_NONE Deprecated. Use EAGER_NONE
static int	EAGER_FETCH_SINGLE Deprecated. Use EAGER_JOIN
static int	EAGER_JOIN Constant indicating to load relations and subclass data if possible without separate queries.
static int	EAGER_NONE Constant indicating not to try to load subclass data and related objects when querying for an object.
static int	EAGER_PARALLEL Constant indicating to load relations and subclass data if possible using either "joins" or parallel queries.
static String	FETCH_GROUP_ALL Special fetch group name that is used by Kodo to indicate that all fetch groups should be loaded by this configuration.
static int	LOCK_NONE No lock.
static int	LOCK_READ Generic read lock level.
static int	LOCK_WRITE Generic write lock level.
static int	QUERY_FLUSH_FALSE Constant denoting that queries should never flush data to the database automatically before executing a query, but should instead execute queries in-memory if necessary.
static int	QUERY_FLUSH_TRUE Constant denoting that queries should flush data to the database automatically whenever Kodo determines that relevant modifications have been made and IgnoreCache is false.
static int	QUERY_FLUSH_WITH_CONNECTION Constant denoting that queries should flush data to the database automatically when Kodo determines that relevant modifications have been made and the current PersistenceManager already has a dedicated connection.

Method Summary

boolean	addFetchGroup(String group) Adds group to the set of fetch group names to use when loading objects.
boolean	addFetchGroups(Collection groups) Adds groups to the set of fetch group names to use when loading objects.
boolean	addFetchGroups(String[] groups) Adds groups to the set of fetch group names to use when loading objects.
boolean	addField(Class cls, String field) Adds field to the set of field names to use when loading objects.
boolean	addField(String field) Adds field to the set of fully-qualified field names to use when loading objects.
boolean	addFields(Class cls, Collection fields) Adds fields to the set of field names to use when loading objects.
boolean	addFields(Class cls, String[] fields) Adds fields to the set of field names to use when loading objects.
boolean	addFields(Collection fields) Adds fields to the set of fully-qualified field names to use when loading objects.
boolean	addFields(String[] fields) Adds fields to the set of fully-qualified field names to use when loading objects.
void	clearFetchGroups() Clears the set of fetch group names to use wen loading data.
void	clearFields() Clears the set of field names to use wen loading data.
Object	clone() Fetch configurations are cloneable.
void	copy(FetchConfiguration fetch) Copy the state from the given fetch configuration to this one.
int	getEagerFetchMode() Return the eager fetch mode.
int	getFetchBatchSize() Return the fetch batch size for large result set support.
String[]	getFetchGroups() Returns the names of the fetch groups that this component will use when loading objects.
String[]	getFields() Returns the names of the fields that this component will use when loading objects.
int	getFlushBeforeQueries() The query automatic flush configuration.
int	getLockTimeout() The number of milliseconds to wait for an object lock, or -1 for no limit.
KodoPersistenceManager	getPersistenceManager() Return the persistence manager assiciated with this configuration; may be null if it has not been set or this object has been serialized.
int	getReadLockLevel() The lock level to use for locking loaded objects.
int	getSubclassFetchMode() Return the subclass fetch mode.
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(Class cls, String field) Return true if the given field has been added.
boolean	hasField(String field) Return true if the given fully-qualified field has been added.
boolean	isQueryCacheEnabled() Return whether or not query caching is enabled.
ResultList	newResultList(ResultObjectProvider rop) Return a new result list for the current fetch configuration.
boolean	removeFetchGroup(String group) Remove the given fetch group.
boolean	removeFetchGroups(Collection groups) Removes groups from the set of fetch group names to use when loading objects.
boolean	removeFetchGroups(String[] groups) Removes groups from the set of fetch group names to use when loading objects.
boolean	removeField(Class cls, String field) Remove the given field.
boolean	removeField(String field) Remove the given fully-qualified field.
boolean	removeFields(Class cls, Collection fields) Removes fields from the set of field names to use when loading objects.
boolean	removeFields(Class cls, String[] fields) Removes fields from the set of field names to use when loading objects.
boolean	removeFields(Collection fields) Removes fields from the set of fully-qualified field names to use when loading objects.
boolean	removeFields(String[] fields) Removes fields from the set of fully-qualified field names to use when loading objects.
void	resetFetchGroups() Resets the set of fetch groups to the list in the global configuration.
void	setEagerFetchMode(int mode) Set the eager fetch mode.
void	setFetchBatchSize(int fetchBatchSize) Set the fetch batch size for large result set support.
void	setFlushBeforeQueries(int flush) The query automatic flush configuration.
void	setLockTimeout(int timeout) The number of milliseconds to wait for an object lock, or -1 for no limit.
void	setPersistenceManager(KodoPersistenceManager pm) Called automatically by the system to associate the fetch configuration with a persistence manager before use.
void	setQueryCacheEnabled(boolean cache) Control whether or not query caching is enabled.
void	setReadLockLevel(int level) The lock level to use for locking loaded objects.
void	setSubclassFetchMode(int mode) Set the subclass fetch mode.
void	setWriteLockLevel(int level) The lock level to use for locking dirtied objects.

Field Detail

DEFAULT

public static final int DEFAULT

Constant to revert any setting back to its default value.

EAGER_NONE

public static final int EAGER_NONE

Constant indicating not to try to load subclass data and related objects when querying for an object.

EAGER_JOIN

public static final int EAGER_JOIN

Constant indicating to load relations and subclass data if possible without separate queries.

EAGER_PARALLEL

public static final int EAGER_PARALLEL

Constant indicating to load relations and subclass data if possible using either "joins" or parallel queries.

EAGER_FETCH_NONE

public static final int EAGER_FETCH_NONE

Deprecated. Use EAGER_NONE

EAGER_FETCH_SINGLE

public static final int EAGER_FETCH_SINGLE

Deprecated. Use EAGER_JOIN

EAGER_FETCH_MULTIPLE

public static final int EAGER_FETCH_MULTIPLE

Deprecated. Use EAGER_PARALLEL

QUERY_FLUSH_TRUE

public static final int QUERY_FLUSH_TRUE

Constant denoting that queries should flush data to the database automatically whenever Kodo determines that relevant modifications have been made and IgnoreCache is false. See JDOConfiguration.getFlushBeforeQueries() for more info.

QUERY_FLUSH_FALSE

public static final int QUERY_FLUSH_FALSE

Constant denoting that queries should never flush data to the database automatically before executing a query, but should instead execute queries in-memory if necessary. See JDOConfiguration.getFlushBeforeQueries() for more info.

QUERY_FLUSH_WITH_CONNECTION

public static final int QUERY_FLUSH_WITH_CONNECTION

Constant denoting that queries should flush data to the database automatically when Kodo determines that relevant modifications have been made and the current PersistenceManager already has a dedicated connection. See JDOConfiguration.getFlushBeforeQueries() for more info.

LOCK_NONE

public static final int LOCK_NONE

No lock.

See Also:

KodoPersistenceManager.LOCK_NONE

LOCK_READ

public static final int LOCK_READ

Generic read lock level.

See Also:

KodoPersistenceManager.LOCK_READ

LOCK_WRITE

public static final int LOCK_WRITE

Generic write lock level.

See Also:

KodoPersistenceManager.LOCK_WRITE

FETCH_GROUP_ALL

public static final String FETCH_GROUP_ALL

Special fetch group name that is used by Kodo to indicate that all fetch groups should be loaded by this configuration.

Method Detail

getPersistenceManager

public KodoPersistenceManager getPersistenceManager()

Return the persistence manager assiciated with this configuration; may be null if it has not been set or this object has been serialized. In this case, the fetch configuration may not allow the setting of certain properties that require non-standard license capabilities.

setPersistenceManager

public void setPersistenceManager(KodoPersistenceManager pm)

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

getEagerFetchMode

public int getEagerFetchMode()

Return the eager fetch mode. Defaults to the kodo.EagerFetchMode setting.

setEagerFetchMode

public void setEagerFetchMode(int mode)

Set the eager fetch mode. Defaults to the kodo.EagerFetchMode setting.

getSubclassFetchMode

public int getSubclassFetchMode()

Return the subclass fetch mode. Defaults to the kodo.SubclassFetchMode setting.

setSubclassFetchMode

public void setSubclassFetchMode(int mode)

Set the subclass fetch mode. Defaults to the kodo.SubclassFetchMode setting.

getFetchBatchSize

public int getFetchBatchSize()

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

setFetchBatchSize

public void setFetchBatchSize(int fetchBatchSize)

Set the fetch batch size for large result set support. Defaults to the kodo.FetchBatchSize setting. Note that this property will be ignored under some data stores.

isQueryCacheEnabled

public boolean isQueryCacheEnabled()

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

public void 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

public int getFlushBeforeQueries()

The query automatic flush configuration.

setFlushBeforeQueries

public void setFlushBeforeQueries(int flush)

The query automatic flush configuration.

getFetchGroups

public String[] getFetchGroups()

Returns the names of the fetch groups that this component will use when loading objects. Defaults to the kodo.FetchGroups setting.

hasFetchGroup

public boolean hasFetchGroup(String group)

Return true if the given fetch group has been added.

addFetchGroup

public boolean addFetchGroup(String group)

Adds group to the set of fetch group names to use when loading objects.

Returns:

true if group was added; false if group was already in the fetch group set

addFetchGroups

public boolean addFetchGroups(String[] groups)

Adds groups to the set of fetch group names to use when loading objects.

Returns:

true if the set of fetch group names to load was updated as a result of this operation

addFetchGroups

public boolean addFetchGroups(Collection groups)

Adds groups to the set of fetch group names to use when loading objects.

Returns:

true if the set of fetch group names to load was updated as a result of this operation

removeFetchGroup

public boolean removeFetchGroup(String group)

Remove the given fetch group.

removeFetchGroups

public boolean removeFetchGroups(String[] groups)

Removes groups from the set of fetch group names to use when loading objects.

Returns:

true if the set of fetch group names to load was updated as a result of this operation

removeFetchGroups

public boolean removeFetchGroups(Collection groups)

Removes groups from the set of fetch group names to use when loading objects.

Returns:

true if the set of fetch group names to load was updated as a result of this operation

clearFetchGroups

public void clearFetchGroups()

Clears the set of fetch group names to use wen 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

public void resetFetchGroups()

Resets the set of fetch groups to the list in the global configuration.

getFields

public String[] getFields()

Returns the names of the fields that this component will use when loading objects. Defaults to the empty set.

hasField

public boolean hasField(String field)

Return true if the given fully-qualified field has been added.

hasField

public boolean hasField(Class cls,
                        String field)

Return true if the given field has been added.

addField

public boolean addField(String field)

Adds field to the set of fully-qualified field names to use when loading objects.

Returns:

true if field was added; false if field was already in the field set

addField

public boolean addField(Class cls,
                        String field)

Adds field to the set of field names to use when loading objects.

Returns:

true if field was added; false if field was already in the field set

addFields

public boolean addFields(String[] fields)

Adds fields to the set of fully-qualified field names to use when loading objects.

Returns:

true if the set of field names to load was updated as a result of this operation

addFields

public boolean addFields(Class cls,
                         String[] fields)

Adds fields to the set of field names to use when loading objects.

Returns:

true if the set of field names to load was updated as a result of this operation

addFields

public boolean addFields(Collection fields)

Adds fields to the set of fully-qualified field names to use when loading objects.

Returns:

true if the set of field names to load was updated as a result of this operation

addFields

public boolean addFields(Class cls,
                         Collection fields)

Adds fields to the set of field names to use when loading objects.

Returns:

true if the set of field names to load was updated as a result of this operation

removeField

public boolean removeField(String field)

Remove the given fully-qualified field.

removeField

public boolean removeField(Class cls,
                           String field)

Remove the given field.

removeFields

public boolean removeFields(String[] fields)

Removes fields from the set of fully-qualified field names to use when loading objects.

Returns:

true if the set of field names to load was updated as a result of this operation

removeFields

public boolean removeFields(Class cls,
                            String[] fields)

Removes fields from the set of field names to use when loading objects.

Returns:

true if the set of field names to load was updated as a result of this operation

removeFields

public boolean removeFields(Collection fields)

Removes fields from the set of fully-qualified field names to use when loading objects.

Returns:

true if the set of field names to load was updated as a result of this operation

removeFields

public boolean removeFields(Class cls,
                            Collection fields)

Removes fields from the set of field names to use when loading objects.

Returns:

true if the set of field names to load was updated as a result of this operation

clearFields

public void clearFields()

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

getLockTimeout

public int getLockTimeout()

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

Since:

3.1

setLockTimeout

public void setLockTimeout(int timeout)

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

Since:

3.1

getReadLockLevel

public int getReadLockLevel()

The lock level to use for locking loaded objects.

Since:

3.1

setReadLockLevel

public void setReadLockLevel(int level)

The lock level to use for locking loaded objects.

Since:

3.1

getWriteLockLevel

public int getWriteLockLevel()

The lock level to use for locking dirtied objects.

Since:

3.1

setWriteLockLevel

public void setWriteLockLevel(int level)

The lock level to use for locking dirtied objects.

Since:

3.1

newResultList

public ResultList newResultList(ResultObjectProvider rop)

Return a new result list for the current fetch configuration.

copy

public void copy(FetchConfiguration fetch)

Copy the state from the given fetch configuration to this one.

clone

public Object clone()

Fetch configurations are cloneable.

Overrides:

clone in class Object