WebObjects 5.2

com.webobjects.eocontrol
Class EOQualifier

java.lang.Object
  |
  +--com.webobjects.eocontrol.EOQualifier
All Implemented Interfaces:
EOQualifierEvaluation, Serializable
Direct Known Subclasses:
BooleanQualifier, EOAndQualifier, EOKeyComparisonQualifier, EOKeyValueQualifier, EONotQualifier, EOOrQualifier, EOSQLQualifier, NonNullQualifier

public abstract class EOQualifier
extends Object
implements Serializable, EOQualifierEvaluation

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, your own custom EOQualifier subclasses, or one of the following classes:

Subclass Purpose


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.

Creating a Qualifier

As described above, there are several EOQualifier subclasses, each of which represents a different semantic. However, in most cases you simply create a qualifier using the EOQualifier static method qualifierWithQualifierFormat , as follows:

 EOQualifier qual = EOQualifier.qualifierWithQualifierFormat
 ("lastName = 'Smith'", null);

The qualifier or group of qualifiers that result from such a statement is based on the contents of the format string you provide. For example, giving the format string "lastName = 'Smith'" as an argument to qualifierWithQualifierFormat returns an EOKeyValueQualifier object. But you don't normally need to be concerned with this level of detail.

The format strings you use to create a qualifier can be compound logical expressions, such as "firstName = 'Fred' AND age < 20" . When you create a qualifier, compound logical expressions are translated into a tree of EOQualifier nodes. Logical operators such as AND and OR become EOAndQualifiers and EOOrQualifiers, respectively. These qualifiers conjoin (AND) or disjoin (OR) a group of sub qualifiers.


Constructing Format Strings

As described above, you typically create a qualifier from a format string by using qualifierWithQualifierFormat. This method takes as an argument a format string vaguely similar to the standard C printf() function. The format string can embed strings, numbers, and other objects using the conversion specification %@. The second argument to qualifierWithQualifierFormat is an array that contains the value or result to substitute for any %@ conversion specifications. This allows qualifiers to be built dynamically. The following table lists the conversion specifications you can use in a format string and their corresponding data types.


Conversion Specification Expected Value or Result
%s A String object, or the result of the toString method
%d An Integer or something which can be converted into an Integer.
%f A Double or something which can be converted into a Double
%@ An arbitrary Object argument. No conversions are performed.
%K Similar to %@ except the argument is coerced to a String with toString and treated as a key which can determine whether the resultant qualifier is an EOKeyValueQualifier or an EOKeyComparisonQualifer.
%% Results in a literal % character.

If you use an unrecognized character in a conversion specification (for example, %x), an exception is thrown.

For example, suppose you have an Employee entity with the properties empID, firstName, lastName, salary, and department (representing a to-one relationship to the employee's department), and a Department entity with properties deptID, and name. You could construct simple qualifier strings like the following:

 lastName = 'Smith'
 salary > 2500
 department.name = 'Personnel'

The following examples build qualifiers similar to the qualifier strings described above, but take the specific values from already fetched enterprise objects:

 Employee anEmployee;    // Assume this exists.
 Department aDept;       // Assume this exists.
 EOQualifier myQualifier;
 NSMutableArray args = new MutableVector();
 args.addObject("lastName");
 args.addObject(anEmployee.lastName());
 myQualifier = EOQualifier.qualifierWithQualifierFormat
 ("%@ = %@", args);
 args.removeAllObjects();
 args.addObject("salary");
 args.addObject(anEmployee.salary());
 myQualifier = EOQualifier.qualifierWithQualifierFormat
 ("%@ > %f", args);
 args.removeAllElements();
 args.addElement("department.name");
 args.addElement(aDept.name());
 myQualifier = EOQualifier.qualifierWithQualifierFormat
 ("%@ = %@", args);

The enterprise objects here implement methods for directly accessing the given attributes: lastName and salary for Employee objects, and name for Department objects. Note that unlike a string literal, the %@ conversion specification is never surrounded by single quotes:

 // For a literal string value such as Smith, you use single quotes.
 EOQualifier.qualifierWithQualifierFormat("lastName = 'Smith'", null);
 // For the conversion specification %@, you don't use quotes
 args.removeAllElements();
 args.addElement("Jones");
 EOQualifier.qualifierWithQualifierFormat("lastName = %@", args);
 

Typically format strings include only two data types: strings and numbers. Single quoted or double quoted strings correspond to String objects in the argument array, non quoted numbers correspond to Numbers, and non quoted strings are keys. You can get around this limitation by performing explicit casting.

The operators you can use in constructing qualifiers are =, ==, !=, <, >, <=, >=, "like", and "caseInsensitiveLike". The like and caseInsensitiveLike operators can be used with wildcards to perform pattern matching,


Checking for NULL Values

To construct a qualifier that fetches rows matching NULL, you can use either of the approaches shown in the following example:

 NSMutableArray args = new NSMutableArray();
 // Approach 1
 EOQualifier.qualifierWithQualifierFormat("bonus = nil", null);
 // Approach 2
 args.addElement(NullValue.nullValue());
 EOQualifier.qualifierWithQualifierFormat("bonus = %@", args);


Using Wildcards and the like Operator

When you use the like or caseInsensitiveLike operator in a qualifier expression, you can use the wildcard characters and ? to perform pattern matching, for example:

 "lastName like 'Jo '"

matches Jones, Johnson, Jolsen, Josephs, and so on.

The ? character just matches a single character, for example:

 "lastName like 'Jone?'"

matches Jones.

The asterisk character ( ) is only interpreted as a wildcard in expressions that use the like or caseInsensitiveLike operator. For example, in the following statement, the character is treated as a literal value, not as a wildcard:

 quot;lastName = 'Jo '"


Using Selectors in Qualifier Expressions

The format strings you use to initialize a qualifier can include methods. The parser recognizes an unquoted string followed by a colon (such as myMethod: ) as a method. For example:

 point1 isInside: area
 firstName isAnagramOfString: "Computer"

The method signature of the embedded selector (isAnagramOfString in this example must be:

 public Boolean isAnagramOfString (String aString){}
 

You can also pass an Object rather than a String. If you pass an Object, the invocation is wrapped in an exception handler and returns false unless you return a Boolean.

Methods specified in a qualifier are parsed and applied only in memory; that is, they can't be used in to qualify fetches in a database.


Using EOQualifier's Subclasses

You rarely need to explicitly create an instance of EOAndQualifier, EOOrQualifier, or EONotQualifier. However, you may want to create instances of EOKeyValueQualifier and EOKeyComparisionQualifier. The primary advantage of this is that it lets you exercise more control over how the qualifier is constructed.

If you want to explicitly create a qualifier subclass, you can do it using code such as the following excerpt, which uses EOKeyValueQualifier to select all objects whose "isOut" key is equal to 1 (meaning true). In the excerpt, the qualifier is used to filter an in memory array.

 // Create the qualifier
 EOQualifier qual = new EOKeyValueQualifier("isOut", 
 EOQualifier.QualifierOperatorEqual,
 new Integer(1));
 // Filter an array and return it 
 return Qualifier.filteredVectorWithQualifier(allRentals(), qual);

filteredArrayWithQualifier is a method that returns an array containing objects from the provided array that match the provided qualifier.


Creating Subclasses

A custom subclass of EOQualifier must implement the EOQualifierEvaluation interface if they are to be evaluated in memory.

See Also:
Serialized Form

Inner Class Summary
static interface EOQualifier.Comparison
          The EOQualifierComparison interface defines methods for comparing values.
static class EOQualifier.ComparisonSupport
          The Java Client EOQualifier.ComparisonSupport class provides default implementations of the EOQualifierComparison interface.
 class EOQualifier.QualifierVariableSubstitutionException
          
 
Field Summary
static NSSelector QualifierOperatorCaseInsensitiveLike
          One of the possible values of selector.
static NSSelector QualifierOperatorContains
          One of the possible values of selector.
static NSSelector QualifierOperatorEqual
          One of the possible values of selector.
static NSSelector QualifierOperatorGreaterThan
          One of the possible values of selector.
static NSSelector QualifierOperatorGreaterThanOrEqualTo
          One of the possible values of selector.
static NSSelector QualifierOperatorLessThan
          One of the possible values of selector.
static NSSelector QualifierOperatorLessThanOrEqualTo
          One of the possible values of selector.
static NSSelector QualifierOperatorLike
          One of the possible values of selector.
static NSSelector QualifierOperatorNotEqual
          One of the possible values of selector.
 
Constructor Summary
EOQualifier()
           
 
Method Summary
abstract  void addQualifierKeysToSet(NSMutableSet qualifierKeys)
          Adds the receiver's qualifier keys to qualifierKeys.
 NSSet allQualifierKeys()
          Returns an NSSet of strings, which are the left hand sides of all the qualifiers in the receiver.
static NSArray allQualifierOperators()
          Returns an NSArray containing all of the operators supported by EOQualifier: =, !=, <, <=, >, >=, like, and caseInsensitiveLike.
 NSArray bindingKeys()
          Returns an array of strings which are the names of the known variables.
 Object clone()
          Returns an exact replica of the receiver.
 boolean evaluateWithObject(Object object)
          Implemented by subclasses to return true if object matches the criteria specified in the receiver, false otherwise.
static void filterArrayWithQualifier(NSMutableArray array, EOQualifier qualifier)
          Filters array in place so that it contains only objects matching qualifier.
static NSArray filteredArrayWithQualifier(NSArray array, EOQualifier qualifier)
          Returns a new array that contains only the array from objects matching qualifier.
 String keyPathForBindingKey(String key)
          Returns a string which is the left hand side of the variable in the qualifier.
protected static NSSelector operatorSelectorForSelectorNamed(String string)
          Returns a named operator selector.
static NSSelector operatorSelectorForString(String string)
          Returns an operator selector based on the string string.
static EOQualifier qualifierToMatchAllValues(NSDictionary values)
          Takes a dictionary of search criteria, from which the method creates EOKeyValueQualifiers (one for each dictionary entry).
static EOQualifier qualifierToMatchAnyValue(NSDictionary values)
          Takes a dictionary of search criteria, from which the method creates EOKeyValueQualifiers (one for each dictionary entry).
abstract  EOQualifier qualifierWithBindings(NSDictionary bindings, boolean requiresAll)
          Returns a new qualifier substituting all variables with values found in bindings.
static EOQualifier qualifierWithQualifierFormat(String format, NSArray arguments)
          Parses the format string format and the specified arguments, uses them to create an EOQualifier, and returns the EOQualifier.
static NSArray relationalQualifierOperators()
          Returns an NSArray containing all of the relational operators supported by EOQualifier: =, !=, <, <=, >, and >=.
static String stringForOperatorSelector(NSSelector selector)
          Returns a string representation of the selector selector.
abstract  void validateKeysWithRootClassDescription(EOClassDescription classDescription)
          Ensures that the receiver contains keys and key paths that belong to or originate from classDescription.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

QualifierOperatorCaseInsensitiveLike

public static final NSSelector QualifierOperatorCaseInsensitiveLike
One of the possible values of selector.

QualifierOperatorContains

public static final NSSelector QualifierOperatorContains
One of the possible values of selector.

QualifierOperatorEqual

public static final NSSelector QualifierOperatorEqual
One of the possible values of selector.

QualifierOperatorGreaterThan

public static final NSSelector QualifierOperatorGreaterThan
One of the possible values of selector.

QualifierOperatorGreaterThanOrEqualTo

public static final NSSelector QualifierOperatorGreaterThanOrEqualTo
One of the possible values of selector.

QualifierOperatorLessThan

public static final NSSelector QualifierOperatorLessThan
One of the possible values of selector.

QualifierOperatorLessThanOrEqualTo

public static final NSSelector QualifierOperatorLessThanOrEqualTo
One of the possible values of selector.

QualifierOperatorLike

public static final NSSelector QualifierOperatorLike
One of the possible values of selector.

QualifierOperatorNotEqual

public static final NSSelector QualifierOperatorNotEqual
One of the possible values of selector.
Constructor Detail

EOQualifier

public EOQualifier()
Method Detail

addQualifierKeysToSet

public abstract void addQualifierKeysToSet(NSMutableSet qualifierKeys)
Adds the receiver's qualifier keys to qualifierKeys. 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.

Parameters:
qualifierKeys - The mutable array of qualifier keys

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 stringssalary andmanager.lastName. Subclasses should not override this method, instead they should override addQualifierKeysToSet.
Returns:
an NSSet of strings
See Also:
addQualifierKeysToSet(NSMutableSet qualKeys)

allQualifierOperators

public static NSArray allQualifierOperators()
Returns an NSArray containing all of the operators supported by EOQualifier: =, !=, <, <=, >, >=, like, and caseInsensitiveLike.
Returns:
an NSArray containing all of the operators supported by EOQualifier
See Also:
relationalQualifierOperators()

bindingKeys

public 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.
Returns:
an array of strings which are the names of the known variables

clone

public Object clone()
Returns an exact replica of the receiver.
Overrides:
clone in class Object
Returns:
The exact replica of the receiver.

evaluateWithObject

public boolean evaluateWithObject(Object object)
Implemented by subclasses to return true if object matches the criteria specified in the receiver, false otherwise. The argument, object, should be an enterprise object, a snapshot dictionary, or something that implements key-value coding.
Specified by:
evaluateWithObject in interface EOQualifierEvaluation
Parameters:
object - The input object
Returns:
return true if object matches the criteria specified in the receiver

filterArrayWithQualifier

public static void filterArrayWithQualifier(NSMutableArray array,
                                            EOQualifier qualifier)
Filters array in place so that it contains only objects matching qualifier.
Parameters:
array - input array
qualifier - database selection criteria

filteredArrayWithQualifier

public static NSArray filteredArrayWithQualifier(NSArray array,
                                                 EOQualifier qualifier)
Returns a new array that contains only the array from objects matching qualifier.
Parameters:
array - The input array
qualifier - database selection criteria
Returns:
new array that contains only the objects from array matching aQualifier

keyPathForBindingKey

public String keyPathForBindingKey(String key)
Returns a string which is the left hand side of the variable in the qualifier. 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.
Parameters:
key - The input string
Returns:
string which is the left hand side of the variable in the qualifier

operatorSelectorForSelectorNamed

protected static NSSelector operatorSelectorForSelectorNamed(String string)
Returns a named operator selector.
Parameters:
string - selector name
Returns:
corresponding selector

operatorSelectorForString

public static NSSelector operatorSelectorForString(String string)
Returns an operator selector based on the string string. 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 would probably only use this method if you were writing the own qualifier parser.
Parameters:
string - The input string
Returns:
an operator selector based on the input string
See Also:
stringForOperatorSelector(NSSelector selector)

qualifierToMatchAllValues

public static EOQualifier qualifierToMatchAllValues(NSDictionary values)
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.
Parameters:
values - dictionary of search criteria
Returns:
the resulting EOAndQualifier object

qualifierToMatchAnyValue

public static EOQualifier qualifierToMatchAnyValue(NSDictionary values)
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.
Parameters:
values - dictionary of search criteria
Returns:
the resulting EOOrQualifier object

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.
Parameters:
bindings - bindings dictionary
requiresAll - Value indicating if all the criteria are required
Returns:
new qualifier substituting all variables with values in bindings

qualifierWithQualifierFormat

public static EOQualifier qualifierWithQualifierFormat(String format,
                                                       NSArray arguments)
Parses the format string format 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 format, 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 twosub 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 format exist. It throws an exception if format contains any syntax errors.

Parameters:
format - The format string
arguments - The input array of arguments
Returns:
resulting EOQualifier object

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".
Returns:
all of the EOQualifier operators minus those which are for strings
See Also:
allQualifierOperators()

stringForOperatorSelector

public static String stringForOperatorSelector(NSSelector selector)
Returns a string representation of the selector selector. For example, the following statement returns the string!=:
String operator = EOQualifier.stringForOperatorSelector(EOQualifier.QualifierOperatorNotEqual);
The possible values for selector are as follows:

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

Parameters:
selector - input selector
Returns:
a string representation of the selector
See Also:
operatorSelectorForString(String string), QualifierOperatorEqual, QualifierOperatorNotEqual, QualifierOperatorLessThan, QualifierOperatorGreaterThan, QualifierOperatorLessThanOrEqualTo, QualifierOperatorGreaterThanOrEqualTo, QualifierOperatorContains, QualifierOperatorLike, QualifierOperatorCaseInsensitiveLike

validateKeysWithRootClassDescription

public abstract void validateKeysWithRootClassDescription(EOClassDescription classDescription)
Ensures that the receiver contains keys and key paths that belong to or originate from classDescription. 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.
Parameters:
classDescription - The EOClassDescription to be checked with the receiver

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

Copyright © 2003 Apple Computer, Inc.