PATH
Documentation > WebObjects 4.5 >
EOControl Reference
- 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
+ (EOFetchSpecification *)fetchSpecificationNamed:(NSString
*)name
entityNamed:(NSString *)entityName
Returns the fetch specification that the entity
specified by entityName associates
with the fetch specification name name.
+ (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
- (NSString *)entityName
Returns the name of the entity to be fetched.See
Also: - isDeep, - setEntityName:
- (unsigned)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.
- (BOOL)fetchesRawRows
Returns YES if rawRowKeyPaths returns non-nil.
- (EOFetchSpecification *)fetchSpecificationWithQualifierBindings:(NSDictionary
*)bindings
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.
- (NSDictionary *)hints
Returns the receiver's hints, which other
objects can use to alter or optimize fetch operations. See
Also: - setHints:
- (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:
- (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:
- (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.
- (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:
- (NSArray *)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").
- (BOOL)promptsAfterFetchLimit
Returns whether to prompt user after the fetch
limit has been reached. Default is NO.
- (EOQualifier *)qualifier
Returns the EOQualifier that indicates which
records or objects the receiver is to fetch.See
Also: - setQualifier:
- (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 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: - setFetchesRawRows:
- (BOOL)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 relationshipsSee
Also: - setRefreshesRefetchedObjects:
- (BOOL)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.
- (void)setEntityName:(NSString
*)entityName
Sets the name of the root entity to be fetched
to entityName.See
Also: - isDeep, - entityName
- (void)setFetchesRawRows:(BOOL)fetchRawRows
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.
- (void)setFetchLimit:(unsigned)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.
- (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 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
- (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
- (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
- (void)setPrefetchingRelationshipKeyPaths:(NSArray
*)prefetchingRelationshipKeyPaths
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").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.
- (void)setPromptsAfterFetchLimit:(BOOL)promptsAfterFetchLimit
Sets whether to prompt user after the fetch
limit has been reached. Default is NO.
- (void)setQualifier:(EOQualifier
*)qualifier
Sets the receiver's qualifier to qualifier.See
Also: - qualifier
- (void)setRawRowKeyPaths:(NSArray
*)rawRowKeyPaths
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: - setFetchesRawRows:
- (void)setRefreshesRefetchedObjects:(BOOL)flag
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
- (void)setRequiresAllQualifierBindingVariables:(BOOL)allVariablesRequired
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:
- (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.
- (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:
- (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.
- (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: