net.wotonomy.control
Class EOFetchSpecification

java.lang.Object
  net.wotonomy.control.EOFetchSpecification

All Implemented Interfaces:

EOKeyValueArchiving

public class EOFetchSpecification
extends java.lang.Object
implements EOKeyValueArchiving

EOFetchSpecification defines the parameters used to request objects from an EOObjectStore. They are commonly created and passed to a EODataSource which fetches from its EOEditingContext, which passes the call up to its root EOObjectStore's objectsWithFetchSpecification method.

Version:

$Revision: 894 $

Author:

michael@mpowers.net, $Author: cgruber $

Constructor Summary

EOFetchSpecification()
Default constructor initializes internal state.

EOFetchSpecification(java.lang.String anEntityName, EOQualifier aQualifier, java.util.List aSortOrderingList)
Constructs a fetch specification for the specified entity type using the specified qualifier and sort ordering.

EOFetchSpecification(java.lang.String anEntityName, EOQualifier aQualifier, net.wotonomy.foundation.NSArray aSortOrderingList, boolean usesDistinct, boolean isDeep, java.util.Map aHintMap)
Constructs a fetch specification for the specified entity type using the specified qualifier and sort ordering, distinct flag, deep flag, and hints dictionary.

Method Summary

java.lang.Object	clone() Implemented to return a new fetch specification that is a deep copy of this one.
static java.lang.Object	decodeWithKeyValueUnarchiver(EOKeyValueUnarchiver unarch)
void	encodeWithKeyValueArchiver(EOKeyValueArchiver arch)
java.lang.String	entityName() Returns the name of the entity fetched by this fetch spec.
boolean	fetchesRawRows() Returns whether this fetch spec will fetch raw rows.
int	fetchLimit() Returns the current fetch limit.
static EOFetchSpecification	fetchSpecificationNamed(java.lang.String name, java.lang.String entityName) Convenience to return the named fetch specification from the class description corresponding to the specified entity name.
EOFetchSpecification	fetchSpecificationWithQualifierBindings(java.util.Map aBindingMap) Returns a fetch specification that resolves the bindings in the specified map.
net.wotonomy.foundation.NSDictionary	hints() Returns a Map containing the hints used by this fetch specification, or null if no hints have been specified.
boolean	isDeep() Returns whether entities related to the primary entities are fetched by this fetch spec.
boolean	locksObjects() Returns whether this data source should lock objects that are fetched.
net.wotonomy.foundation.NSArray	prefetchingRelationshipKeyPaths() Returns a List of relationships for the fetched objects that should also be fetched, or null if no such list has been specified.
boolean	promptsAfterFetchLimit() Returns whether the user should be prompted to continue when the fetch limit has been exceeded.
EOQualifier	qualifier() Returns the qualifier used by this fetch specification, or null if none has been specified.
net.wotonomy.foundation.NSArray	rawRowKeyPaths() Returns a List of keys or key paths for which values should be returned when fetching raw rows, or null if no raw row key paths have been specified.
boolean	refreshesRefetchedObjects() Returns whether fetched objects should replace modified versions already fetched into an editing context.
boolean	requiresAllQualifierBindingVariables() Returns whether all qualifier bindings must be specified in order to fetch.
void	setEntityName(java.lang.String aName) Sets the name of the entity fetched by this spec.
void	setFetchesRawRows(boolean shouldFetchRawRows) Sets whether this fetch spec will return raw rows.
void	setFetchLimit(int aLimit) Sets the limit on the number of records returned for this fetch spec.
void	setHints(java.util.Map aHintMap) Sets the hints passed by this fetch spec.
void	setIsDeep(boolean isDeep) Sets whether this fetch specification fetches deeply.
void	setLocksObjects(boolean shouldLockObjects) Sets whether this fetch spec locks objects that are returned by the fetch.
void	setPrefetchingRelationshipKeyPaths(java.util.List aKeyPathList) Sets the prefetch key paths that should be used as an optimization hint to the server.
void	setPromptsAfterFetchLimit(boolean shouldPrompt) Sets whether the user should be prompted when the fetch limit has been reached.
void	setQualifier(EOQualifier aQualifier) Sets the qualifier used by this fetch specification.
void	setRawRowKeyPaths(java.util.List aKeyPathList) Sets the key paths to be returned if this fetch spec is returning raw rows.
void	setRefreshesRefetchedObjects(boolean shouldRefresh) Sets whether modified objects in an editing context should be replaced by newer versions returned by this fetch spec.
void	setRequiresAllQualifierBindingVariables(boolean shouldRequireAll) Sets whether this fetch spec should require all bindings to be resolved before executing.
void	setSortOrderings(java.util.List aSortList) Sets the sort orderings used by this fetch spec.
void	setUsesDistinct(boolean shouldUseDistinct) Sets whether this fetch spec should return only distinct objects.
net.wotonomy.foundation.NSArray	sortOrderings() Returns a List of the sort orderings used by this fetch spec, or null if none have been specified.
java.lang.String	toString() Returns a string representation of this fetch specification.
boolean	usesDistinct() Returns whether this fetch specification will return only one reference to each distinct object returned by the fetch.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

EOFetchSpecification

public EOFetchSpecification()

Default constructor initializes internal state.

EOFetchSpecification

public EOFetchSpecification(java.lang.String anEntityName,
                            EOQualifier aQualifier,
                            java.util.List aSortOrderingList)

Constructs a fetch specification for the specified entity type using the specified qualifier and sort ordering.

EOFetchSpecification

public EOFetchSpecification(java.lang.String anEntityName,
                            EOQualifier aQualifier,
                            net.wotonomy.foundation.NSArray aSortOrderingList,
                            boolean usesDistinct,
                            boolean isDeep,
                            java.util.Map aHintMap)

Constructs a fetch specification for the specified entity type using the specified qualifier and sort ordering, distinct flag, deep flag, and hints dictionary.

Method Detail

fetchSpecificationNamed

public static EOFetchSpecification fetchSpecificationNamed(java.lang.String name,
                                                           java.lang.String entityName)

Convenience to return the named fetch specification from the class description corresponding to the specified entity name. Returns null if either entityName or spec name cannot be resolved.

clone

public java.lang.Object clone()

Implemented to return a new fetch specification that is a deep copy of this one.

Overrides:

clone in class java.lang.Object

entityName

public java.lang.String entityName()

Returns the name of the entity fetched by this fetch spec.

fetchLimit

public int fetchLimit()

Returns the current fetch limit. A fetch limit of zero indicates no fetch limit. Zero is the default.

fetchesRawRows

public boolean fetchesRawRows()

Returns whether this fetch spec will fetch raw rows. Default is false.

fetchSpecificationWithQualifierBindings

public EOFetchSpecification fetchSpecificationWithQualifierBindings(java.util.Map aBindingMap)

Returns a fetch specification that resolves the bindings in the specified map.

hints

public net.wotonomy.foundation.NSDictionary hints()

Returns a Map containing the hints used by this fetch specification, or null if no hints have been specified.

isDeep

public boolean isDeep()

Returns whether entities related to the primary entities are fetched by this fetch spec. If true, all relationships whose destinations meet the qualifier criteria will be returned in addition to primary results. If false, only the primary entities will be returned. Default is true.

locksObjects

public boolean locksObjects()

Returns whether this data source should lock objects that are fetched. Default is false.

prefetchingRelationshipKeyPaths

public net.wotonomy.foundation.NSArray prefetchingRelationshipKeyPaths()

Returns a List of relationships for the fetched objects that should also be fetched, or null if no such list has been specified. Use this to avoid additional calls to the server to fetch relationships that you know you will use. NOTE: wotonomy allows you to specify non-relational keys as well.

promptsAfterFetchLimit

public boolean promptsAfterFetchLimit()

Returns whether the user should be prompted to continue when the fetch limit has been exceeded. Default is false.

qualifier

public EOQualifier qualifier()

Returns the qualifier used by this fetch specification, or null if none has been specified.

rawRowKeyPaths

public net.wotonomy.foundation.NSArray rawRowKeyPaths()

Returns a List of keys or key paths for which values should be returned when fetching raw rows, or null if no raw row key paths have been specified.

refreshesRefetchedObjects

public boolean refreshesRefetchedObjects()

Returns whether fetched objects should replace modified versions already fetched into an editing context. If true, those changes will be lost. Default is false.

requiresAllQualifierBindingVariables

public boolean requiresAllQualifierBindingVariables()

Returns whether all qualifier bindings must be specified in order to fetch. If true, an exception is thrown if unspecified bindings exist. If false, unspecified bindings will be removed from the qualifier. Default is false.

setEntityName

public void setEntityName(java.lang.String aName)

Sets the name of the entity fetched by this spec.

setFetchesRawRows

public void setFetchesRawRows(boolean shouldFetchRawRows)

Sets whether this fetch spec will return raw rows.

setFetchLimit

public void setFetchLimit(int aLimit)

Sets the limit on the number of records returned for this fetch spec. Zero indicates no limit on fetches.

setHints

public void setHints(java.util.Map aHintMap)

Sets the hints passed by this fetch spec.

setIsDeep

public void setIsDeep(boolean isDeep)

Sets whether this fetch specification fetches deeply.

setLocksObjects

public void setLocksObjects(boolean shouldLockObjects)

Sets whether this fetch spec locks objects that are returned by the fetch.

setPrefetchingRelationshipKeyPaths

public void setPrefetchingRelationshipKeyPaths(java.util.List aKeyPathList)

Sets the prefetch key paths that should be used as an optimization hint to the server. NOTE: wotonomy allows you to specify non-relationship keys as well.

setPromptsAfterFetchLimit

public void setPromptsAfterFetchLimit(boolean shouldPrompt)

Sets whether the user should be prompted when the fetch limit has been reached.

setQualifier

public void setQualifier(EOQualifier aQualifier)

Sets the qualifier used by this fetch specification.

setRawRowKeyPaths

public void setRawRowKeyPaths(java.util.List aKeyPathList)

Sets the key paths to be returned if this fetch spec is returning raw rows.

setRefreshesRefetchedObjects

public void setRefreshesRefetchedObjects(boolean shouldRefresh)

Sets whether modified objects in an editing context should be replaced by newer versions returned by this fetch spec.

setRequiresAllQualifierBindingVariables

public void setRequiresAllQualifierBindingVariables(boolean shouldRequireAll)

Sets whether this fetch spec should require all bindings to be resolved before executing.

setSortOrderings

public void setSortOrderings(java.util.List aSortList)

Sets the sort orderings used by this fetch spec.

setUsesDistinct

public void setUsesDistinct(boolean shouldUseDistinct)

Sets whether this fetch spec should return only distinct objects.

sortOrderings

public net.wotonomy.foundation.NSArray sortOrderings()

Returns a List of the sort orderings used by this fetch spec, or null if none have been specified.

toString

public java.lang.String toString()

Returns a string representation of this fetch specification.

Overrides:

toString in class java.lang.Object

usesDistinct

public boolean usesDistinct()

Returns whether this fetch specification will return only one reference to each distinct object returned by the fetch. Default is false.

encodeWithKeyValueArchiver

public void encodeWithKeyValueArchiver(EOKeyValueArchiver arch)

Specified by:

encodeWithKeyValueArchiver in interface EOKeyValueArchiving

decodeWithKeyValueUnarchiver

public static java.lang.Object decodeWithKeyValueUnarchiver(EOKeyValueUnarchiver unarch)