PATH |
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:
- 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, 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)
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)
decodeWithKeyValueUnarchiver
public static Object decodeWithKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver)
fetchSpecificationNamed
public static EOFetchSpecification fetchSpecificationNamed( String name, String entityName)
Instance Methods
classForCoder
public Class classForCoder()
clone
public Object clone()
encodeWithCoder
public void encodeWithCoder(NSCoder coder)
encodeWithKeyValueArchiver
public void encodeWithKeyValueArchiver(EOKeyValueArchiver archiver)
entityName
public String entityName()
See Also: isDeep, setEntityName
fetchLimit
public int fetchLimit()
fetchesRawRows
public boolean fetchesRawRows()
fetchSpecificationWithQualifierBindings:
public EOFetchSpecification fetchSpecificationWithQualifierBindings(NSDictionary bindings)
hints
public NSDictionary hints()
See Also: setHints
isDeep
public boolean 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
public boolean locksObjects()
See Also: setLocksObjects
prefetchingRelationshipKeyPaths
public NSArray prefetchingRelationshipKeyPaths()
promptsAfterFetchLimit
public boolean promptsAfterFetchLimit()
qualifier
public EOQualifier qualifier()
See Also: setQualifier
rawRowKeyPaths
public NSArray rawRowKeyPaths()
See Also: setFetchesRawRows
refreshesRefetchedObjects
public boolean refreshesRefetchedObjects()
See Also: setRefreshesRefetchedObjects
requiresAllQualifierBindingVariables
public boolean requiresAllQualifierBindingVariables()
setEntityName
public void setEntityName(String entityName)
See Also: isDeep, entityName
setFetchesRawRows
public void setFetchesRawRows(boolean fetchRawRows)
setFetchLimit
public void setFetchLimit(int fetchLimit)
setHints
public void setHints(NSDictionary hints)
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)
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)
See Also: locksObjects
setPrefetchingRelationshipKeyPaths
public 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
public void setPromptsAfterFetchLimit(boolean promptsAfterFetchLimit)
setQualifier
public void setQualifier(EOQualifier qualifier)
See Also: qualifier
setRawRowKeyPaths
public void setRawRowKeyPaths(NSArray rawRowKeyPaths)
See Also: setFetchesRawRows
setRefreshesRefetchedObjects
public void setRefreshesRefetchedObjects(boolean 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 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)
See Also: fetchSpecificationWithQualifierBindings:
setSortOrderings
public void setSortOrderings(NSArray sortOrderings)
setUsesDistinct
public void setUsesDistinct(boolean flag)
See Also: usesDistinct
sortOrderings
public NSArray sortOrderings()
toString
public String toString()
usesDistinct
public boolean usesDistinct()
See Also: setUsesDistinct
© 2001 Apple Computer, Inc. (Last Published April 19, 2001)