WebObjects 5.2.3

com.webobjects.eocontrol
Class EOKeyValueQualifier

java.lang.Object
  extended bycom.webobjects.eocontrol.EOQualifier
      extended bycom.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:

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)

Last updated Thu Oct 21 15:04:16 PDT 2004.

Copyright © 2004 Apple Computer, Inc.