com.webobjects.eocontrol
Class EOFetchSpecification

java.lang.Object
  |
  +--com.webobjects.eocontrol.EOFetchSpecification

All Implemented Interfaces:

Cloneable, EOKeyValueArchiving, NSCoding, Serializable

public class EOFetchSpecification

extends Object

implements Serializable, Cloneable, NSCoding, EOKeyValueArchiving

An EOFetchSpecification collects the criteria needed to select and order a group of records or enterprise objects, whether from an external repository such as a relational database or an internal store such as an EOEditingContext. An EOFetchSpecification contains these elements:

• The name of an entity for which to fetch records or objects. This is the only mandatory element.
• An EOQualifier, indicating which properties to select by and how to do so.
• An array of EOSortOrderings, which indicate how the selected records or objects should be ordered when fetched.
• An indicator of whether to produce distinct results or not. Normally if a record or object is selected several times, such as when forming a join, it appears several times in the fetched results. An EOFetchSpecification that makes distinct selections causes duplicates to be filtered out, so each record or object selected appears exactly once in the result set.
• An indicator of whether to fetch deeply or not. This is used with inheritance hierarchies when fetching for an entity with sub entities. A deep fetch produces all instances of the entity and its sub entities, while a shallow fetch produces instances only of the entity in the fetch specification.
• A fetch limit indicating how many objects to fetch before giving the user or program an opportunity to intervene.
• A listing of relationships for which the destination of the relationship should be prefetched along with the entity being fetched. Proper use of this feature allows for substantially increased performance in some cases.
• A dictionary of hints, which an EODatabaseContext or other object can use to optimize or alter the results of the fetch.

EOFetchSpecifications are most often used with the method objectsWithFetchSpecification, defined by EOObjectStore, EOEditingContext, and EODatabaseContext. EOAdaptorChannel and EODatabaseChannel also define methods that use EOFetchSpecifications.

See Also:

Serialized Form

Nested Class Summary

Nested classes inherited from class com.webobjects.foundation.NSCoding

NSCoding.Support

Nested classes inherited from class com.webobjects.eocontrol.EOKeyValueArchiving

EOKeyValueArchiving.Awaking, EOKeyValueArchiving.FinishInitialization, EOKeyValueArchiving.Support

Constructor Summary

EOFetchSpecification()
Creates a new EOFetchSpecification.

EOFetchSpecification(String entityName, EOQualifier qualifier, NSArray sortOrderings)
Creates a new EOFetchSpecification with the arguments specified.

EOFetchSpecification(String entityName, EOQualifier qualifier, NSArray sortOrderings, boolean usesDistinct, boolean isDeep, NSDictionary hints)
Creates a new EOFetchSpecification with the arguments specified.

Method Summary

Class	classForCoder() Allows the receiver, before being encoded, to substitute a class other than its own in a coder.
Object	clone() Implementation of the java.lang.Cloneable interface.
static Object	decodeObject(NSCoder coder) (Re)creates an object based on type information and data stored in coder.
static Object	decodeWithKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver) (Re)creates an object based on information in unarchiver.
void	encodeWithCoder(NSCoder coder) Archives the receiver's type information and data into coder.
void	encodeWithKeyValueArchiver(EOKeyValueArchiver archiver) Archives the receiver's into archiver.
String	entityName() Returns the name of the entity to be fetched.
boolean	fetchesRawRows() Returns whether the rawRowKeyPaths method returns non-null.
int	fetchLimit() Returns the fetch limit value which indicates the maximum number of objects to fetch.
static EOFetchSpecification	fetchSpecificationNamed(String name, String entityName) Returns the fetch specification that the entity specified by entityName associates with the fetch specification name name.
EOFetchSpecification	fetchSpecificationWithQualifierBindings(NSDictionary bindings) Applies bindings from bindings to the receiver's qualifier if there is one, and returns a new fetch specification that can be used in a fetch.
NSDictionary	hints() Returns the receiver's hints, which other objects can use to alter or optimize fetch operations.
boolean	isDeep() Returns true if a fetch should include sub-entities of the receiver's entity, false if it shouldn't.
boolean	locksObjects() Returns true if a fetch should result in the selected objects being locked in the data repository, false if it shouldn't.
NSArray	prefetchingRelationshipKeyPaths() Returns an array of relationship key paths that should be prefetched along with the main fetch.
boolean	promptsAfterFetchLimit() Returns whether to prompt the user after the fetch limit has been reached.
EOQualifier	qualifier() Returns the EOQualifier that indicates which records or objects the receiver is to fetch.
NSArray	rawRowKeyPaths() Returns an array of attribute key paths that should be fetched as raw data and returned as an array of dictionaries (instead of the normal result of full objects).
boolean	refreshesRefetchedObjects() Returns true if existing objects are overwritten with fetched values when they've been updated or changed.
boolean	requiresAllQualifierBindingVariables() Returns true to indicate that a missing binding will cause an exception to be raised during variable substitution.
void	setEntityName(String entityName) Sets the name of the root entity to be fetched to entityName.
void	setFetchesRawRows(boolean fetchesRawRows) Sets the behavior for fetching raw rows.
void	setFetchLimit(int fetchLimit) Sets the fetch limit value which indicates the maximum number of objects to fetch.
void	setHints(NSDictionary hints) Sets the receiver's hints to hints.
void	setIsDeep(boolean isDeep) Sets whether a fetch should include sub-entities of the receiver's entity.
void	setLocksObjects(boolean locksObjects) Sets whether a fetch should result in the selected objects being locked in the data repository.
void	setPrefetchingRelationshipKeyPaths(NSArray keyPaths) Sets an array of relationship key paths that should be prefetched along with the main fetch.
void	setPromptsAfterFetchLimit(boolean value) Sets whether or not the application's message handler is notified when the fetch limit has been reached, enabling the message handler to prompt the user whether to continue to fetch more rows.
void	setQualifier(EOQualifier qualifier) Sets this fetch specification's qualifier to qualifier.
void	setRawRowKeyPaths(NSArray keyPaths) Sets an array of attribute key paths that should be fetched as raw data and returned as an array of dictionaries (instead of the normal result of full objects).
void	setRefreshesRefetchedObjects(boolean refreshes) Sets whether existing objects are overwritten with fetched values when they have been updated or changed.
void	setRequiresAllQualifierBindingVariables(boolean requires) Sets the behavior when a missing binding is encountered during variable substitution.
void	setSortOrderings(NSArray sortOrderings) Sets the receiver's array of EOSortOrderings to sortOrderings.
void	setUsesDistinct(boolean usesDistinct) Sets whether duplicate objects or records are removed after fetching.
NSArray	sortOrderings() Returns the receiver's array of EOSortOrderings.
String	toString() Returns a String representation of the receiver.
boolean	usesDistinct() Returns true if duplicate objects or records are removed after fetching, false if they aren't.

Methods inherited from class java.lang.Object

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

Constructor Detail

EOFetchSpecification

public EOFetchSpecification()

Creates a new EOFetchSpecification. By default, fetch specifications fetch deeply and don't use distinct. Before using the fetch specification, you have to set more parameters, at minimum the entity name.

See Also:

setEntityName(String)

EOFetchSpecification

public EOFetchSpecification(String entityName,
                            EOQualifier qualifier,
                            NSArray sortOrderings,
                            boolean usesDistinct,
                            boolean isDeep,
                            NSDictionary hints)

Creates a new EOFetchSpecification with the arguments specified. Minimally, you must specify an entity name. If qualifier is empty, such as an EOAndQualifier or EOOrQualifier whose array of elements contains zero qualifiers, this fetch specification will have its qualifier set to null

Parameters:

entityName - the name of the entity to fetch

qualifier - the qualifier to use for fetching

sortOrderings - the sort orderings to use for fetching

usesDistinct - true if the fetch specification should be distinct; false otherwise

isDeep - true if the fetch specification should be deep; false otherwise

hints - the hints to use for fetching

EOFetchSpecification

public EOFetchSpecification(String entityName,
                            EOQualifier qualifier,
                            NSArray sortOrderings)

Creates a new EOFetchSpecification with the arguments specified. Minimally, you must specify an entity name. The new EOFetchSpecification is deep, doesn't perform distinct selection, and has no hints. If qualifier is empty, such as an EOAndQualifier or EOOrQualifier whose array of elements contains zero qualifiers, this fetch specification will have its qualifier set to null

Parameters:

entityName - the name of the entity to fetch

qualifier - the qualifier to use for fetching

sortOrderings - the sort orderings to use for fetching

Method Detail

classForCoder

public Class classForCoder()

Allows the receiver, before being encoded, to substitute a class other than its own in a coder.

Specified by:

classForCoder in interface NSCoding

Returns:

the class a coder should record

See Also:

encodeWithCoder(NSCoder), decodeObject(NSCoder), NSCoding

clone

public Object clone()

Implementation of the java.lang.Cloneable interface.

Overrides:

clone in class Object

Returns:

a clone of the receiver

decodeObject

public static Object decodeObject(NSCoder coder)

(Re)creates an object based on type information and data stored in coder.

Returns:

an object (re)created from the data in coder

See Also:

encodeWithCoder(NSCoder coder), classForCoder(), NSCoding

decodeWithKeyValueUnarchiver

public static Object decodeWithKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver)

(Re)creates an object based on information in unarchiver.

Parameters:

unarchiver - the key-value unarchiver with which the receiver should be decoded

Returns:

an object (re)created from the data in unarchiver

See Also:

EOKeyValueArchiving

encodeWithCoder

public void encodeWithCoder(NSCoder coder)

Archives the receiver's type information and data into coder. The receiver can then be recreated using decodeObject. Custom type information can be used by overriding classForCoder.

Specified by:

encodeWithCoder in interface NSCoding

Parameters:

coder - the coder storing object type information along with an object's data

See Also:

decodeObject(NSCoder), classForCoder(), NSCoding

encodeWithKeyValueArchiver

public void encodeWithKeyValueArchiver(EOKeyValueArchiver archiver)

Archives the receiver's into archiver. The receiver can then be recreated using decodeWithKeyValueUnarchiver.

Specified by:

encodeWithKeyValueArchiver in interface EOKeyValueArchiving

Parameters:

archiver - the key-value archiver with which the receiver should be encoded

See Also:

EOKeyValueArchiving

entityName

public String entityName()

Returns the name of the entity to be fetched.

Returns:

the name of the entity to be fetched

See Also:

setEntityName(String), isDeep()

fetchLimit

public int fetchLimit()

Returns the fetch limit value which indicates the maximum number of objects to fetch. Depending on the value of promptsAfterFetchLimit, the EODatabaseContext will either stop fetching objects when this limit is reached or it will ask the editing context's message handler to prompt the user as to whether or not it should continue fetching. Use 0 (zero) to indicate no fetch limit. The default is 0.

Returns:

the fetch limit value which indicates the maximum number of objects to fetch

See Also:

setFetchLimit(int), promptsAfterFetchLimit(), setPromptsAfterFetchLimit(boolean)

fetchSpecificationNamed

public static EOFetchSpecification fetchSpecificationNamed(String name,
                                                           String entityName)

Returns the fetch specification that the entity specified by entityName associates with the fetch specification name name.

Parameters:

name - the fetch specification name

entityName - the name of an entity for which to fetch records or objects

Returns:

the named fetch specification

fetchSpecificationWithQualifierBindings

public EOFetchSpecification fetchSpecificationWithQualifierBindings(NSDictionary bindings)

Applies bindings from bindings to the receiver's qualifier if there is one, and returns a new fetch specification that can be used in a fetch. The default behavior is to prune any nodes for which there are no bindings. You can invoke setRequiresAllQualifierBindingVariables with a true argument to force an exception to be raised if a binding is missing during variable substitution.

Parameters:

bindings - the bindings which are applied to the receiver's qualifier

Returns:

the new fetch specification that can be used in a fetch

See Also:

setRequiresAllQualifierBindingVariables(boolean)

fetchesRawRows

public boolean fetchesRawRows()

Returns whether the rawRowKeyPaths method returns non-null.

Returns:

true if rawRowKeyPaths returns non-null; false otherwise

See Also:

rawRowKeyPaths(), setFetchesRawRows(boolean)

hints

public NSDictionary hints()

Returns the receiver's hints, which other objects can use to alter or optimize fetch operations.

Returns:

the receiver's hints

See Also:

setHints(NSDictionary)

isDeep

public boolean isDeep()

Returns true if a fetch should include sub-entities of the receiver's entity, false if it shouldn't. EOFetchSpecifications are deep by default.

For example, if you have a Person entity with two sub-entities, Employee and Customer, fetching Persons deeply also fetches all Employees and Customers matching the qualifier. Fetching Persons shallowly fetches only Persons matching the qualifier.

Returns:

true if a fetch should include sub entities of the receiver's entity; false otherwise

See Also:

setIsDeep(boolean)

locksObjects

public boolean locksObjects()

Returns true if a fetch should result in the selected objects being locked in the data repository, false if it shouldn't. The default is false. Note that unnecessary locking could severely degrade the performance of certain repository operations.

Returns:

true if a fetch should result in the selected objects being locked in the data repository; false otherwise

See Also:

setLocksObjects(boolean)

prefetchingRelationshipKeyPaths

public NSArray prefetchingRelationshipKeyPaths()

Returns an array of relationship key paths that should be prefetched along with the main fetch. For example, if fetching from a Movie entity, you might specify paths of the form: ("directors","roles.talent", "plotSummary").

Returns:

an array of relationship key paths to prefetch

See Also:

setPrefetchingRelationshipKeyPaths(NSArray)

promptsAfterFetchLimit

public boolean promptsAfterFetchLimit()

Returns whether to prompt the user after the fetch limit has been reached. The default is false.

Returns:

true if the user should be prompted after the fetch limit has been reached; false if fetching should just stop at that point

See Also:

setPromptsAfterFetchLimit(boolean), fetchLimit(), setFetchLimit(int)

qualifier

public EOQualifier qualifier()

Returns the EOQualifier that indicates which records or objects the receiver is to fetch.

Returns:

the EOQualifier that indicates which records or objects to fetch

See Also:

setQualifier(EOQualifier)

rawRowKeyPaths

public NSArray rawRowKeyPaths()

Returns an array of attribute key paths that should be fetched as raw data and returned as an array of dictionaries (instead of the normal result of full objects). The raw fetch can increase speed, but forgoes most of the benefits of full Enterprise Objects. The default value is null, indicating that full objects will be returned from the fetch. An empty array may be used to indicate that the fetch should query the entity named by the fetch specification using the method attributesToFetch. As long as the primary key attributes are included in the raw attributes, the raw row may be used to generate a fault for the corresponding object using EOEditingContext's faultForRawRow method.

Returns:

an array of attribute key paths to be fetched as raw data

See Also:

setFetchesRawRows(boolean), setRawRowKeyPaths(NSArray), EOEditingContext.faultForRawRow(NSDictionary, String), EOEditingContext.faultForRawRow(NSDictionary, String, EOEditingContext)

refreshesRefetchedObjects

public boolean refreshesRefetchedObjects()

Returns true if existing objects are overwritten with fetched values when they've been updated or changed. Returns false if existing objects aren't touched when their data is refetched (the fetched data is simply discarded). The default is false. Note that this setting does not affect relationships.

Returns:

true if existing objects are overwritten with fetched values when they've been updated or changed; false otherwise

See Also:

setRefreshesRefetchedObjects(boolean)

requiresAllQualifierBindingVariables

public boolean requiresAllQualifierBindingVariables()

Returns true to indicate that a missing binding will cause an exception to be raised during variable substitution. The default value is false, which says to prune any nodes for which there are no bindings.

Returns:

true if a missing binding should cause an exception; false otherwise

setEntityName

public void setEntityName(String entityName)

Sets the name of the root entity to be fetched to entityName.

Parameters:

entityName - the name of the root entity to be fetched

See Also:

isDeep(), entityName()

setFetchLimit

public void setFetchLimit(int fetchLimit)

Sets the fetch limit value which indicates the maximum number of objects to fetch. Depending on the value of promptsAfterFetchLimit, the EODatabaseContext either stops fetching objects when this limit is reached or asks the editing context's message handler to prompt the user as to whether or not it should continue fetching. Use 0 (zero) to indicate no fetch limit. The default is 0.

Parameters:

fetchLimit - the fetch limit value which indicates the maximum number of objects to fetch

See Also:

fetchLimit(), promptsAfterFetchLimit(), setPromptsAfterFetchLimit(boolean)

setFetchesRawRows

public void setFetchesRawRows(boolean fetchesRawRows)

Sets the behavior for fetching raw rows. If set to true, the behavior is the same as if setRawRowKeyPaths were called with an empty array (which causes fetchesRawRows to return true). If set to false, the behavior is as if setRawRowKeyPaths were called with null as the argument (which causes fetchesRawRows to return false). Note that if rawRowKeyPaths has already had a value assigned to it, using this method will overwrite that value.

Parameters:

fetchesRawRows - true if rawRowKeyPaths returns non-null; false otherwise

See Also:

rawRowKeyPaths(), fetchesRawRows()

setHints

public void setHints(NSDictionary hints)

Sets the receiver's hints to hints. Any object that uses an EOFetchSpecification can define its own hints that it uses to alter or optimize fetch operations. For example, EODatabaseContext uses a hint identified by the key CustomQueryExpressionHintKey. EODatabaseContext is the only class in the standard Enterprise Objects Framework that defines fetch specification hints.

Parameters:

hints - the receiver's hints

See Also:

hints(), EODatabaseContext

setIsDeep

public void setIsDeep(boolean isDeep)

Sets whether a fetch should include sub-entities of the receiver's entity. If flag is true, sub-entities are also fetched; if flag is false, they aren't. EOFetchSpecifications are deep by default.

For example, if you have a Person entity with two sub-entities and subclasses, Employee and Customer, fetching Persons deeply also fetches all Employees and Customers matching the qualifier. Fetching Persons shallowly fetches only Persons matching the qualifier.

Parameters:

isDeep - true if sub-entities should be fetched; false otherwise

See Also:

isDeep()

setLocksObjects

public void setLocksObjects(boolean locksObjects)

Sets whether a fetch should result in the selected objects being locked in the data repository. If flag is true it should, if flag is false it shouldn't. The default is false. Note that unnecessary locking could severely degrade the performance of certain repository operations.

Parameters:

locksObjects - true if the selected objects should be locked in the data repository; false otherwise

See Also:

locksObjects()

setPrefetchingRelationshipKeyPaths

public void setPrefetchingRelationshipKeyPaths(NSArray keyPaths)

Sets an array of relationship key paths that should be prefetched along with the main fetch. For example, if fetching from a Movie entity, you might specify paths of the form: ("directors","roles.talent", "plotSummary").

Prefetching increases the initial fetch cost, but it can improve overall performance by reducing the number of round trips made to the database server. Assigning relationships to prefetch also has an effect on how a fetch specification refreshes.

Refreshing refers to existing objects being overwritten with fetched values. This allows the application to see changes to the database that have been made by someone else. Normally, when an EOFetchSpecification is set to refresh using setRefreshesRefetchedObjects, it only refreshes the objects you are fetching. For example, if you fetch employees, you do not also fetch the employees' departments. However, if you prefetch relationships, the refetch is propagated for all of the relationships specified.

Parameters:

keyPaths - an array of relationship key paths to be prefetched

See Also:

prefetchingRelationshipKeyPaths(), setRefreshesRefetchedObjects(boolean)

setPromptsAfterFetchLimit

public void setPromptsAfterFetchLimit(boolean value)

Sets whether or not the application's message handler is notified when the fetch limit has been reached, enabling the message handler to prompt the user whether to continue to fetch more rows. If value is false, or if the application has no message handler, fetching stops after fetchLimit rows have been fetched. The default is false.

Note that only the EOInterface layer provides a built-in message handler implementation. Standard WebObjects applications must set the message handler directly and implement editingContextShouldContinueFetching to prompt the user in an appropriate form in order to make use of this feature.

Parameters:

value - true if the user should be prompted after the fetch limit has been reached; false if fetching should just stop at that point

See Also:

fetchLimit(), setFetchLimit(int), promptsAfterFetchLimit(), EOEditingContext.MessageHandler.editingContextShouldContinueFetching(EOEditingContext context, int count, int originalLimit, EOObjectStore objectStore)

setQualifier

public void setQualifier(EOQualifier qualifier)

Sets this fetch specification's qualifier to qualifier. If qualifier is empty, such as an EOAndQualifier or EOOrQualifier whose array of elements contains zero qualifiers, this fetch specification will have its qualifier set to null

Parameters:

qualifier - the qualifier

See Also:

qualifier()

setRawRowKeyPaths

public void setRawRowKeyPaths(NSArray keyPaths)

Sets an array of attribute key paths that should be fetched as raw data and returned as an array of dictionaries (instead of the normal result of full objects). The raw fetch can increase speed, but forgoes most of the benefits of full Enterprise Objects. The default value is null, indicating that full objects will be returned from the fetch. An empty array may be used to indicate that the fetch should query the entity named by the fetch specification using the method attributesToFetch. As long as the primary key attributes are included in the raw attributes, the raw row may be used to generate a fault for the corresponding object using EOEditingContext's faultForRawRow method.

Parameters:

keyPaths - an array of attribute key paths to be fetched as raw data

See Also:

rawRowKeyPaths(), setFetchesRawRows(boolean), EOEditingContext.faultForRawRow(NSDictionary, String), EOEditingContext.faultForRawRow(NSDictionary, String, EOEditingContext)

setRefreshesRefetchedObjects

public void setRefreshesRefetchedObjects(boolean refreshes)

Sets whether existing objects are overwritten with fetched values when they have been updated or changed. If refreshes is true, they are; if refreshes is false, they aren't (the fetched data is simply discarded). The default is false.

For example, suppose that an employee object is fetched and then refetched, without changing the employee between fetches. In this case you want to refresh the employee when you refetch it because another application might have updated the object since the first fetch. To keep the employee in sync with the employee data in the external repository you would need to replace the employee's outdated values with the new ones. On the other hand, if you have to fetch the employee, change it, and then refetch it, you would not want to refresh the employee. If you are to refresh it whether or not another application had changed the employee you would lose the changes that you have made to the object.

You can get finer grain control on an EODatabaseContext's refreshing behavior in the EOControl layer than you can with an EOFetchSpecification by using the delegate method databaseContextShouldUpdateCurrentSnapshot.

Parameters:

refreshes - true if existing objects are overwritten with fetched values; false otherwise

See Also:

refreshesRefetchedObjects(), EODatabaseContext, EODatabaseContext.Delegate

setRequiresAllQualifierBindingVariables

public void setRequiresAllQualifierBindingVariables(boolean requires)

Sets the behavior when a missing binding is encountered during variable substitution. If requires is true, then a missing binding will cause an exception to be raised during variable substitution. The default value is false, which says to prune any nodes for which there are no bindings.

Parameters:

requires - true if a missing binding should cause an exception; false otherwise

setSortOrderings

public void setSortOrderings(NSArray sortOrderings)

Sets the receiver's array of EOSortOrderings to sortOrderings. When a fetch is performed with the receiver, the results are sorted by applying each EOSortOrdering in the array (serially in lowest-array-index-first order).

Parameters:

sortOrderings - the array of EOSortOrderings

See Also:

sortOrderings()

setUsesDistinct

public void setUsesDistinct(boolean usesDistinct)

Sets whether duplicate objects or records are removed after fetching. If flag is true they are removed (that is, proper sets are returned). If flag is false they aren't (multisets are returned). EOFetchSpecifications by default don't use distinct.

Parameters:

usesDistinct - true if duplicate objects or records should be removed; false otherwise

See Also:

usesDistinct()

sortOrderings

public NSArray sortOrderings()

Returns the receiver's array of EOSortOrderings. When a fetch is performed with the receiver, the results are sorted by applying each EOSortOrdering in the array (serially in lowest-array-index-first order).

Returns:

the receiver's array of EOSortOrderings

See Also:

setSortOrderings(NSArray)

toString

public String toString()

Returns a String representation of the receiver.

Overrides:

toString in class Object

Returns:

a String representation of the receiver

usesDistinct

public boolean usesDistinct()

Returns true if duplicate objects or records are removed after fetching, false if they aren't. EOFetchSpecifications by default don't use distinct (that is, they return multisets).

Returns:

true if duplicate objects or records are removed; false otherwise

See Also:

setUsesDistinct(boolean)