com.webobjects.eocontrol
Class EOKeyValueQualifier

java.lang.Object
  com.webobjects.eocontrol.EOQualifier
      com.webobjects.eocontrol.EOKeyValueQualifier

All Implemented Interfaces:

EOKeyValueArchiving, EOQualifierEvaluation, NSCoding, Serializable

public class EOKeyValueQualifier

extends EOQualifier

implements NSCoding, EOKeyValueArchiving

EOKeyValueQualifier is a subclass of EOQualifier that compares a named property of an object with a supplied value, for example, "salary > 1500". EOKeyValueQualifier implements the EOQualifierEvaluation interface, which defines the method evaluateWithObject for in-memory evaluation. When an EOKeyValueQualifier object receives an evaluateWithObject message, it evaluates the given object to determine if it satisfies the qualifier criteria.

In addition to performing in memory filtering, EOKeyValueQualifier can be used to generate SQL. When it's used for this purpose, the key should be a valid property name of the root entity for the qualifier (or a valid key path).

See Also:

EOQualifierEvaluation.evaluateWithObject(Object), Serialized Form

Nested Class Summary

Nested classes inherited from class com.webobjects.eocontrol.EOQualifier

EOQualifier.Comparison, EOQualifier.ComparisonSupport, EOQualifier.QualifierVariableSubstitutionException

Nested classes inherited from class com.webobjects.foundation.NSCoding

NSCoding.Support

Nested classes inherited from class com.webobjects.eocontrol.EOKeyValueArchiving

EOKeyValueArchiving.Awaking, EOKeyValueArchiving.FinishInitialization, EOKeyValueArchiving.Support

Field Summary

Fields inherited from class com.webobjects.eocontrol.EOQualifier

QualifierOperatorCaseInsensitiveLike, QualifierOperatorContains, QualifierOperatorEqual, QualifierOperatorGreaterThan, QualifierOperatorGreaterThanOrEqualTo, QualifierOperatorLessThan, QualifierOperatorLessThanOrEqualTo, QualifierOperatorLike, QualifierOperatorNotEqual

Constructor Summary

EOKeyValueQualifier(String key, NSSelector selector, Object value)
Creates a new EOKeyValueQualifier.

Method Summary

void	addQualifierKeysToSet(NSMutableSet qualKeys) Implements the abstract version of this method defined in EOQualfier.
Class	classForCoder() Allows the receiver, before being encoded, to substitute a class other than its own in a coder.
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.
boolean	equals(Object other) Compares the receiver to other.
boolean	evaluateWithObject(Object object) Returns true if object satisfies the qualifier, false otherwise.
String	key() Returns the key (possibly a key path) that the receiver uses when qualifying (for instance, with evaluateWithObject).
EOQualifier	qualifierWithBindings(NSDictionary bindings, boolean requiresAll) Implements the abstract version of this method defined in EOQualfier.
NSSelector	selector() Returns the selector that the receiver uses when qualifying (for instance, with evaluateWithObject).
String	toString() Returns a String representation of the receiver containing its key, selector, and value.
void	validateKeysWithRootClassDescription(EOClassDescription classDesc) Ensures that the receiver contains keys and key paths that belong to or originate from classDesc.
Object	value() Returns the value that the receiver uses when qualifying (for instance, with evaluateWithObject).

Methods inherited from class com.webobjects.eocontrol.EOQualifier

allQualifierKeys, allQualifierOperators, bindingKeys, clone, filterArrayWithQualifier, filteredArrayWithQualifier, keyPathForBindingKey, operatorSelectorForSelectorNamed, operatorSelectorForString, qualifierToMatchAllValues, qualifierToMatchAnyValue, qualifierWithQualifierFormat, relationalQualifierOperators, stringForOperatorSelector

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

EOKeyValueQualifier

public EOKeyValueQualifier(String key,
                           NSSelector selector,
                           Object value)

Creates a new EOKeyValueQualifier. If key, selector, and value are provided, the EOKeyValueQualifier compares values for key to value using the operator method selector. The possible values for selector are as follows:

• EOQualifier.QualifierOperatorEqual
• EOQualifier.QualifierOperatorNotEqual
• EOQualifier.QualifierOperatorLessThan
• EOQualifier.QualifierOperatorGreaterThan
• EOQualifier.QualifierOperatorLessThanOrEqualTo
• EOQualifier.QualifierOperatorGreaterThanOrEqualTo
• EOQualifier.QualifierOperatorContains
• EOQualifier.QualifierOperatorLike
• EOQualifier.QualifierOperatorCaseInsensitiveLike

Enterprise Objects Framework supports SQL generation for these methods only. You can generate SQL using the EOSQLExpression static method sqlStringForKeyValueQualifier.

For example, the following excerpt creates an EOKeyValueQualifier qualifier that has the key "name", the operator method QualifierOperatorEqual, and the value "Smith". Once constructed, the qualifier qualifier is used to filter an in-memory array.

  NSArray employees;   // assume this is populated with Employees
  EOKeyValueQualifier qualifier = new EOKeyValueQualifier("name", EOQualifier.QualifierOperatorEqual, "Smith");
  return EOQualifier.filteredArrayWithQualifier(employees, qualifier);
 

Parameters:

key - the key path to a property that will be evaluated against value

selector - operator used to compare key's value to value

value - the value compared against key

See Also:

EOQualifier.filteredArrayWithQualifier(NSArray, EOQualifier), EOSQLExpression.sqlStringForKeyValueQualifier(EOKeyValueQualifier), EOQualifier.QualifierOperatorEqual, EOQualifier.QualifierOperatorNotEqual, EOQualifier.QualifierOperatorLessThan, EOQualifier.QualifierOperatorGreaterThan, EOQualifier.QualifierOperatorLessThanOrEqualTo, EOQualifier.QualifierOperatorGreaterThanOrEqualTo, EOQualifier.QualifierOperatorContains, EOQualifier.QualifierOperatorLike, EOQualifier.QualifierOperatorCaseInsensitiveLike

Method Detail

addQualifierKeysToSet

public void addQualifierKeysToSet(NSMutableSet qualKeys)

Implements the abstract version of this method defined in EOQualfier. Adds the receiver's qualifier keys to qualKeys. EOKeyValueQualifier adds its key to the set.

Specified by:

addQualifierKeysToSet in class EOQualifier

Parameters:

qualKeys - the set to which to add the receiver's qualifier keys

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

decodeObject

public static Object decodeObject(NSCoder coder)

(Re)creates an object based on type information and data stored in coder.

Parameters:

coder - the coder storing 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

equals

public boolean equals(Object other)

Compares the receiver to other. If other is an EOKeyValueQualifier and its key, value and selector are equal to the receiver's, this method returns true. If not, it returns false.

Parameters:

other - the object against which the receiver is compared

Returns:

true if the receiver the other object are equal; false otherwise

evaluateWithObject

public boolean evaluateWithObject(Object object)

Returns true if object satisfies the qualifier, false otherwise. When an EOKeyValueQualifier object receives the evaluateWithObject message, it evaluates object to determine if it meets the qualifier criteria. This method can throw one of several possible exceptions if an error occurs. If the application allows users to construct arbitrary qualifiers (such as through a user interface), you may want to write code to catch any exceptions and properly respond to errors (for example, by displaying a panel saying that the user typed a poorly formed qualifier).

Specified by:

evaluateWithObject in interface EOQualifierEvaluation

Overrides:

evaluateWithObject in class EOQualifier

Parameters:

object - the object which is evaluated with the receiver

Returns:

true if the object satisfies the qualifier; false otherwise

key

public String key()

Returns the key (possibly a key path) that the receiver uses when qualifying (for instance, with evaluateWithObject).

Returns:

the receiver's key (or key path)

See Also:

evaluateWithObject(Object), EOKeyValueQualifier(String, NSSelector, Object)

qualifierWithBindings

public EOQualifier qualifierWithBindings(NSDictionary bindings,
                                         boolean requiresAll)

Implements the abstract version of this method defined in EOQualfier. 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 (this method will return null).

Specified by:

qualifierWithBindings in class EOQualifier

Parameters:

bindings - the key-value pairs with which to create a new EOKeyValueQualifier

requiresAll - true if the "value" attribute of bindings must be non-null; false otherwise

Returns:

a new EOKeyValueQualifier if no errors occurred; null if requiresAll is false and value(s) were missing in bindings

Throws:

EOQualifier.QualifierVariableSubstitutionException - if requiresAll is true and values could not be properly extracted from bindings

selector

public NSSelector selector()

Returns the selector that the receiver uses when qualifying (for instance, with evaluateWithObject).

Returns:

the receiver's selector

See Also:

evaluateWithObject(Object), EOKeyValueQualifier(String, NSSelector, Object)

toString

public String toString()

Returns a String representation of the receiver containing its key, selector, and value.

Returns:

a String representation of the receiver

See Also:

key(), value(), selector()

validateKeysWithRootClassDescription

public 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 (or key is null), otherwise it just returns cleanly to indicate that the keys contained by the qualifier are valid.

Specified by:

validateKeysWithRootClassDescription in class EOQualifier

Parameters:

classDesc - the class description with which to validate the receiver's key

value

public Object value()

Returns the value that the receiver uses when qualifying (for instance, with evaluateWithObject).

Returns:

the receiver's value

See Also:

evaluateWithObject(Object), EOKeyValueQualifier(String, NSSelector, Object)