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, which can be modified by the RecordSortController.

The sorting information for groups can be found in the Groups collection returned by DataDefinition.getGroups(). You can obtain the sorting information for each group in the collection by calling IGroup.getSort(). The order of the objects in the Groups collection represents the order of groups in the report, as well as the order that group sorts are applied to the report data. If the report also has record sorts, they are applied after the group sorting.

If a group contains a summary, it may use summary sort, the order of summary sort can be ascending, descending, Top N, Bottom N, Top Percentage, or Bottom Percentage. 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 on summary sort, 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
 void addSummarySort(ITopNSort summarySort)
          Adds a group summary sort to the report DataDefinition.
 boolean canSortOn(IField field)
          For internal use only
 boolean canSortOn(IField field, boolean forGridCondition)
           Returns whether or not the field can be used to sort data.
 boolean canTopNSortOn(IField field)
          For internal use only
 ISort findSort(IField field)
           Retrieves a sort that corresponds to a field.
 void modify(int groupIndex, ISort newSort)
           Modifies a group primary sort.
 void modify(ISort oldSort, ISort newSort)
          For internal use only
 void modifySortDirection(int groupIndex, SortDirection direction)
           Modifies the direction of a primary group sort found by group index.
 void modifySortDirection(ISort sort, SortDirection direction)
          For internal use only
 void removeSummarySort(ITopNSort summarySort)
          Removes a group summary sort from the report DataDefinion.
 void reorderSummarySorts(int groupIndex, int fromIndex, int toIndex)
          For internal use only
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

canSortOn

public boolean canSortOn(IField field)
For internal use only


canSortOn

public boolean canSortOn(IField field,
                         boolean forGridCondition)

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, crosstab or detail chart. Only recurring fields can be sorted in report groups, and only recurring fields and formula fields can be sorted in crosstab and detail chart groups.

Parameters:
field - the field to sort data on
forGridCondition - true if field is used in crosstab or detail chart
Returns:
true if the field can be used to sort data, false otherwise

canTopNSortOn

public boolean canTopNSortOn(IField field)
For internal use only


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 groupIndex,
                   ISort newSort)
            throws ReportSDKException

Modifies a group primary sort. This API always modifies the group primary sort

Parameters:
groupIndex - The index of the group whose primary sort you will modify.
newSort - The new Sort object.
Throws:
ReportSDKException

modify

public void modify(ISort oldSort,
                   ISort newSort)
            throws ReportSDKException
For internal use only

Throws:
ReportSDKException

modifySortDirection

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

Modifies the direction of a primary group sort found by group 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. This API always modifies the direction of group primary sort.

Parameters:
groupIndex - the index of the group whose primary sort direction you will modify.
direction - the new direction of the sort as defined by SortDirection.
Throws:
java.lang.IllegalArgumentException - if the groupIndex parameter is negative or the direction parameter is null
ReportSDKException

modifySortDirection

public void modifySortDirection(ISort sort,
                                SortDirection direction)
                         throws ReportSDKException
For internal use only

Throws:
ReportSDKException

addSummarySort

public void addSummarySort(ITopNSort summarySort)
                    throws ReportSDKException

Adds a group summary sort to the report DataDefinition.

A group may have multiple summary sorts, but only if they are all of the sort type "All ascending" or "All descending". To use "Top N" summary sorting, the group may have only one summary sort. An exception will be thrown if this criteria is not met.

Note: The object model has limited support for multiple summary sorts. If a group contains more than one summary sort, only the primary group summary sort can be retrieved, via IGroup.getSort().

Parameters:
summarySort - The new summary sort object to add to the report. The group that the new sort is applied to is dictated by the new sort's sort field - see ISummaryField.getGroup().
Throws:
ReportSDKException

removeSummarySort

public void removeSummarySort(ITopNSort summarySort)
                       throws ReportSDKException

Removes a group summary sort from the report DataDefinion. If a group has multiple summary sorts, only the primary group sort can be removed.

Parameters:
summarySort - The summary sort object to remove from the report.
Throws:
ReportSDKException
See Also:
com.crystaldecisions.sdk.occa.report.data.IGroup#getSort IGroup.getSort()}

reorderSummarySorts

public void reorderSummarySorts(int groupIndex,
                                int fromIndex,
                                int toIndex)
                         throws ReportSDKException
For internal use only

Throws:
ReportSDKException