EOFetchSpecification

Inherits From:
NSObject

Conforms To: 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:

EOFetchSpecifications are used most often in the objectsWithFetchSpecification:editingContext: method defined by EOObjectStore, EOEditingContext, and EODatabaseContext, as well as objectsWithFetchSpecification: , defined by EOEditingContext alone. EOAdaptorChannel and EODatabaseChannel also define methods that use EOFetchSpecifications.

NSCopying
- copyWithZone:
Creating instances
+ fetchSpecificationWithEntityName:qualifier:sortOrderings:
- init
- initWithEntityName:qualifier:sortOrderings:usesDistinct:
isDeep:hints:
Configuring fetch parameters
- setEntityName:
- entityName
- setQualifier:
- qualifier
- setSortOrderings:
- sortOrderings
- setUsesDistinct:
- usesDistinct
- setLocksObjects:
- locksObjects
- setIsDeep:
- isDeep
- setRefreshesRefetchedObjects:
- refreshesRefetchedObjects
- setHints:
- hints

Class Methods

fetchSpecificationWithEntityName:qualifier:sortOrderings:

+ (EOFetchSpecification *)fetchSpecificationWithEntityName: (NSString *)entityName
qualifier: (EOQualifier *)qualifier
sortOrderings: (NSArray *)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:

Instance Methods

entityName

- (NSString *)entityName

Returns the name of the entity to be fetched.

See also: - isDeep , - setEntityName:

hints

- (NSDictionary *)hints

Returns the receiver's hints, which other objects can use to alter or optimize fetch operations. EODatabaseContext's objectsWithFetchSpecification:editingContext: uses a hint to prefetch the destinations of relationships, for example.

See also: - setHints:

init

- (id)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:

- (id)initWithEntityName: (NSString *)entityName
qualifier: (EOQualifier *)qualifier
sortOrderings: (NSArray *)sortOrderings
usesDistinct: (BOOL)distinctFlag
isDeep: (BOOL)deepFlag
hints: (NSDictionary *)hints

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

See also: + fetchSpecificationWithEntityName:qualifier:sortOrderings:

isDeep

- (BOOL)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

- (BOOL)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:

qualifier

- (EOQualifier *)qualifier

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

See also: - setQualifier:

refreshesRefetchedObjects

- (BOOL)refreshesRefetchedObjects

Returns YES if existing objects are overwritten with fetched values when they've have 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.

See also: - setRefreshesRefetchedObjects:

setEntityName:

- (void)setEntityName: (NSString *)entityName

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

See also: - isDeep , - entityName

setHints:

- (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 hints identified by the keys EOPrefetchingRelationshipHintKey and 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 and the Access Layer Types and Constants 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:

- (void)setLocksObjects: (BOOL)flag

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

setQualifier:

- (void)setQualifier: (EOQualifier *)qualifier

Sets the receiver's qualifier to qualifier.

See also: - qualifier

setRefreshesRefetchedObjects:

- (void)setRefreshesRefetchedObjects: (BOOL)flag

Controls whether existing objects are overwritten with fetched values when they've 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.

- refreshesRefetchedObjects

setSortOrderings:

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

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

setUsesDistinct:

- (void)setUsesDistinct: (BOOL)flag

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

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

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

usesDistinct

- (BOOL)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:

Copyright © 1997, Apple Computer, Inc. All rights reserved.