WebObjects 5.2

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

Last updated Fri Feb 21 13:15:00 PST 2003.

Copyright © 2003 Apple Computer, Inc.