WebObjects 5.2

com.webobjects.eocontrol
Class EOFetchSpecification

java.lang.Object
  |
  +--com.webobjects.eocontrol.EOFetchSpecification
All Implemented Interfaces:
Cloneable, EOKeyValueArchiving, NSCoding, Serializable

public class EOFetchSpecification
extends Object
implements Serializable, Cloneable, NSCoding, EOKeyValueArchiving

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.

See Also:
Serialized Form

Inner classes inherited from class com.webobjects.foundation.NSCoding
NSCoding.Support
 
Inner classes inherited from class com.webobjects.eocontrol.EOKeyValueArchiving
EOKeyValueArchiving.Awaking, EOKeyValueArchiving.FinishInitialization, EOKeyValueArchiving.Support
 
Constructor Summary
EOFetchSpecification()
          Creates a new EOFetchSpecification.
EOFetchSpecification(String entityName, EOQualifier qualifier, NSArray sortOrderings)
          Creates a new EOFetchSpecification with the arguments specified.
EOFetchSpecification(String entityName, EOQualifier qualifier, NSArray sortOrderings, boolean usesDistinct, boolean isDeep, NSDictionary hints)
          Creates a new EOFetchSpecification with the arguments specified.
 
Method Summary
 Class classForCoder()
          Allows the receiver, before being encoded, to substitute a class other than its own in a coder.
 Object clone()
          Implementation of the java.lang.Cloneable interface.
static Object decodeObject(NSCoder coder)
          (Re)creates an object based on type information and data stored in coder.
static Object decodeWithKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver)
          (Re)creates an object based on information in unarchiver.
 void encodeWithCoder(NSCoder coder)
          Archives the receiver's type information and data into coder.
 void encodeWithKeyValueArchiver(EOKeyValueArchiver archiver)
          Archives the receiver's into archiver.
 String entityName()
          Returns the name of the entity to be fetched.
 boolean fetchesRawRows()
          Returns whether the rawRowKeyPaths method returns non-null.
 int fetchLimit()
          Returns the fetch limit value which indicates the maximum number of objects to fetch.
static EOFetchSpecification fetchSpecificationNamed(String name, String entityName)
          Returns the fetch specification that the entity specified by entityName associates with the fetch specification name name.
 EOFetchSpecification fetchSpecificationWithQualifierBindings(NSDictionary bindings)
          Applies bindings from bindings to the receiver's qualifier if there is one, and returns a new fetch specification that can be used in a fetch.
 NSDictionary hints()
          Returns the receiver's hints, which other objects can use to alter or optimize fetch operations.
 boolean isDeep()
          Returns true if a fetch should include sub-entities of the receiver's entity, false if it shouldn't.
 boolean locksObjects()
          Returns true if a fetch should result in the selected objects being locked in the data repository, false if it shouldn't.
 NSArray prefetchingRelationshipKeyPaths()
          Returns an array of relationship key paths that should be prefetched along with the main fetch.
 boolean promptsAfterFetchLimit()
          Returns whether to prompt the user after the fetch limit has been reached.
 EOQualifier qualifier()
          Returns the EOQualifier that indicates which records or objects the receiver is to fetch.
 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).
 boolean refreshesRefetchedObjects()
          Returns true if existing objects are overwritten with fetched values when they've been updated or changed.
 boolean requiresAllQualifierBindingVariables()
          Returns true to indicate that a missing binding will cause an exception to be raised during variable substitution.
 void setEntityName(String entityName)
          Sets the name of the root entity to be fetched to entityName.
 void setFetchesRawRows(boolean fetchesRawRows)
          Sets the behavior for fetching raw rows.
 void setFetchLimit(int fetchLimit)
          Sets the fetch limit value which indicates the maximum number of objects to fetch.
 void setHints(NSDictionary hints)
          Sets the receiver's hints to hints.
 void setIsDeep(boolean isDeep)
          Sets whether a fetch should include sub-entities of the receiver's entity.
 void setLocksObjects(boolean locksObjects)
          Sets whether a fetch should result in the selected objects being locked in the data repository.
 void setPrefetchingRelationshipKeyPaths(NSArray keyPaths)
          Sets an array of relationship key paths that should be prefetched along with the main fetch.
 void setPromptsAfterFetchLimit(boolean value)
          Sets whether or not the application's message handler is notified when the fetch limit has been reached, enabling the message handler to prompt the user whether to continue to fetch more rows.
 void setQualifier(EOQualifier qualifier)
          Sets this fetch specification's qualifier to qualifier.
 void setRawRowKeyPaths(NSArray keyPaths)
          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).
 void setRefreshesRefetchedObjects(boolean refreshes)
          Sets whether existing objects are overwritten with fetched values when they have been updated or changed.
 void setRequiresAllQualifierBindingVariables(boolean requires)
          Sets the behavior when a missing binding is encountered during variable substitution.
 void setSortOrderings(NSArray sortOrderings)
          Sets the receiver's array of EOSortOrderings to sortOrderings.
 void setUsesDistinct(boolean usesDistinct)
          Sets whether duplicate objects or records are removed after fetching.
 NSArray sortOrderings()
          Returns the receiver's array of EOSortOrderings.
 String toString()
          Returns a String representation of the receiver.
 boolean usesDistinct()
          Returns true if duplicate objects or records are removed after fetching, false if they aren't.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

EOFetchSpecification

public EOFetchSpecification()
Creates a new EOFetchSpecification. By default, fetch specifications fetch deeply and don't use distinct. Before using the fetch specification, you have to set more parameters, at minimum the entity name.
See Also:
setEntityName(String)

EOFetchSpecification

public EOFetchSpecification(String entityName,
                            EOQualifier qualifier,
                            NSArray sortOrderings,
                            boolean usesDistinct,
                            boolean isDeep,
                            NSDictionary hints)
Creates a new EOFetchSpecification with the arguments specified. Minimally, you must specify an entity name. If qualifier is empty, such as an EOAndQualifier or EOOrQualifier whose array of elements contains zero qualifiers, this fetch specification will have its qualifier set to null
Parameters:
entityName - the name of the entity to fetch
qualifier - the qualifier to use for fetching
sortOrderings - the sort orderings to use for fetching
usesDistinct - true if the fetch specification should be distinct; false otherwise
isDeep - true if the fetch specification should be deep; false otherwise
hints - the hints to use for fetching

EOFetchSpecification

public EOFetchSpecification(String entityName,
                            EOQualifier qualifier,
                            NSArray sortOrderings)
Creates a new EOFetchSpecification with the arguments specified. Minimally, you must specify an entity name. The new EOFetchSpecification is deep, doesn't perform distinct selection, and has no hints. If qualifier is empty, such as an EOAndQualifier or EOOrQualifier whose array of elements contains zero qualifiers, this fetch specification will have its qualifier set to null
Parameters:
entityName - the name of the entity to fetch
qualifier - the qualifier to use for fetching
sortOrderings - the sort orderings to use for fetching
Method Detail

classForCoder

public Class classForCoder()
Allows the receiver, before being encoded, to substitute a class other than its own in a coder.
Specified by:
classForCoder in interface NSCoding
Returns:
the class a coder should record
See Also:
encodeWithCoder(NSCoder), decodeObject(NSCoder), NSCoding

clone

public Object clone()
Implementation of the java.lang.Cloneable interface.
Overrides:
clone in class Object
Returns:
a clone of the receiver

decodeObject

public static Object decodeObject(NSCoder coder)
(Re)creates an object based on type information and data stored in coder.
Parameters:
coder - the coder stroing object type information along with an object's data
Returns:
an object (re)created from the data in coder
See Also:
encodeWithCoder(NSCoder coder), classForCoder(), NSCoding

decodeWithKeyValueUnarchiver

public static Object decodeWithKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver)
(Re)creates an object based on information in unarchiver.
Parameters:
unarchiver - the key-value unarchiver with which the receiver should be decoded
Returns:
an object (re)created from the data in unarchiver
See Also:
EOKeyValueArchiving

encodeWithCoder

public void encodeWithCoder(NSCoder coder)
Archives the receiver's type information and data into coder. The receiver can then be recreated using decodeObject. Custom type information can be used by overriding classForCoder.
Specified by:
encodeWithCoder in interface NSCoding
Parameters:
coder - the coder storing object type information along with an object's data
See Also:
decodeObject(NSCoder), classForCoder(), NSCoding

encodeWithKeyValueArchiver

public void encodeWithKeyValueArchiver(EOKeyValueArchiver archiver)
Archives the receiver's into archiver. The receiver can then be recreated using decodeWithKeyValueUnarchiver.
Specified by:
encodeWithKeyValueArchiver in interface EOKeyValueArchiving
Parameters:
archiver - the key-value archiver with which the receiver should be encoded
See Also:
EOKeyValueArchiving

entityName

public String entityName()
Returns the name of the entity to be fetched.
Returns:
the name of the entity to be fetched
See Also:
setEntityName(String), isDeep()

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.
Returns:
the fetch limit value which indicates the maximum number of objects to fetch
See Also:
setFetchLimit(int), promptsAfterFetchLimit(), setPromptsAfterFetchLimit(boolean)

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.
Parameters:
name - the fetch specification name
entityName - the name of an entity for which to fetch records or objects
Returns:
the named fetch specification

fetchSpecificationWithQualifierBindings

public EOFetchSpecification fetchSpecificationWithQualifierBindings(NSDictionary bindings)
Applies bindings from bindings to the receiver's 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. You can invoke setRequiresAllQualifierBindingVariables with a true argument to force an exception to be raised if a binding is missing during variable substitution.
Parameters:
bindings - the bindings which are applied to the receiver's qualifier
Returns:
the new fetch specification that can be used in a fetch
See Also:
setRequiresAllQualifierBindingVariables(boolean)

fetchesRawRows

public boolean fetchesRawRows()
Returns whether the rawRowKeyPaths method returns non-null.
Returns:
true if rawRowKeyPaths returns non-null; false otherwise
See Also:
rawRowKeyPaths(), setFetchesRawRows(boolean)

hints

public NSDictionary hints()
Returns the receiver's hints, which other objects can use to alter or optimize fetch operations.
Returns:
the receiver's hints
See Also:
setHints(NSDictionary)

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.

Returns:
true if a fetch should include sub entities of the receiver's entity; false otherwise
See Also:
setIsDeep(boolean)

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. Note that unnecessary locking could severely degrade the performance of certain repository operations.
Returns:
true if a fetch should result in the selected objects being locked in the data repository; false otherwise
See Also:
setLocksObjects(boolean)

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 a Movie entity, you might specify paths of the form: ("directors","roles.talent", "plotSummary").
Returns:
an array of relationship key paths to prefetch
See Also:
setPrefetchingRelationshipKeyPaths(NSArray)

promptsAfterFetchLimit

public boolean promptsAfterFetchLimit()
Returns whether to prompt the user after the fetch limit has been reached. The default is false.
Returns:
true if the user should be prompted after the fetch limit has been reached; false if fetching should just stop at that point
See Also:
setPromptsAfterFetchLimit(boolean), fetchLimit(), setFetchLimit(int)

qualifier

public EOQualifier qualifier()
Returns the EOQualifier that indicates which records or objects the receiver is to fetch.
Returns:
the EOQualifier that indicates which records or objects to fetch
See Also:
setQualifier(EOQualifier)

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 null, 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.
Returns:
an array of attribute key paths to be fetched as raw data
See Also:
setFetchesRawRows(boolean), setRawRowKeyPaths(NSArray), EOEditingContext.faultForRawRow(NSDictionary, String), EOEditingContext.faultForRawRow(NSDictionary, String, EOEditingContext)

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.
Returns:
true if existing objects are overwritten with fetched values when they've been updated or changed; false otherwise
See Also:
setRefreshesRefetchedObjects(boolean)

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.
Returns:
true if a missing binding should cause an exception; false otherwise

setEntityName

public void setEntityName(String entityName)
Sets the name of the root entity to be fetched to entityName.
Parameters:
entityName - the name of the root entity to be fetched
See Also:
isDeep(), entityName()

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.
Parameters:
fetchLimit - the fetch limit value which indicates the maximum number of objects to fetch
See Also:
fetchLimit(), promptsAfterFetchLimit(), setPromptsAfterFetchLimit(boolean)

setFetchesRawRows

public void setFetchesRawRows(boolean fetchesRawRows)
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 (which causes fetchesRawRows to return true). If set to false, the behavior is as if setRawRowKeyPaths were called with null as the argument (which causes fetchesRawRows to return false). Note that if rawRowKeyPaths has already had a value assigned to it, using this method will overwrite that value.
Parameters:
fetchesRawRows - true if rawRowKeyPaths returns non-null; false otherwise
See Also:
rawRowKeyPaths(), fetchesRawRows()

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 the standard Enterprise Objects Framework that defines fetch specification hints.
Parameters:
hints - the receiver's hints
See Also:
hints(), EODatabaseContext

setIsDeep

public void setIsDeep(boolean isDeep)

Sets 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 with two sub-entities and subclasses, Employee and Customer, fetching Persons deeply also fetches all Employees and Customers matching the qualifier. Fetching Persons shallowly fetches only Persons matching the qualifier.

Parameters:
isDeep - true if sub-entities should be fetched; false otherwise
See Also:
isDeep()

setLocksObjects

public void setLocksObjects(boolean locksObjects)
Sets whether a fetch should result in the selected objects being locked in the data repository. If flag is true it should, if flag is false it shouldn't. The default is false. Note that unnecessary locking could severely degrade the performance of certain repository operations.
Parameters:
locksObjects - true if the selected objects should be locked in the data repository; false otherwise
See Also:
locksObjects()

setPrefetchingRelationshipKeyPaths

public void setPrefetchingRelationshipKeyPaths(NSArray keyPaths)

Sets an array of relationship key paths that should be prefetched along with the main fetch. For example, if fetching from a 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 a fetch specification refreshes.

Refreshing refers to existing objects being overwritten with fetched values. This allows the application to see changes to the database that have been made by someone else. Normally, when an EOFetchSpecification is set to refresh using setRefreshesRefetchedObjects, it only refreshes the objects you are fetching. For example, if you fetch employees, you do not also fetch the employees' departments. However, if you prefetch relationships, the refetch is propagated for all of the relationships specified.

Parameters:
keyPaths - an array of relationship key paths to be prefetched
See Also:
prefetchingRelationshipKeyPaths(), setRefreshesRefetchedObjects(boolean)

setPromptsAfterFetchLimit

public void setPromptsAfterFetchLimit(boolean value)
Sets whether or not the application's message handler is notified when the fetch limit has been reached, enabling the message handler to prompt the user whether to continue to fetch more rows. If value is false, or if the application has no message handler, fetching stops after fetchLimit rows have been fetched. The default is false.

Note that only the EOInterface layer provides a built-in message handler implementation. Standard WebObjects applications must set the message handler directly and implement editingContextShouldContinueFetching to prompt the user in an appropriate form in order to make use of this feature.

Parameters:
value - true if the user should be prompted after the fetch limit has been reached; false if fetching should just stop at that point
See Also:
fetchLimit(), setFetchLimit(int), promptsAfterFetchLimit(), EOEditingContext.MessageHandler.editingContextShouldContinueFetching(EOEditingContext context, int count, int originalLimit, EOObjectStore objectStore)

setQualifier

public void setQualifier(EOQualifier qualifier)
Sets this fetch specification's qualifier to qualifier. If qualifier is empty, such as an EOAndQualifier or EOOrQualifier whose array of elements contains zero qualifiers, this fetch specification will have its qualifier set to null
Parameters:
qualifier - the qualifier
See Also:
qualifier()

setRawRowKeyPaths

public void setRawRowKeyPaths(NSArray keyPaths)
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 null, 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.
Parameters:
keyPaths - an array of attribute key paths to be fetched as raw data
See Also:
rawRowKeyPaths(), setFetchesRawRows(boolean), EOEditingContext.faultForRawRow(NSDictionary, String), EOEditingContext.faultForRawRow(NSDictionary, String, EOEditingContext)

setRefreshesRefetchedObjects

public void setRefreshesRefetchedObjects(boolean refreshes)

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

For example, suppose that an employee object is fetched and then refetched, 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 the first fetch. To keep the employee in sync with the employee data in the external repository you would need to replace the employee's outdated values with the new ones. On the other hand, if you have to fetch the employee, change it, and then refetch it, you would not want to refresh the employee. If you are to refresh it whether or not another application had changed the employee you would lose the changes that you have made to the object.

You can get finer grain control on an EODatabaseContext's refreshing behavior in the EOControl layer than you can with an EOFetchSpecification by using the delegate method databaseContextShouldUpdateCurrentSnapshot.

Parameters:
refreshes - true if existing objects are overwritten with fetched values; false otherwise
See Also:
refreshesRefetchedObjects(), EODatabaseContext, EODatabaseContext.Delegate

setRequiresAllQualifierBindingVariables

public void setRequiresAllQualifierBindingVariables(boolean requires)
Sets the behavior when a missing binding is encountered during variable substitution. If requires 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.
Parameters:
requires - true if a missing binding should cause an exception; false otherwise

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 (serially in lowest-array-index-first order).
Parameters:
sortOrderings - the array of EOSortOrderings
See Also:
sortOrderings()

setUsesDistinct

public void setUsesDistinct(boolean usesDistinct)
Sets whether duplicate objects or records are removed after fetching. If flag is true they are removed (that is, proper sets are returned). If flag is false they aren't (multisets are returned). EOFetchSpecifications by default don't use distinct.
Parameters:
usesDistinct - true if duplicate objects or records should be removed; false otherwise
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 (serially in lowest-array-index-first order).
Returns:
the receiver's array of EOSortOrderings
See Also:
setSortOrderings(NSArray)

toString

public String toString()
Returns a String representation of the receiver.
Overrides:
toString in class Object
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 (that is, they return multisets).
Returns:
true if duplicate objects or records are removed; false otherwise
See Also:
setUsesDistinct(boolean)

Last updated Fri Feb 21 13:15:00 PST 2003.

Copyright © 2003 Apple Computer, Inc.