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

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

public class GroupSortController
extends java.lang.Object

This class is used to modify how groups are sorted in a report. Each level of grouping in a report has a corresponding sort order. Reports may also contain 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.

If a group contains a summary, it may use a Top N sort. A Top N group sort selects the n groups with the highest value of the summary. For example, if the group contains a summary field that calculates the total sales for the group, you can use a Top N sort to select the groups with the top 10 highest sales figures. The other groups are either discarded or grouped together. For more details, see the TopNSort object.

To access the GroupSortController, use the getGroupSortController 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:
RecordSortController

Method Summary
 boolean canSortOn(IField field)
           Returns whether or not the field can be used to sort data.
 boolean canTopNSortOn(IField field)
           Returns whether or not a field can be used to perform a Top N sort.
 ISort findSort(IField field)
           Retrieves a sort that corresponds to a 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.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

canSortOn

public boolean canSortOn(IField field)

Returns whether or not the field can be used to sort data. Use this method to see whether or not a field may be used to sort data before adding a sort to a report. Only recurring fields can be sorted.

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

canTopNSortOn

public boolean canTopNSortOn(IField field)

Returns whether or not a field can be used to perform a Top N sort. Top N sorts are only performed on summary fields that are based on a group.

Use this method to determine if a field is a summary field based on a group before adding a Top N sort to a report. For example, you can perform a Top N summary on a report that is grouped by the "Country" field and contains a summary for the "Last Year's Sales" field for each country. This function will return true if you pass in the summary for "Last Year's Sales" as the argument.

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

findSort

public ISort findSort(IField field)
               throws ReportSDKException

Retrieves a sort that corresponds to a field. If the field has not been sorted on, then null is returned.

Parameters:
field - the field to find the sort for
Returns:
the sort for the field, or null if no sort is found
Throws:
java.lang.NullPointerException - if the field parameter is null
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 IDataDefinition.getGroups() 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 IDataDefinition.getGroups() 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

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:
java.lang.IllegalArgumentException - if the index parameter is negative or the direction parameter is null
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, may not be null
Throws:
java.lang.IllegalArgumentException - if the sort parameter or direction parameter is null
ReportSDKException