com.webobjects.eocontrol
Class EOSortOrdering

java.lang.Object
  |
  +--com.webobjects.eocontrol.EOSortOrdering

All Implemented Interfaces:

EOKeyValueArchiving, NSCoding, Serializable

public class EOSortOrdering

extends Object

implements Serializable, NSCoding, EOKeyValueArchiving

An EOSortOrdering object specifies the way that a group of objects should be sorted, using a property key and a method selector for comparing values of that property. EOSortOrderings are used both to generate SQL when fetching rows from a database server, and to sort objects in memory. EOFetchSpecification objects use an array of EOSortOrderings, which are applied in series to perform sorts by more than one property.

Sorting with SQL

When an EOSortOrdering is used to fetch data from a relational database, it's rendered into an ORDER BY clause for a SQL SELECT statement according to the concrete adaptor you're using. For more information, see the class description for EOSQLExpression. The Framework predefines symbols for four comparison selectors, listed in the table below. The table also shows an example of how the comparison selectors can be mapped to SQL.

Defined Name	SQL Expression
CompareAscending	(key) asc
CompareDescending	(key) desc
CompareCaseInsensitiveAscending	upper(key) asc
CompareCaseInsensitiveDescending	upper(key) desc

Using the mapping in the table above, the array of EOSortOrderings (nameOrdering) created in the following code example:

EOSortOrdering lastNameOrdering = EOSortOrdering.sortOrderingWithKey("lastName", EOSortOrdering.CompareAscending);
EOSortOrdering firstNameOrdering = (EOSortOrdering.sortOrderingWithKey("firstName", EOSortOrdering.CompareAscending);
NSMutableArray nameOrdering = new NSMutableArray();
nameOrdering.addObject(lastNameOrdering);
nameOrdering.addObject(firstNameOrdering);

results in this ORDER BY clause:

order by (lastName) asc, (firstName) asc

In-Memory Sorting

The methods sortedArrayUsingKeyOrderArray and sortArrayUsingKeyOrderArray are used to sort objects in memory. Given an array of objects and an array of EOSortOrderings, sortedArrayUsingKeyOrderArray returns a new array of objects sorted according to the specified EOSortOrderings. Similarly, sortArrayUsingKeyOrderArray sorts the provided array of objects in place. This code fragment, for example, sorts an array of Employee objects in place, by last name, then first name using the array of EOSortOrderings created above:

EOSortOrdering.sortArrayUsingKeyOrderArray(employees, nameOrdering);

See Also:

sortArrayUsingKeyOrderArray(com.webobjects.foundation.NSMutableArray, com.webobjects.foundation.NSArray), sortedArrayUsingKeyOrderArray(com.webobjects.foundation.NSArray, com.webobjects.foundation.NSArray), Serialized Form

Inner Class Summary

static interface	EOSortOrdering.Comparison The Comparison interface defines methods for comparing values.
static class	EOSortOrdering.ComparisonSupport ComparisonSupport provides default implementations of the EOSortOrdering.Comparison interface and a registry for support objects.

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

NSCoding.Support

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

EOKeyValueArchiving.Awaking, EOKeyValueArchiving.FinishInitialization, EOKeyValueArchiving.Support

Field Summary

static NSSelector	CompareAscending
static NSSelector	CompareCaseInsensitiveAscending
static NSSelector	CompareCaseInsensitiveDescending
static NSSelector	CompareDescending

Constructor Summary

EOSortOrdering(String key, NSSelector selector)
Creates a new EOSortOrdering object.

Method Summary

Class	classForCoder() Conformance to NSCoding.
static Object	decodeObject(NSCoder coder) Conformance to NSCoding.
static Object	decodeWithKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver) Conformance to EOKeyValueArchiving.
void	encodeWithCoder(NSCoder coder) Conformance to NSCoding.
void	encodeWithKeyValueArchiver(EOKeyValueArchiver archiver) Conformance to EOKeyValueArchiving.
String	key() Returns the key by which the receiver orders items.
NSSelector	selector() Returns the method selector used to compare values when sorting.
static void	sortArrayUsingKeyOrderArray(NSMutableArray array, NSArray sortOrderings) Sorts objects in array in place according to the EOSortOrderings in sortOrderings.
static NSArray	sortedArrayUsingKeyOrderArray(NSArray array, NSArray sortOrderings) Creates and returns a new array by sorting objects according to the EOSortOrderings in sortOrderings.
static EOSortOrdering	sortOrderingWithKey(String key, NSSelector selector) Creates an EOSortOrdering based on key and selector.
String	toString() Returns a description of the receiver.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

CompareAscending

public static final NSSelector CompareAscending

CompareCaseInsensitiveAscending

public static final NSSelector CompareCaseInsensitiveAscending

CompareCaseInsensitiveDescending

public static final NSSelector CompareCaseInsensitiveDescending

CompareDescending

public static final NSSelector CompareDescending

Constructor Detail

EOSortOrdering

public EOSortOrdering(String key,
                      NSSelector selector)

Creates a new EOSortOrdering object. If key and selector are provided, the new EOSortOrdering is initialized with them.

Parameters:

key - property key to sort objects by

selector - selector to use when comparing values for key in objects

See Also:

sortOrderingWithKey(java.lang.String, com.webobjects.foundation.NSSelector)

Method Detail

classForCoder

public Class classForCoder()

Conformance to NSCoding.

Specified by:

classForCoder in interface NSCoding

Returns:

the receiver's class

See Also:

NSCoding.classForCoder()

decodeObject

public static Object decodeObject(NSCoder coder)

Conformance to NSCoding.

Parameters:

coder - the NSCoder object used to create a new EOSortOrdering from

Returns:

the EOSortOrdering object described by the data in coder

decodeWithKeyValueUnarchiver

public static Object decodeWithKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver)

Conformance to EOKeyValueArchiving.

Parameters:

unarchiver - the EOKeyValueUnarchiver object that contains the state of the object to be decoded

Returns:

an EOSortOrdering object decoded from unarchiver

See Also:

EOKeyValueArchiver

encodeWithCoder

public void encodeWithCoder(NSCoder coder)

Conformance to NSCoding.

Specified by:

encodeWithCoder in interface NSCoding

Parameters:

coder - the NSCoder that will be the destination for class type and object information encoded by the receiver

encodeWithKeyValueArchiver

public void encodeWithKeyValueArchiver(EOKeyValueArchiver archiver)

Conformance to EOKeyValueArchiving.

Specified by:

encodeWithKeyValueArchiver in interface EOKeyValueArchiving

Parameters:

archiver - the EOKeyValueArchiver object to encode the receiver's state into

See Also:

EOKeyValueArchiver

key

public String key()

Returns the key by which the receiver orders items.

Returns:

the key the receiver orders items by

See Also:

selector()

selector

public NSSelector selector()

Returns the method selector used to compare values when sorting.

Returns:

the method selector used to compare values when sorting

See Also:

key()

sortArrayUsingKeyOrderArray

public static void sortArrayUsingKeyOrderArray(NSMutableArray array,
                                               NSArray sortOrderings)

Sorts objects in array in place according to the EOSortOrderings in sortOrderings. The objects are compared by extracting the sort properties using the NSKeyValueCoding method valueForKey and sending them compare... messages. See the table in "Sorting with SQL" for a list of the compare methods.

Parameters:

array - array of objects to sort

sortOrderings - an array of sort orderings to use to sort array by

See Also:

sortedArrayUsingKeyOrderArray(com.webobjects.foundation.NSArray, com.webobjects.foundation.NSArray)

sortOrderingWithKey

public static EOSortOrdering sortOrderingWithKey(String key,
                                                 NSSelector selector)

Creates an EOSortOrdering based on key and selector.

Parameters:

key - property key to sort objects by

selector - selector to use when comparing values for key in objects

Returns:

an EOSortOrdering based on key and selector

sortedArrayUsingKeyOrderArray

public static NSArray sortedArrayUsingKeyOrderArray(NSArray array,
                                                    NSArray sortOrderings)

Creates and returns a new array by sorting objects according to the EOSortOrderings in sortOrderings. The objects are compared by extracting the sort properties using the added EOKeyValueCoding method valueForKey and sending them compare... messages. See the table in "Sorting with SQL" for a list of the compare methods.

Parameters:

array - array of objects to sort

sortOrderings - array of EOSortOrderings to sort objects in array by

Returns:

an array containing the objects of array sorted according to sortOrderings

See Also:

sortArrayUsingKeyOrderArray(com.webobjects.foundation.NSMutableArray, com.webobjects.foundation.NSArray)

toString

public String toString()

Returns a description of the receiver.

Overrides:

toString in class Object

Returns:

a description string of the receiver