com.webobjects.eocontrol
Class EOKeyComparisonQualifier

java.lang.Object
  com.webobjects.eocontrol.EOQualifier
      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 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

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.

• 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 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).

 

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

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

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:

encodeWithCoder(NSCoder coder), 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:

encodeWithCoder(NSCoder coder), NSCoder, NSCoding

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

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:

decodeObject(NSCoder coder), 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

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.

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

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

rightKey

public String rightKey()

The property in the second object to be compared.

Returns:

a String representiing receiver's right 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

toString

public String toString()

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