com.crystaldecisions.sdk.occa.report.application
Class RecordSortController

java.lang.Object
  extended by com.crystaldecisions.sdk.occa.report.application.RecordSortController

public class RecordSortController
extends java.lang.Object

This class is used to modify how records are sorted in a report. Reports that contain groups have group-level sorting in addition to record-level sorting.

The sorting information for both records and groups is stored in the Sorts collection. The Sorts collection contains an ordered list of Sort objects that are used to represent sorting information, including the field that is being sorted on and the sort direction. The order of the Sort objects in the Sorts collection is important because the data is first sorted by the Sort object at index 0, and then it is sorted by the Sort object at index 1, etc. By reordering the Sort objects in the Sorts collection, you change the order in which the report data is sorted.

For example, if there are two Sort objects in the Sorts collection, where the Sort object at index 0 is on a database field named "Country" and the Sort object at index 1 is on a database field named "Customer Name", the report will be sorted first by "Country" and then by "Customer Name". If the order of the two Sort objects in the Sorts collection is reversed, then the report will be sorted by "Customer Name" and then "Country".

When a group is added to the Groups collection, a corresponding Sort object is automatically created and added to the Sorts collection. Because group sorts need to be calculated before record sorts are calculated, and because groups automatically add Sort objects to the Sorts collection, it is recommended to add all of the groups (and therefore the group sorts) to a report before adding record sorts. This ensures that the order of the sorts in the Sorts collection matches the intended order.

To access the RecordSortController, use the getRecordSortController method in the DataDefController object.

Note: To display a field on a report, add it to the ResultFields collection. For more information about the ResultFields collection, see the ResultFieldController class description.

Note: The GroupSortController and RecordSortController classes replace the SortController class from previous releases.

See Also:


Method Summary
 int add(int index, ISort sort)
           Adds a record sort to the report.
static boolean canSortOn(IField field)
           Returns true if the field can be used to sort data, and false otherwise.
static boolean canTopNSortOn(IField field)
           Returns true if the field can be used to do a Top N sort, and false otherwise.
 ISort findSort(IField field)
           Retrieves a sort given a particular field.
 void modify(int index, ISort newSort)
           Modifies a sort.
 void modify(ISort oldSort, ISort newSort)
           Modifies a sort.
 void modifySortDirection(int index, SortDirection direction)
           Modifies the direction of a sort found by sort index.
 void modifySortDirection(ISort sort, SortDirection direction)
           Modifies the direction of a sort by sort index.
 void move(int nFrom, int nTo)
           Moves a Sort object from one position in the array to another.
 void move(ISort sort, int nTo)
           Moves a Sort object from one position in the array to another.
 void remove(int index)
           Removes a sort from the collection.
 void remove(ISort sort)
           Removes a sort from the collection.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

add

public int add(int index,
               ISort sort)
        throws ReportSDKException

Adds a record sort to the report. This method adds a sort object to the Sorts collection and returns the index of the sort after it has been added. This index is zero-based.

To add the Sort to the end of the Sorts collection, set the index parameter to -1. This causes the sort to be calculated after the other sorts have been calculated.

Before adding a sort to the report, use the canSortOn method to ensure that the field can be used to sort data.

The Sorts collection can be accessed through the getRecordSorts method in the DataDefinition object.

Parameters:
index - the position in the Sorts collection to add the ISort object, or -1 to add the object to the end of the collection
sort - the sort to add to the report
Returns:
the index of the sort in the Sorts collection
Throws:
ReportSDKException

canSortOn

public static boolean canSortOn(IField field)

Returns true if the field can be used to sort data, and false otherwise. Before adding a sort to the report, use this method to see if a particular field can be used to sort data. Only recurring fields can be sorted.

Parameters:
field - the field to sort on
Returns:
true if the field can be used to sort data, and false otherwise.

canTopNSortOn

public static boolean canTopNSortOn(IField field)

Returns true if the field can be used to do a Top N sort, and false otherwise. Only summary fields that are based on a group can be Top N sorted.

Use this method to check if the field that you want to sort data on is a summary field based on a group. For example, suppose that you have grouped your data by Country and summarized Last Year's Sales for each group. This function will return true if you pass in the summary field as the argument.

Parameters:
field - the field to Top N sort on
Returns:
true if the field can be used to do a Top N sort, and false otherwise

findSort

public ISort findSort(IField field)
               throws ReportSDKException

Retrieves a sort given a particular field. If the field has not been sorted on, null is returned.

Parameters:
field - The field that has (or has not) been used to sort on.
Returns:
An ISort object corresponding to the given field.
Throws:
ReportSDKException

modify

public void modify(int index,
                   ISort newSort)
            throws ReportSDKException

Modifies a sort. The collection of Sort objects can be accessed by using the getRecordSorts method in the DataDefinition object. The index is zero-based.

Parameters:
index - The index of the sort to be modified in the collection.
newSort - The new Sort object.
Throws:
ReportSDKException

modify

public void modify(ISort oldSort,
                   ISort newSort)
            throws ReportSDKException

Modifies a sort. The collection of Sort objects can be accessed by using the getSorts method in the DataDefinition object. The index is zero-based.

Parameters:
oldSort - The Sort object to be modified in the collection.
newSort - The new Sort object.
Throws:
ReportSDKException

move

public void move(int nFrom,
                 int nTo)
          throws ReportSDKException

Moves a Sort object from one position in the array to another. The collection of Sort objects can be accessed by using the getRecordSorts method in the DataDefinition object. The index is zero-based. The order of the Sort objects in the collection's array is important since it defines the order in which the fields will be sorted. The Sort object in item(0) will be sorted first.

Parameters:
nFrom - The index of the Sort object to be moved in the collection.
nTo - The new index position of the Sort object.
Throws:
ReportSDKException

move

public void move(ISort sort,
                 int nTo)
          throws ReportSDKException

Moves a Sort object from one position in the array to another. The collection of Sort objects can be accessed by using the getRecordSorts method in the DataDefinition object. The index is zero-based. The order of the Sort objects in the collection's array is important since it defines the order in which the fields will be sorted. The Sort object in item(0) will be sorted first.

Parameters:
sort - The Sort object to be moved in the collection.
nTo - The new index position of the Sort object.
Throws:
ReportSDKException

remove

public void remove(int index)
            throws ReportSDKException

Removes a sort from the collection. The collection of Sort objects can be accessed by using the getRecordSorts method in the DataDefinition object. The index is zero-based.

Parameters:
index - The index of the Sort object to be removed from the collection.
Throws:
ReportSDKException

remove

public void remove(ISort sort)
            throws ReportSDKException

Removes a sort from the collection. The collection of Sort objects can be accessed by using the getRecordSorts method in the DataDefinition object. The index is zero-based.

Parameters:
sort - The Sort object to be removed from the collection.
Throws:
ReportSDKException

modifySortDirection

public void modifySortDirection(int index,
                                SortDirection direction)
                         throws ReportSDKException

Modifies the direction of a sort found by sort index.

The sort direction can be changed from the existing sort direction to any one of ascending order, descending order, only sorting the bottom N items, only sorting the top N items, sorting the bottom N percentage, or the top N percentage as defined by SortDirection

Parameters:
index - the index of the sort whose direction you will modify. The sort index which is the Item property of the Sorts collection.
direction - the new direction of the sort as defined by SortDirection
Throws:
ReportSDKException

modifySortDirection

public void modifySortDirection(ISort sort,
                                SortDirection direction)
                         throws ReportSDKException

Modifies the direction of a sort by sort index.

The sort direction can be changed from the existing sort direction to any one of ascending order, descending order, only sorting the bottom N items, only sorting the top N items, sorting the bottom N percentage, or the top N percentage as defined by SortDirection

Parameters:
sort - the ISort object whose direction you will modify
direction - the new direction of the sort as defined by SortDirection
Throws:
ReportSDKException