Sorting

The sort method

The Module class sort method is used to order a set of matching records once the search of a module has been run.

Arguments

This sort method takes two arguments:

  • columns

    The columns argument is used to specify the columns by which to sort the result set. The argument can be either a String, String[] or a ArrayList<String>. Each string can be a simple column name or a set of column names, separated by semi-colons or commas.

    Each column name can be preceded by a + (plus) or - (minus or dash). A leading + indicates that the records should be sorted in ascending order. A leading - indicates that the records should be sorted in descending order.

    Note: If a sort order ("+" or "-") is not given, the sort order defaults to ascending.

  • flags

    The flags argument is used to pass one or more flags to control the way the sort is carried out. As with the columns argument, the flags argument can be either a String, String[] or a ArrayList<String>. Each String can be a single flag or a set of flags separated by semi-colons or commas.

    The following flags control the type of comparisons used when sorting:

    • word-based

      Sort disregards all punctuation and white spaces (more than the one space between words). For example:

      Traveler's        Inn

      will be sorted as

      Travelers Inn
    • full-text

      Sort includes all punctuation and white spaces. For example:

      Traveler's        Inn

      will be sorted as

      Traveler's        Inn

      and will therefore differ from:

      Traveler's Inn
    • compress-spaces

      Sort includes punctuation but disregards all white space (with the exception of a single space between words). For example:

      Traveler's        Inn

      will be sorted as

      Traveler's Inn

      Note: If none of these flags is included, the comparison defaults to word-based.

    The following flags modify the sorting behaviour:

    • case-sensitive

      Sort is sensitive to upper and lower case. For example:

      Melbourne gallery

      will be sorted separately to

      Melbourne Gallery
    • order-insensitive

      Values in a multi-value field will be sorted alphabetically regardless of the order in which they display. For example, a record which has the following values in the NamRoles_tab column in this order:

      1. Collection Manager
2. Curator
3. Internet Administrator

      and another record which has the values in this order:

      1. Internet Administrator
2. Collection Manager
3. Curator

      will be sorted the same.

    • null-low

      Records with empty columns will be placed at the start of the result set rather than at the end.

    • extended-sort

      Values that include diacritics will be sorted separately to those that do not. For example:

      entrée

      will be sorted separately to

      entree

    The following flags can be used when generating a summary of the sorted records:

    • report

      A summary of the sort is generated. The summary report is a hierarchically structured object that summarises the number of unique values contained in the sort columns. See Return Value and Example for a description and illustration of the returned structure.

    • table-as-text

      All data from multi-valued columns will be treated as a single value (joined by line break characters) in the summary results array. For example, for a record which has the following values in the NamRoles_tab column:

      Collection Manager, Curator, Internet Administrator

      the summary will include statistics for a single value:

      Collection Manager
      Curator
      Internet Administrator

      Thus the number of values in the summary results display will match the number of records.

      If this option is not included, each value in a multi-valued column will be treated as a distinct value in the summary. Thus there may be many more values in the summary results than there are records.

For example:

  1. Sort parties by first name (ascending):
    Module parties = new Module("eparties", session);
Terms search = new Terms();
search.add("NamLast", "Smith");
long hits = parties.findTerms(search);

parties.sort("NamFirst");
  2. Sort parties by title (ascending) and then first name (descending):
    String[] sort =
{
    "NamTitle",
    "-NamFirst"
};
parties.sort(sort);

  3. Run a case-sensitive sort of parties by title (ascending) and then first name (descending):

    String[] sort =
{
    "NamTitle",
    "-NamFirst"
};
String[] flags =
{
    "case-sensitive",
};
parties.sort(sort, flags);

The sort method returns null unless the report flag is used.

If the report flag is used, the sort method returns a ModuleSortResult object. This object contains two read-only properties:

  • count

    An int (accessed using the getCount method) specifying the number of distinct terms in the primary sort key.

  • terms

    A ModuleSortTerm[] (accessed using the getTerms method) containing the list of distinct terms associated with the primary key in the sorted result set.

This ModuleSortTerm object contains three read-only properties which describe the term:

  • value

    A String (accessed using the getValue method) that is the distinct value itself.

  • count

    A long (accessed using the getCount method) specifying the number of records in the result set which have the value.

  • nested

    A ModuleSortResult object (accessed using the getNested method) that holds the values for secondary sorts within the primary sort.

This is illustrated in the following example.

This example shows a three-level sort by title, last name (descending) and first name on a set of Parties records:

import com.kesoftware.imu.*;

public class Summary
{
    public static void main(String[] args) throws Exception
    {
        Session session = new Session("imu.mel.kesoftware.com", 40136);
        Module parties = new Module("eparties", session);

        Terms search = new Terms(TermsKind.OR);
        search.add("NamLast", "Smith");
        search.add("NamLast", "Wood");

        parties.findTerms(search);
        
        String[] sort =
        {
            "NamTitle",
            "-NamLast",
            "NamFirst"
        };
        String[] flags =
        {
            "report"
        };
        ModuleSortResult report = parties.sort(sort, flags);
        showSummary(report, 0);
        System.exit(0);
    }

    private static void showSummary(ModuleSortResult report, int indent)
    {
        String prefix = "";
        for (int i = 0; i < indent; i++)
            prefix += "  ";
        
        ModuleSortTerm[] terms = report.getTerms();
        for (int i = 0; i < terms.length; i++)
        {
            ModuleSortTerm term = terms[i];

            String value = term.getValue();
            long count = term.getCount();
            System.out.format("%s%s (%d)%n", prefix, value, count);

            ModuleSortResult nested = term.getNested();
            if (nested != null)
                showSummary(nested, indent + 1);
        }
    }
}

This displays the distinct terms (and their counts) for the primary sort key (title). Nested under each primary key is the set of distinct terms and counts for the secondary key (last name) and nested under each secondary key is the set of distinct terms and counts for the tertiary key (first name):

Mr (2)

 Wood (1)

  Gerard (1)

 SMITH (1)

  Ian (1)

Ms (1)

 ECCLES-SMITH (1)

  Kate (1)

Sir (1)

 Wood (1)

  Henry (1)

(3)

 Wood (1)

  Grant (1)

Smith (2)

 Sophia (1)

 William (1)

If another sort key was specified its terms would be nested under the tertiary key and so on.

Note: In the example above some of the records do not have a value for the primary sort key (title). By default these values are sorted after any other values. They can be sorted before other values using the null-low flag.