EOQualifier
- Inherits from:
- NSObject
- Conforms to:
- NSCopying
Declared in:
- EOControl/EOQualifier.h
Class Description
EOQualifier is an abstract class for objects that hold information used to restrict selections on objects or database rows according to specified criteria. With the exception of EOSQLQualifier (EOAccess), qualifiers aren't based on SQL and they don't rely upon an EOModel (EOAccess). Thus, the same qualifier can be used both to perform in-memory searches and to fetch from the database.
You never instantiate an instance of EOQualifier. Rather, you use one of its subclasses-one of the following or your own custom EOQualifier subclass:
Subclass | Purpose |
EOKeyValueQualifier | Compares the named property of an object to a supplied value, for example, "weight > 150". |
EOKeyComparisonQualifier | Compares the named property of one object with the named property of another, for example "name = wife.name". |
EOAndQualifier | Contains multiple qualifiers, which it conjoins. For example, "name = 'Fred' AND age < 20". |
EOOrQualifier | Contains multiple qualifiers, which it disjoins. For example, "name = 'Fred' OR name = 'Ethel'". |
EONotQualifier | Contains a single qualifier, which it negates. For example, "NOT (name = 'Fred')". |
EOSQLQualifier | Contains unstructured text that can be transformed into a SQL expression. EOSQLQualifier provides a way to create SQL expressions with any arbitrary SQL. Because EOSQLQualifiers can't be evaluated against objects in memory and because they contain database and SQL-specific content, you should use EOQualifier wherever possible. |
The protocol EOQualifierEvaluation defines how qualifiers are evaluated in memory. To evaluate qualifiers in a database, methods in EOSQLExpression (EOAccess) and EOEntity (EOAccess) are used to generate SQL for qualifiers. Note that all of the SQL generation functionality is contained in the access layer.
For more information on using EOQualifiers, see the sections
- "Creating a Qualifier"
- "Constructing Format Strings"
- "Checking for NULL Values"
- "Using Wildcards and the like Operator"
- "Using Selectors in Qualifier Expressions"
- "Using Different Data Types in Format Strings"
- "Using EOQualifier's Subclasses"
- "Creating Subclasses"
Constants
In EOQualifier.h, EOControl defines the following selector constants to represent the qualifier operators:
Adopted Protocols
NSCopying
Method Types
- Creating a qualifier
- + qualifierWithQualifierFormat:
- + stringForOperatorSelector:
- + qualifierToMatchAllValues:
- + qualifierToMatchAnyValue:
- - qualifierWithBindings:requiresAllVariables:
- In-memory filtering
- - evaluateWithObject:
- Converting strings and operators
- + operatorSelectorForString:
- + stringForOperatorSelector:
- Get EOQualifier operators
- + allQualifierOperators
- + relationalQualifierOperators
- Accessing a qualifiers keys
- - allQualifierKeys
- - addQualifierKeysToSet:
- Accessing a qualifier's binding keys
- - bindingKeys
- - keyPathForBindingKey:
- Validating a qualifier's keys
- - validateKeysWithRootClassDescription:
Class Methods
allQualifierOperators
+ (NSArray *)allQualifierOperators
See Also: + relationalQualifierOperators
operatorSelectorForString:
+ (SEL)operatorSelectorForString:(NSString
*)aString
selector = [EOQualifier operatorSelectorForString:@"!="];
The possible values of aString are =, ==, !=, <, >, <=, >=, "like", and "caseInsensitiveLike".
You'd probably only use this method if you were writing your own qualifier parser.
See Also: + stringForOperatorSelector:
qualifierToMatchAllValues:
+ (EOQualifier *)qualifierToMatchAllValues:(NSDictionary
*)values
qualifierToMatchAnyValue:
+ (EOQualifier *)qualifierToMatchAnyValue:(NSDictionary
*)values
qualifierWithQualifierFormat:
+ (EOQualifier *)qualifierWithQualifierFormat:(NSString
*)qualifierFormat,
...
Based on the content of qualifierFormat, this method generates a tree of the basic qualifier types. For example, the format string "firstName = 'Joe' AND department = 'Facilities'" generates an EOAndQualifier that contains two "sub" EOKeyValueQualifiers. The following code excerpt shows a typical way to use the qualifierWithQualifierFormat: method. The excerpt constructs an EOFetchSpecification, which includes an entity name and a qualifier. It then applies the EOFetchSpecification to the EODisplayGroup's data source and tells the EODisplayGroup to fetch.
EODisplayGroup *displayGroup; /* Assume this exists.*/ EOFetchSpecification *fetchSpec; EODatabaseDataSource *dataSource; dataSource = [displayGroup dataSource]; fetchSpec = [EOFetchSpecification fetchSpecificationWithEntityName:@"Member" qualifier:[EOQualifier qualifierWithQualifierFormat: @"cardType = 'Visa' "] sortOrderings:nil]; [dataSource setFetchSpecification:fetchSpec]; [displayGroup fetch];
qualifierWithQualifierFormat performs no verification to ensure that keys referred to by the format string qualifierFormat exist. It raises an NSInvalidArgumentException if qualifierFormat contains any syntax errors.
qualifierWithQualifierFormat:arguments:
+ (EOQualifier *)qualifierWithQualifierFormat:(NSString
*)qualifierFormat
arguments:(NSArray *)arguments
qualifierWithQualifierFormat:varargList:
+ (EOQualifier *)qualifierWithQualifierFormat:(NSString
*)format
varargList:(va_list)args
relationalQualifierOperators
+ (NSArray *)relationalQualifierOperators
See Also: + allQualifierOperators
stringForOperatorSelector:
+ (NSString *)stringForOperatorSelector:(SEL)aSelector
operator = [EOQualifier stringForOperatorSelector:EOQualifierOperatorNotEqual];
The possible values for selector are as follows:
- EOQualifierOperatorEqual
- EOQualifierOperatorNotEqual
- EOQualifierOperatorLessThan
- EOQualifierOperatorGreaterThan
- EOQualifierOperatorLessThanOrEqualTo
- EOQualifierOperatorGreaterThanOrEqualTo
- EOQualifierOperatorContains
- EOQualifierOperatorLike
- EOQualifierOperatorCaseInsensitiveLike
You'd probably use this method only if you were writing your own parser.
See Also: + operatorSelectorForString:
Instance Methods
addQualifierKeysToSet:
- (void)addQualifierKeysToSet:(NSMutableSet
*)qualKeys
Subclasses of EOQualifier must implement this method.
allQualifierKeys
- (NSSet *)allQualifierKeys
salary > 10000 AND manager.lastName = 'smith'
allQualifierKeys returns an array containing the strings "salary" and "manager.lastName".
Subclasses should not override this method, instead they should override addQualifierKeysToSet:.
bindingKeys
- (NSArray *)bindingKeys
evaluateWithObject:
- (BOOL)evaluateWithObject:(id)object
YES
if object matches
the criteria specified in the receiver, NO
otherwise.
The argument, object, should be an enterprise object, a snapshot
dictionary, or something that implements key-value coding.keyPathForBindingKey:
- (NSString *)keyPathForBindingKey:(NSString
*)key
qualifierWithBindings:requiresAllVariables:
- (EOQualifier *)qualifierWithBindings:(NSDictionary
*)bindings
requiresAllVariables:(BOOL)requiresAll
validateKeysWithRootClassDescription:
- (NSException *)validateKeysWithRootClassDescription:(EOClassDescription
*)classDesc
nil
to
indicate that the keys contained by the qualifier are valid.