EOFetchSpecification
- Inherits from:
- NSObject
- Conforms to:
- NSCoding
- NSCopying
- NSObject (NSObject)
Declared in:
- EOControl/EOFetchSpecification.h
Class Description
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:editingContext:, defined by EOObjectStore, EOEditingContext, and EODatabaseContext, as well as objectsWithFetchSpecification:editingContext:, defined by EOEditingContext alone. EOAdaptorChannel and EODatabaseChannel also define methods that use EOFetchSpecifications.
Adopted Protocols
NSCoding
- - encodeWithCoder:
- - initWithCoder:
NSCopying
- - copyWithZone:
Method Types
- Creating and accessing instances
- + fetchSpecificationWithEntityName:qualifier:sortOrderings:
- - fetchSpecificationWithQualifierBindings: (Yellow Box only)
- - init
- - initWithEntityName:qualifier:sortOrderings:usesDistinct:isDeep:hints:
- + fetchSpecificationNamed:entityNamed:
- 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
Class Methods
fetchSpecificationNamed:entityNamed:
+ (EOFetchSpecification *)fetchSpecificationNamed:(NSString
*)name
entityNamed:(NSString *)entityName
fetchSpecificationWithEntityName:qualifier:sortOrderings:
+ (EOFetchSpecification *)fetchSpecificationWithEntityName:(NSString
*)entityName
qualifier:(EOQualifier *)qualifier
sortOrderings:(NSArray *)sortOrderings
See Also: - initWithEntityName:qualifier:sortOrderings:usesDistinct:isDeep:hints:
Instance Methods
entityName
- (NSString *)entityName
See Also: - isDeep, - setEntityName:
fetchLimit
- (unsigned)fetchLimit
fetchesRawRows
- (BOOL)fetchesRawRows
fetchSpecificationWithQualifierBindings:
- (EOFetchSpecification *)fetchSpecificationWithQualifierBindings:(NSDictionary
*)bindings
hints
- (NSDictionary *)hints
See Also: - setHints:
init
- (id)init
See Also: - initWithEntityName:qualifier:sortOrderings:usesDistinct:isDeep:hints:
initWithEntityName:qualifier:sortOrderings:usesDistinct:isDeep:hints:
- (id)initWithEntityName:(NSString
*)entityName
qualifier:(EOQualifier *)qualifier
sortOrderings:(NSArray *)sortOrderings
usesDistinct:(BOOL)distinctFlag
isDeep:(BOOL)deepFlag
hints:(NSDictionary *)hints
See Also: + fetchSpecificationWithEntityName:qualifier:sortOrderings:
isDeep
- (BOOL)isDeep
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.
locksObjects
- (BOOL)locksObjects
See Also: - setLocksObjects:
prefetchingRelationshipKeyPaths
- (NSArray *)prefetchingRelationshipKeyPaths
promptsAfterFetchLimit
- (BOOL)promptsAfterFetchLimit
qualifier
- (EOQualifier *)qualifier
See Also: - setQualifier:
rawRowKeyPaths
- (NSArray *)rawRowKeyPaths
See Also: - setFetchesRawRows:
refreshesRefetchedObjects
- (BOOL)refreshesRefetchedObjects
See Also: - setRefreshesRefetchedObjects:
requiresAllQualifierBindingVariables
- (BOOL)requiresAllQualifierBindingVariables
setEntityName:
- (void)setEntityName:(NSString
*)entityName
See Also: - isDeep, - entityName
setFetchesRawRows:
- (void)setFetchesRawRows:(BOOL)fetchRawRows
setFetchLimit:
- (void)setFetchLimit:(unsigned)fetchLimit
setHints:
- (void)setHints:(NSDictionary
*)hints
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
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:
- (void)setLocksObjects:(BOOL)flag
See Also: - locksObjects
setPrefetchingRelationshipKeyPaths:
- (void)setPrefetchingRelationshipKeyPaths:(NSArray
*)prefetchingRelationshipKeyPaths
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 an EOFetchSpecification refreshes. "Refreshing" refers to existing objects being overwritten with fetched values-this allows your application to see changes to the database that have been made by someone else. Normally, when you set an EOFetchSpecification to refresh using setRefreshesRefetchedObjects:, it only refreshes the objects you're fetching. For example, if you fetch employees, you don't also fetch the employees' departments. However, if you prefetch relationships, the refetch is propagated for all of the relationships specified.
setPromptsAfterFetchLimit:
- (void)setPromptsAfterFetchLimit:(BOOL)promptsAfterFetchLimit
setQualifier:
- (void)setQualifier:(EOQualifier
*)qualifier
See Also: - qualifier
setRawRowKeyPaths:
- (void)setRawRowKeyPaths:(NSArray
*)rawRowKeyPaths
See Also: - setFetchesRawRows:
setRefreshesRefetchedObjects:
- (void)setRefreshesRefetchedObjects:(BOOL)flag
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:
- (void)setRequiresAllQualifierBindingVariables:(BOOL)allVariablesRequired
See Also: - fetchSpecificationWithQualifierBindings:
setSortOrderings:
- (void)setSortOrderings:(NSArray
*)sortOrderings
setUsesDistinct:
- (void)setUsesDistinct:(BOOL)flag
See Also: - usesDistinct:
sortOrderings:
- (NSArray *)sortOrderings
usesDistinct:
- (BOOL)usesDistinct
See Also: - setUsesDistinct: