Documentation Archive Developer
Search
PATH Documentation > WebObjects

Table of Contents

EOFetchSpecification


Inherits from:
Object
Implements:
NSCoding
Cloneable
EOKeyValueArchiving
Serializable
Package:
com.webobjects.eocontrol


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 most often used with the method objectsWithFetchSpecification, defined by EOObjectStore, EOEditingContext, and EODatabaseContext. EOAdaptorChannel and EODatabaseChannel also define methods that use EOFetchSpecifications.




Interfaces Implemented


NSCoding
classForCoder
classForCoder


Method Types


Constructors
EOFetchSpecification
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


Constructors



EOFetchSpecification

public EOFetchSpecification()

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

public EOFetchSpecification( String entityName, EOQualifier qualifier, NSArray sortOrderings, boolean distinctFlag, boolean deepFlag, NSDictionary hints)

Creates a new EOFetchSpecification with the arguments specified. If no arguments are provided, the new EOFetchSpecification has no state, except that it fetches deeply and doesn't use distinct. Use the set... methods to add other parts of the specification. Minimally, you must set the entity name.

If only entityName, qualifier, and sortOrderings are provided, the new EOFetchSpecification is deep, doesn't perform distinct selection, and has no hints.




Static Methods



decodeObject

public static Object decodeObject(NSCoder coder)

Conformance to NSCoding.

decodeWithKeyValueUnarchiver

public static Object decodeWithKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver)

Conformance to EOKeyValueArchiving.

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.


Instance Methods



classForCoder

public Class classForCoder()

Conformance to NSCoding.

clone

public Object clone()

Conformance to Cloneable.

encodeWithCoder

public void encodeWithCoder(NSCoder coder)

Conformance to NSCoding.

encodeWithKeyValueArchiver

public void encodeWithKeyValueArchiver(EOKeyValueArchiver archiver)

Conformance to EOKeyValueArchiving.

entityName

public String entityName()

Returns the name of the entity to be fetched.

See Also: isDeep, setEntityName



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.

fetchesRawRows

public boolean fetchesRawRows()

Returns true if rawRowKeyPaths returns non-nil.

fetchSpecificationWithQualifierBindings:

public 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 true to force an exception to be raised if a binding is missing during variable substitution.

hints

public NSDictionary hints()

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

See Also: setHints



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.



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.

See Also: setLocksObjects



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 the Movie entity, you might specify paths of the form ("directors", "roles.talent", "plotSummary").

promptsAfterFetchLimit

public boolean promptsAfterFetchLimit()

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

qualifier

public EOQualifier qualifier()

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

See Also: setQualifier



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 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 method. (Note that this faulting behavior does not occur in Java Client.)

See Also: setFetchesRawRows



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

See Also: setRefreshesRefetchedObjects



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.

setEntityName

public void setEntityName(String entityName)

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

See Also: isDeep, entityName



setFetchesRawRows

public void setFetchesRawRows(boolean fetchRawRows)

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. If set to false, the behavior is as if setRawRowKeyPaths were called with a nil argument.

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.

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

See Also: hints



setIsDeep

public void setIsDeep(boolean flag)

Controls 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 /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

public void setLocksObjects(boolean flag)

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

See Also: locksObjects



setPrefetchingRelationshipKeyPaths

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



setPromptsAfterFetchLimit

public void setPromptsAfterFetchLimit(boolean promptsAfterFetchLimit)

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

setQualifier

public void setQualifier(EOQualifier qualifier)

Sets the receiver's qualifier to qualifier.

See Also: qualifier



setRawRowKeyPaths

public 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 method. (Note that this faulting behavior does not occur in Java Client.)

See Also: setFetchesRawRows



setRefreshesRefetchedObjects

public void setRefreshesRefetchedObjects(boolean flag)

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

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 in com.webobjects.eocontrol than you can with an EOFetchSpecification by using the delegate method databaseContextShouldUpdateCurrentSnapshot. For more information see the EODatabaseContext class specification and EODatabaseContext.Delegate interface specification.

See Also: refreshesRefetchedObjects



setRequiresAllQualifierBindingVariables

public void setRequiresAllQualifierBindingVariables(boolean allVariablesRequired)

Sets the behavior when a missing binding is encountered during variable substitution. If allVariablesRequired 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.

See Also: fetchSpecificationWithQualifierBindings:



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.

setUsesDistinct

public void setUsesDistinct(boolean flag)

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

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.

toString

public String toString()

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.

See Also: setUsesDistinct



© 2001 Apple Computer, Inc. (Last Published April 19, 2001)


Table of Contents