EOQualifier

Inherits From:
NSObject

Conforms To: NSCopying

Declared in: EOControl/EOQualifier.h

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".
EOKeyComparisonQuali fier	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. EOSQLQualifier is also provided for backward compatibility with pre-2.0 Enterprise Objects Framework releases, which didn't offer a SQL-independent qualifier.

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

The following selector constants are defined to represent the different qualifier operators:

EOQualifierOperatorEqual	EOQualifierOperatorLessThanOrEqualTo
EOQualifierOperatorNotEqual	EOQualifierOperatorGreaterThanOrEqualTo
EOQualifierOperatorLessThan	EOQualifierOperatorContains
EOQualifierOperatorGreaterThan	EOQualifierOperatorLike
	EOQualifierOperatorCaseInsensitiveLike

Adopted Protocols

NSCopying

Creating a qualifier

+ qualifierWithQualifierFormat:

+ qualifierWithQualifierFormat:arguments:

+ qualifierToMatchAllValues:

+ qualifierToMatchAnyValue:

- qualifierWithBindings:requiresAllVariables:

Converting strings and operators

+ operatorSelectorForString:

+ stringForOperatorSelector:

Get EOQualifier operators

+ allQualifierOperators

+ relationalQualifierOperators

Accessing a qualifier's keys

- bindingKeys

- keyPathForBindingKey:

Validating a qualifier's keys

- validateKeysWithRootClassDescription:

allQualifierOperators

Returns an NSArray containing all of the operators supported by EOQualifier: =, !=, <, <=, >, >=, "like", and "caseInsensitiveLike".

See also: + relationalQualifierOperators

operatorSelectorForString:

Returns an operator selector based on the string aString. This method is used in parsing a qualifier. For example, the following statement returns the selector isNotEqualTo: .

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:

Takes a dictionary of search criteria, from which the method creates EOKeyValueQualifiers (one for each dictionary entry). The method ANDs these qualifiers together, and returns the resulting EOAndQualifier.

See also:

qualifierToMatchAnyValue:

Takes a dictionary of search criteria, from which the method creates EOKeyValueQualifiers (one for each dictionary entry). The method ORs these qualifiers together, and returns the resulting EOOrQualifier.

See also:

qualifierWithQualifierFormat:

Parses the format string qualifierFormat, usesit to create an EOQualifier, and returns the EOQualifier. 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:

Parses the format string qualifierFormat and the specified arguments, uses them to create an EOQualifier, and returns the EOQualifier. This method is equivalent to qualifierWithQualifierFormat: except that format characters (for example, %@, %d, %f) in qualifierFormat cause the method to search in the arguments array for values rather than in a variable argument list. Note that although %d and %f can be used when constructing qualifiers, they don't work with most other string formatting methods such as NSString's stringWithFormat:.

relationalQualifierOperators

Returns an NSArray containing all of the relational operators supported by EOQualifier: =, !=, <, <=, >, and >=. In other words, returns all of the EOQualifier operators except for the ones that work exclusively on strings: "like" and "caseInsensitiveLike".

See also: + allQualifierOperators

stringForOperatorSelector:

Returns an NSString representation of the selector aSelector. For example, the following statement returns the string "!=":

operator = [EOQualifier stringForOperatorSelector:EOQualifierOperatorNotEqual];

The possible values for selector are as follows:

• EOQualifierOperatorEqual
  
• EOQualifierOperatorNotEqual
  
• EOQualifierOperatorLessThan
  
• EOQualifierOperatorGreaterThan
  
• EOQualifierOperatorLessThanOrEqualTo
  
• EOQualifierOperatorGreaterThanOrEqualTo
  
• EOQualifierOperatorContains
  
• EOQualifierOperatorLike
  
• EOQualifierOperatorCaseInsensitiveLike
  

You'd probably only use this method if you were writing your own parser.

See also: + operatorSelectorForString:

bindingKeys

Returns an array of strings which are the names of the known variables. Multiple occurrences of the same variable will only appear once in this list.

keyPathForBindingKey:

Returns a string which is the "left-hand-side" of the variable in the qualifier. e.g. If you have a qualifier "salary > $amount and manager.lastName = $manager", then calling bindingKeys would return the array ("amount", "manager"). Calling keyPathForBindingKey would return salary for amount, and manager.lastname for manager.

qualifierWithBindings:requiresAllVariables:

Returns a new qualifier substituting all variables with values found in bindings. If requiresAll is YES, any variable not found in bindings will cause an EOQualifierVariableSubstitutionException to be raised. If requiresAll is NO, missing variable values will cause the qualifier node to be pruned from the tree.

validateKeysWithRootClassDescription:

Validates that the receiver contains keys and key paths that belong to or originate from classDesc. This method returns an NSInternalInconsistencyException if an unknown key is found, otherwise it returns nil to indicate that the keys contained by the qualifier are valid.