WebObjects 5.4.2

com.webobjects.eocontrol
Class EOKeyComparisonQualifier

java.lang.Object
  extended by com.webobjects.eocontrol.EOQualifier
      extended by com.webobjects.eocontrol.EOKeyComparisonQualifier
All Implemented Interfaces:
EOKeyValueArchiving, EOQualifierEvaluation, NSCoding, Serializable

public class EOKeyComparisonQualifier
extends EOQualifier
implements NSCoding, EOKeyValueArchiving

EOKeyComparisonQualifier is a subclass of EOQualifier that compares a named property of an object with a named value of another object. For example, to return all of the employees whose salaries are greater than those of their managers, you might use an expression such as "salary > manager.salary", where "salary" is the left key and "manager.salary" is the right key. The "left key" is the property of the first object that's being compared to a property in a second object. The property in the second object is the "right key". Both the left key and the right key might be key paths. You can use EOKeyComparisonQualifier to compare properties of two different objects or to compare two properties of the same object.

EOKeyComparisonQualifier implements the EOQualifierEvaluation interface, which defines the method evaluateWithObject for in-memory evaluation. When an EOKeyComparisonQualifier 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, EOKeyComparisonQualifier 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:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class com.webobjects.eocontrol.EOQualifier
EOQualifier.Comparison, EOQualifier.ComparisonSupport, EOQualifier.QualifierVariableSubstitutionException
 
Nested classes/interfaces inherited from interface com.webobjects.foundation.NSCoding
NSCoding.Support
 
Nested classes/interfaces inherited from interface 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
EOKeyComparisonQualifier(String leftKey, NSSelector selector, String rightKey)
          Creates and returns a new EOKeyComparisonQualifier object that compares the properties named by leftKey and rightKey, using the operator method selector, one of the list below.
 
Method Summary
 void addQualifierKeysToSet(NSMutableSet qualKeys)
          Takes the receiver's leftKey and rightKey and inserts into qualKeys; null values are skipped.
 Class classForCoder()
          Allows the receiver to substitute a class other than its own (for example, a public superclass) for use during archiving (encoding) by an NSCoder.
static Object decodeObject(NSCoder coder)
          (Re)creates an object based on type information and data stored in coder.
static Object decodeWithKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver)
          Unarchives and returns the newly-unarchived object; provides conformance to the EOKeyValueArchiving interface.
 void encodeWithCoder(NSCoder coder)
          Archives the receiver's type information and data into coder.
 void encodeWithKeyValueArchiver(EOKeyValueArchiver archiver)
          Archives the receiver; provides conformance to the EOKeyValueArchiving interface.
 boolean equals(Object other)
          The comparison made between the receiver and other is done by each one of the EOKeyComparisonQualifier components.
 boolean evaluateWithObject(Object object)
          Returns true if the object object satisfies the qualifier, false otherwise.
 String leftKey()
          The property of the object that's being compared to a property in a second object.
 EOQualifier qualifierWithBindings(NSDictionary bindings, boolean requiresAll)
          Overriding EOQualifier's behavior.
 String rightKey()
          The property in the second object to be compared.
 NSSelector selector()
          The operator method used to do the comparison.
 String toString()
           
 void validateKeysWithRootClassDescription(EOClassDescription classDesc)
          Ensures that the receiver contains keys and key paths that belong to or originate from classDesc.
 
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

EOKeyComparisonQualifier

public EOKeyComparisonQualifier(String leftKey,
                                NSSelector selector,
                                String rightKey)
Creates and returns a new EOKeyComparisonQualifier object that compares the properties named by leftKey and rightKey, using the operator method selector, one of the list below.

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

For example, the following excerpt creates an EOKeyComparisonQualifier qual that has the left key lastName, the operator method EOQualifierOperatorEqual, and the right key member.lastName. Once constructed, the qualifier qual is used to filter an in-memory array. The code excerpt returns an array of Guest objects whose lastName properties have the same value as the lastName property of the guest's sponsoring member (this example is based on the Rentals sample database).

  <blockquote>
 
 NSArray guests;
 EOKeyComparisonQualifier qual = new EOKeyComparisonQualifier(lastName, EOQualifier.QualifierOperatorEqual, member.lastName);
 return (EOQualifier.filteredArrayWithQualifier(guests, qual));
 
 </blockquote>
 

Parameters:
leftKey - key path to first property
selector - the operator method used to compare
rightKey - key path to second property; compared against the leftKey
See Also:
EOQualifier, NSSelector
Method Detail

equals

public boolean equals(Object other)
The comparison made between the receiver and other is done by each one of the EOKeyComparisonQualifier components. The leftKey, rightKey and selctor of the receiver will be compared to the other object to find out if they are equal or not.

Overrides:
equals in class Object
Parameters:
other - the object against which the receiver is compared
Returns:
true if the input object is equal to the receiver; else false

evaluateWithObject

public boolean evaluateWithObject(Object object)
Returns true if the object object satisfies the qualifier, false otherwise. When an EOKeyComparisonQualifier object receives an 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 respect to the receiver's criteria
Returns:
true if the object object satisfies the qualifier, false otherwise
Throws:
IllegalArgumentException - (for example, if object is null)

leftKey

public String leftKey()
The property of the object that's being compared to a property in a second object.

Returns:
a String representing the receiver's left key
See Also:
EOKeyComparisonQualifier

selector

public NSSelector selector()
The operator method used to do the comparison.

Returns:
a NSSelector representiing the receiver's selector
See Also:
EOKeyComparisonQualifier

rightKey

public String rightKey()
The property in the second object to be compared.

Returns:
a String representiing receiver's right key
See Also:
EOKeyComparisonQualifier

toString

public String toString()
Overrides:
toString in class Object
Returns:
a string representing the receiver: the leftKey, the selector for comparison, and the rightKey.

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, otherwise the keys contained by the qualifier are valid.

Specified by:
validateKeysWithRootClassDescription in class EOQualifier
Parameters:
classDesc - bridge between enterprise objects and the metadata contained in an external source of information
Throws:
IllegalStateException - if one of the keys in the receiver is null or invalid

qualifierWithBindings

public EOQualifier qualifierWithBindings(NSDictionary bindings,
                                         boolean requiresAll)
Overriding EOQualifier's behavior. qualifierWithBindings in EOKeyComparisonQualifier simply returns the receiver.

Specified by:
qualifierWithBindings in class EOQualifier
Parameters:
bindings - the immutable dictionary of bindings
requiresAll - true if all the values need to match; else false
Returns:
the receiver

addQualifierKeysToSet

public void addQualifierKeysToSet(NSMutableSet qualKeys)
Takes the receiver's leftKey and rightKey and inserts into qualKeys; null values are skipped.

Specified by:
addQualifierKeysToSet in class EOQualifier
Parameters:
qualKeys - the input mutable set into which the receiver's keys are inserted

classForCoder

public Class classForCoder()
Allows the receiver to substitute a class other than its own (for example, a public superclass) for use during archiving (encoding) by an NSCoder. Default is the value of the getClass method.

Specified by:
classForCoder in interface NSCoding
Returns:
the Class to be used with an NSCoder
See Also:
EOKeyComparisonQualifier.encodeWithCoder(NSCoder coder), EOKeyComparisonQualifier.decodeObject(NSCoder coder), NSCoder, NSCoding

decodeObject

public static Object decodeObject(NSCoder coder)
(Re)creates an object based on type information and data stored in coder.

Parameters:
coder - stores object type information along with an object's data
Returns:
an Object (re)created from the data in coder.
See Also:
EOKeyComparisonQualifier.encodeWithCoder(NSCoder coder), NSCoder, NSCoding

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 - stores object type information along with an object's data
See Also:
EOKeyComparisonQualifier.decodeObject(NSCoder coder), EOKeyComparisonQualifier.classForCoder(), NSCoder, NSCoding

encodeWithKeyValueArchiver

public void encodeWithKeyValueArchiver(EOKeyValueArchiver archiver)
Archives the receiver; provides conformance to the EOKeyValueArchiving interface.

Specified by:
encodeWithKeyValueArchiver in interface EOKeyValueArchiving
Parameters:
archiver - the key-value archiver with which the receiver should be encoded
See Also:
EOKeyValueArchiving, EOKeyValueArchiver

decodeWithKeyValueUnarchiver

public static Object decodeWithKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver)
Unarchives and returns the newly-unarchived object; provides conformance to the EOKeyValueArchiving interface.

Parameters:
unarchiver - the key-value unarchiver with which the receiver should be decoded
See Also:
EOKeyValueArchiving, EOKeyValueArchiver

Last updated June 2008

Copyright © 2000-2008 Apple Inc.