Documentation Archive Developer
Search
PATH  Documentation > WebObjects 4.5 > EOControl Reference

Table of Contents

EOQualifier


Inherits from:
(com.apple.client.eocontrol) Object
(com.apple.yellow.eocontrol) NSObject
Package:
com.apple.client.eocontrol
com.apple.yellow.eocontrol

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 interface 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




Constants

EOQualifier defines the following NSSelector constants to represent the qualifier operators:


QualifierOperatorEqual QualifierOperatorGreaterThanOrEqualTo
QualifierOperatorNotEqual QualifierOperatorContains
QualifierOperatorLessThan QualifierOperatorLike
QualifierOperatorGreaterThan QualifierOperatorCaseInsensitiveLike
QualifierOperatorLessThanOrEqualTo  



Method Types

Creating a qualifier
qualifierWithQualifierFormat (com.apple.yellow.eocontrol only)
qualifierToMatchAllValues
qualifierToMatchAnyValue
qualifierWithBindings
In-memory filtering
filterArrayWithQualifier
filteredArrayWithQualifier
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


Static Methods


allQualifierOperators

public static NSArray allQualifierOperators()

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

See Also: relationalQualifierOperators


filterArrayWithQualifier

public static void filterArrayWithQualifier( NSMutableArray objects, EOQualifier aQualifier)

Filters objects in place so that it contains only objects matching aQualifier.

filteredArrayWithQualifier

public static NSArray filteredArrayWithQualifier( NSArray objects, EOQualifier aQualifier)

Returns a new array that contains only the objects from objects matching aQualifier.

operatorSelectorForString

public static NSSelector operatorSelectorForString(String aString)

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 QualifierOperatorNotEqual.
Selector selector = Qualifier.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

public static EOQualifier qualifierToMatchAllValues(NSDictionary dictionary)

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.

qualifierToMatchAnyValue

public static EOQualifier qualifierToMatchAnyValue(NSDictionary dictionary)

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.

qualifierWithQualifierFormat

public static EOQualifier qualifierWithQualifierFormat( String qualifierFormat, NSArray arguments)

(com.apple.yellow.eocontrol only) Parses the format string qualifierFormat and the specified arguments, uses them to create an EOQualifier, and returns the EOQualifier. Conversion specifications (occurrences of %@) in qualifierFormat are replaced using the value objects in arguments.

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.*/
EOQualifier qualifier;
EOFetchSpecification fetchSpec;
EODatabaseDataSource dataSource;

dataSource = (EODatabaseDataSource)displayGroup.dataSource();
qualifier =
    EOQualifier.qualifierWithQualifierFormat("cardType = 'Visa'", null);
fetchSpec = new EOFetchSpecification("Member", qualifier, null), null);

dataSource.setFetchSpecification(fetchSpec);
displayGroup.fetch();

qualifierWithQualifierFormat performs no verification to ensure that keys referred to by the format string qualifierFormat exist. It throws an exception if qualifierFormat contains any syntax errors.


relationalQualifierOperators

public static NSArray 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

public static String stringForOperatorSelector(NSSelector aSelector)

Returns a string representation of the selector aSelector. For example, the following statement returns the string "!=":
String operator =
    EOQualifier.stringForOperatorSelector(EOQualifier.QualifierOperatorNotEqual);

The possible values for selector are as follows:

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

See Also: operatorSelectorForString



Instance Methods


addQualifierKeysToSet:

public void addQualifierKeysToSet(NSMutableSet qualKeys)

Adds the receiver's qualifier keys to qualKeys. The subclasses in the EOControl framework do this by traversing the tree of qualifiers. Node qualifiers (such as EOAndQualifier) recursively invoke this method until they reach a leaf qualifier (such as EOKeyValueQualifier) which adds its key to the set.

Subclasses of EOQualifier must implement this method.


allQualifierKeys

public NSSet allQualifierKeys()

Returns an NSSet of strings, which are the left-hand sides of all the qualifiers in the receiver. For example, if you have a qualifier

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()

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.

evaluateWithObject

(com.apple.client.eocontrol) public boolean evaluateWithObject(EOKeyValueCodingAdditions object)

(com.apple.yellow.eocontrol) public boolean evaluateWithObject(Object object)

Implemented by subclasses to return 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

public String keyPathForBindingKey(String key)

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

public abstract EOQualifier qualifierWithBindings( NSDictionary bindings, boolean requiresAll)

Returns a new qualifier substituting all variables with values found in bindings. If requiresAll is true, any variable not found in bindings throws an exception. If requiresAll is false, missing variable values cause the qualifier node to be pruned from the tree.

validateKeysWithRootClassDescription

(com.apple.client.eocontrol) public abstract void validateKeysWithRootClassDescription(EOClassDescription classDesc)

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

(com.apple.yellow.eocontrol) public abstract Throwable validateKeysWithRootClassDescription(EOClassDescription classDesc)

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


Table of Contents