Documentation Archive Developer
Search
PATH Documentation > WebObjects

Table of Contents

EOSortOrdering


Inherits from:
Object
Implements:
EOKeyValueArchiving
NSCoding
Serializable
Package:
com.webobjects.eocontrol


Class Description


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:


SortOrdering.sortVectorUsingKeyOrderVector(employees, nameOrdering);




Constants


EOSortOrdering defines the following NSSelector constants:


Defined Name Method
CompareAscending compareAscending
CompareDescending compareDescending
CompareCaseInsensitiveAscending compareCaseInsensitiveAscending
CompareCaseInsensitiveDescending compareCaseInsensitiveDescending

The first two can be used with any value class; the second two with NSString objects only. The sorting methods extract property values using key-value coding and apply the selectors to the values. If you use custom value classes, you should be sure to implement the appropriate comparison methods to avoid exceptions when sorting objects.



Interfaces Implemented


NSCoding
classForCoder
decodeObject
encodeWithCoder
EOKeyValueArchiving
decodeWithKeyValueUnarchiver
encodeWithKeyValueArchiver


Method Types


Constructors
EOSortOrdering
Examining a sort ordering
key
selector
In-memory sorting
sortedArrayUsingKeyOrderArray
sortArrayUsingKeyOrderArray


Constructors



EOSortOrdering

public EOSortOrdering( String key, NSSelector selector)

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

See Also: EOSortOrdering




Static Methods



decodeObject

public static Object decodeObject(NSCoder coder)

Conformance to NSCoding.

decodeWithKeyValueUnarchiver

public static Object decodeWithKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver)

Conformance to EOKeyValueArchiving.

sortArrayUsingKeyOrderArray

public static void sortArrayUsingKeyOrderArray( NSMutableArray objects, NSArray sortOrderings)

Sorts objects 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.

See Also: sortedArrayUsingKeyOrderArray



sortOrderingWithKey

public static EOSortOrdering sortOrderingWithKey( String key, NSSelector selector)

Creates and returns an EOSortOrdering based on key and selector.

See Also: EOSortOrdering constructor



sortedArrayUsingKeyOrderArray

public static NSArray sortedArrayUsingKeyOrderArray( NSArray objects, 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.


Instance Methods



classForCoder

public Class classForCoder()

Conformance to NSCoding.

encodeWithCoder

public void encodeWithCoder(NSCoder coder)

Conformance to NSCoding.

encodeWithKeyValueArchiver

public void encodeWithKeyValueArchiver(EOKeyValueArchiver archiver)

Conformance to EOKeyValueArchiving.

key

public String key()

Returns the key by which the receiver orders items.

See Also: selector



selector

public NSSelector selector()

Returns the method selector used to compare values when sorting.

See Also: key



toString

public String toString()

Description forthcoming.

© 2001 Apple Computer, Inc. (Last Published April 19, 2001)


Table of Contents