EOFetchSpecification

Inherits From:
NSObject

Conforms To: NSCoding
NSCopying
NSObject (NSObject)

Declared in: EOControl/EOFetchSpecification.h

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.

Adopted Protocols

NSCoding

- encodeWithCoder:

- initWithCoder:

NSCopying

- copyWithZone:

Creating instances

+ fetchSpecificationWithEntityName:qualifier:sortOrderings:

- fetchSpecificationWithQualifierBindings:

- init

- initWithEntityName:qualifier:sortOrderings:usesDistinct:
isDeep:hints:

Setting the qualifier

- setQualifier:

- qualifier

Sorting

- setSortOrderings:

- sortOrderings:

Removing duplicates

- setUsesDistinct:

- usesDistinct:

Fetching objects in an inheritance hierarchy

- setIsDeep:

- isDeep

- setEntityName:

- entityName

Controlling fetching behavior

- setFetchLimit:

- fetchLimit

- setFetchesRawRows:

- fetchesRawRows

- setPrefetchingRelationshipKeyPaths:

- prefetchingRelationshipKeyPaths

- setPromptsAfterFetchLimit:

- promptsAfterFetchLimit

- setRawRowKeyPaths:

- rawRowKeyPaths

- setRequiresAllQualifierBindingVariables:

- requiresAllQualifierBindingVariables

- setHints:

- hints

Locking objects

- setLocksObjects:

- locksObjects

Refreshing refetched objects

- setRefreshesRefetchedObjects:

- refreshesRefetchedObjects

fetchSpecificationWithEntityName:qualifier:sortOrderings:

Returns an EOFetchSpecification for entityName, using qualifier to select and sortOrderings to sort the results. The EOFetchSpecification created with this method is deep, doesn't perform distinct selection, and has no hints.

See also: - initWithEntityName:qualifier:sortOrderings:usesDistinct:isDeep:hints:

entityName

Returns the name of the entity to be fetched.

See also: - isDeep , - setEntityName:

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.

See also: - setFetchLimit:

fetchesRawRows

Returns YES if rawRowKeyPaths returns non-nil.

See also: - rawRowKeyPaths , - setFetchesRawRows:

fetchSpecificationWithQualifierBindings:

Applies bindings from bindings to its 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. Invoke setRequiresAllQualifierBindingVariables: with an argument of YES to force an exception to be raised if a binding is missing during variable substitution.

See also: - setRequiresAllQualifierBindingVariables:

hints

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

See also: - setHints:

init

Initializes a new EOFetchSpecification with no state, except that it fetches deeply and doesn't use distinct. Use the set... methods to add other parts of the specification. This is the designated initializer for the EOFetchSpecification class. Returns self .

See also: - initWithEntityName:qualifier:sortOrderings:usesDistinct:isDeep:hints:

initWithEntityName:qualifier:sortOrderings:usesDistinct:isDeep:hints:

Initializes a new EOFetchSpecification with the given arguments. Returns self .

See also: + fetchSpecificationWithEntityName:qualifier:sortOrderings:

isDeep

Returns YES if a fetch should include sub-entities of the receiver's entity, NO 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.

See also: - setIsDeep:

locksObjects

Returns YES if a fetch should result in the selected objects being locked in the data repository, NO if it shouldn't. The default is NO.

See also: - setLocksObjects:

prefetchingRelationshipKeyPaths

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

See also: - setPrefetchingRelationshipKeyPaths:

promptsAfterFetchLimit

Returns whether to prompt user after the fetch limit has been reached. Default is NO.

See also: - setPromptsAfterFetchLimit:

qualifier

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

See also: - setQualifier:

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 nil, 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:entityNamed: method.

See also: - fetchesRawRows , - setFetchesRawRows: , - setRawRowKeyPaths:

refreshesRefetchedObjects

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

See also: - setRefreshesRefetchedObjects:

requiresAllQualifierBindingVariables

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

See also: - setRequiresAllQualifierBindingVariables:

setEntityName:

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

See also: - isDeep , - entityName

setFetchesRawRows:

Sets the behavior for fetching raw rows. If set to YES, the behavior is the same as if setRawRowKeyPaths: were called with an empty array. If set to NO, the behavior is as if setRawRowKeyPaths: were called with a nil argument.

See also: - fetchesRawRows , - setRawRowKeyPaths: , - rawRowKeyPaths

setFetchLimit:

Sets 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.

See also: - fetchLimit

setHints:

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 EOCustomQueryExpressionHintKey. EODatabaseContext is the only class in Enterprise Objects Framework that defines fetch specification hints. For information about EODatabaseContext's hints, see the EODatabaseContext class specification.

See also: - hints

setIsDeep:

- (void)setIsDeep: (BOOL)flag

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

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

See also: - isDeep

setLocksObjects:

Controls whether a fetch should result in the selected objects being locked in the data repository. If flag is YES it should, if NO it shouldn't. The default is NO.

See also: - locksObjects

setPrefetchingRelationshipKeyPaths:

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

See also: - prefetchingRelationshipKeyPaths

setPromptsAfterFetchLimit:

Sets whether to prompt user after the fetch limit has been reached. Default is NO.

See also: - promptsAfterFetchLimit

setQualifier:

Sets the receiver's qualifier to qualifier.

See also: - qualifier

setRawRowKeyPaths:

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 nil, 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:entityNamed: method.

See also: - fetchesRawRows , - rawRowKeyPaths , - setFetchesRawRows:

setRefreshesRefetchedObjects:

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

For example, suppose that you fetch an employee object and then refetch it, 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 your first fetch. To keep your employee in sync with the employee data in the external repository, you'd need to replace the employee's outdated values with the new ones. On the other hand, if you were to fetch the employee, change it, and then refetch it, you would not want to refresh the employee. If you to refreshed it-whether or not another application had changed the employee-you would lose the changes that you had made to the object.

You can get finer-grain control on an EODatabaseContext's refreshing behavior than you can with an EOFetchSpecification by using the delegate method databaseContext:shouldUpdateCurrentSnapshot:newSnapshot:globalID:databaseChannel: . For more information see the EODatabaseContext class specification.

See also: - refreshesRefetchedObjects

setRequiresAllQualifierBindingVariables:

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

See also: - fetchSpecificationWithQualifierBindings: , - requiresAllQualifierBindingVariables

setSortOrderings:

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.

See also: - sortedArrayUsingKeyOrderArray: (NSArray Additions), - sortOrderings:

setUsesDistinct:

Controls whether duplicate objects or records are removed after fetching. If flag is YES they're removed; if flag is NO they aren't. EOFetchSpecifications by default don't use distinct.

See also: - usesDistinct:

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.

See also: - sortedArrayUsingKeyOrderArray: (NSArray Additions), - setSortOrderings:

usesDistinct:

Returns YES if duplicate objects or records are removed after fetching, NO if they aren't. EOFetchSpecifications by default don't use distinct.

See also: - setUsesDistinct: