Implement custom sorting and filtering in Refiner

Here we explain how you can customise Caplin Refiner's sorting and filtering behaviour.

Before you try any of the customisations detailed below, make sure you've read these pages: Refiner Overview, How can I configure Refiner and How can I filter and sort in Refiner.

The topics covered on this page are:

Custom sorting

When sorting a container, you can specify whether the field type is numeric or text. However, in some cases you might want to use your own logic to order field values, rather than a simple alphabetic or numeric comparison.

One example would be sorting a container of bonds by their credit ratings. The ordering used by Standard & Poor’s for upper-medium grade bonds and higher is:

However, if you sort these ratings with a normal ascending alphabetic sort, the resulting order is quite different:

To deal with problems such as this, you can customise the sort order. There are two ways to do this:

Custom sort lists

Custom sort lists provide a simple way to specify a custom sort order.

As an example, assume you need to sort container records on the value of the Tenor (settlement date) field, where the ordered list of tenor values is, starting from the earliest date:

SPOT,ON,TN,SN,1W,2W,1M,2M,6M,1Y

To define a custom sort based on an ordered list of values:

  • In the Deployment Framework​, open the file <Framework-root>/global_config/​overrides/RefinerService/Transformer/etc/refiner.properties
    (<Framework-root> is the topmost directory of the Framework).
  • Add a line of the form:
sorting.algorithm.<sort-name>=list:<item1>, <item2>,...

So to define the sort order of the Tenor field, you'd add:

sorting.algorithm.TenorSort=list:SPOT,ON,TN,SN,1W,2W,1M,2M,6M,1Y
Tip: For the full definition of the sorting.algorithm.<sort-name> property, see Refiner configuration properties.

Custom sort comparators

When you need to sort records where the logic defining the sort order is more complex than just a simple text / numeric comparison or ordered list of values, you can write your own custom sort comparator for Caplin Refiner.

Writing a custom sort comparator

The custom sort comparator is a Java class that implements the java.util.Comparator<String> interface. For detailed information on how to implement such a class, see the API reference documentation for the Java Platform Standard Edition (here's a link to the API documentation for the Java Platform Standard Edition 8).

During the sorting process, Caplin Refiner calls the compare() method of the custom sort comparator class:

int compare(String object1, String object2)

The method compares object1 against object2, and returns:

  • A negative integer if object1 is deemed to be less than object2.
  • Zero if object1 is deemed to be equal to object2.
  • A positive integer if object1 is deemed to be greater than object2.

When Caplin Refiner calls compare(), object1 and object2 are the field values of two records to be compared.

As an example, consider filtering a container of bonds by their credit ratings, where the Standard & Poor’s grading applies for upper-medium grade bonds and higher:

You could implement a custom sort comparator for this scheme, where the implemented compare() method would behave according to the following examples:

Compare() method call result explanation
compare("AA", "AAA")  -1 (AA is less than AAA)
compare("AA", "AA+") -1 (AA is less than AA+)
compare("AA", "AA")  0 (AA is equal to AA)
compare("AA", "AA-")  1 (AA is greater than AA-)
compare("AA", "A+") 1 (AA is greater than A+)
compare("AA", "A") 1 (AA is greater than A)
compare("AA-", "AA")  -1 (AA- is less than AA)
compare("AA+", "A+") 1 (AA+ is greater than A+)

For example purposes, the following sections assume the custom sort comparator class that implements this scheme is called com.example.BondRatingComparator.

Tip: If correctly implemented according to the specification of the java.util.Comparator<String> interface, a custom sort comparator can also be used as a custom filter comparator for the same record field (see Custom filter comparators ).

Deploying the custom sort comparator

The custom comparator class must be on the classpath for Caplin Refiner. To deploy the custom sort comparator, place the compiled jar in the Deployment Framework folder <Framework-root>/global_config/​overrides/RefinerService/Transformer/etc

Configuring the custom sort comparator

Assign the custom comparator a unique name that Caplin Refiner uses to determine when to use it for sorting:

  • Open the file <Framework-root>/global_config/​overrides/RefinerService/Transformer/etc/refiner.properties
  • Add a line of the form:
sorting.algorithm.<sort-name>=class:<comparator-class>

where <sort-name> is the unique name for your custom sort comparator, and​ <comparator-class> is the fully qualified class name of the comparator.

For example:

sorting.algorithm.BondRating=class:com.example.BondRatingComparator
Tip: For the full definition of the sorting.algorithm.<sort-name> property, see Refiner configuration properties.

Using a custom sort in client code

To use a custom sort in a client application, call the appropriate API methods provided in the StreamLink library that your application uses.

Custom filter comparators

You may need to filter records where the logic defining how the records match the filter is more complex than just a simple text or numeric comparison. In this case, you can write your own custom filter comparator for Caplin Refiner.

Writing a custom filter comparator

The custom filter comparator is a Java class that implements the java.util.Comparator<String> interface.

For information on how to implement such a class, see the API reference documentation for the Java Platform Standard Edition. For detailed information on how to implement such a class, see the API reference documentation for the Java Platform Standard Edition (here's a link to the API documentation for the Java Platform Standard Edition 8).

During the filtering process, Caplin Refiner calls the compare() method of the custom filter comparator class, passing the value of the criterion you are filtering against and the field value of the record to be compared. Your custom code must return a value which represents how the record value compares to the filter criterion:

int compare(String object1, String object2)

The method compares object1 against object2, and returns:

  • A negative integer if object1 is deemed to be less than object2.
  • Zero if object1 is deemed to be equal to object2.
  • A positive integer if object1 is deemed to be greater than object2.

When Caplin Refiner calls compare(), object1 is the value of the filter criterion, and object2 is the corresponding field value of the record being filtered.

As an example, consider filtering a container of bonds by their credit ratings, where the Standard & Poor’s grading applies for upper-medium grade bonds and higher:

The implemented compare() method should behave according to the following examples:

Compare() method CALL result explanation
compare("AA", "AAA")  -1 (AA is less than AAA)
compare("AA", "AA+") -1 (AA is less than AA+)
compare("AA", "AA")  0 (AA is equal to AA)
compare("AA", "AA-")  1 (AA is greater than AA-)
compare("AA", "A+") 1 (AA is greater than A+)
compare("AA", "A") 1 (AA is greater than A)
compare("AA-", "AA")  -1 (AA- is less than AA)
compare("AA+", "A+") 1 (AA+ is greater than A+)

At run-time, Caplin Refiner's filtering software calls the compare() method as:

compare(value, record-field);

So, if at run-time the filter is (rating<AA), the method is called as

compare("AA", rating);

and all comparisons returning 1 pass the filter.

Therefore only bonds with rating AA-, A+, or A are returned to the client.

If instead the filter is (rating>=AA), all comparisons returning -1 or 0 pass the filter, so only bonds with rating AA, AA+, or AAA are returned to the client.

Tip: If correctly implemented according to the specification of the java.util.Comparator<String> interface, a custom filter comparator can also be used as a custom sort comparator for the same record field (see Custom sort comparators ).

For example purposes, the following sections assume the custom filter comparator class is called com.example.BondRatingComparator.

Deploying the custom filter comparator

The custom comparator class must be on the classpath for Caplin Refiner.  To deploy the custom filter comparator, place the compiled jar in the Deployment Framework folder <Framework-root>/global_config/​overrides/RefinerService/Transformer/etc

Configuring the custom filter comparator

Assign the custom comparator a unique name that Caplin Refiner uses to determine when to use it for filtering:

  • Open the file <Framework-root>/global_config/​overrides/RefinerService/Transformer/etc/refiner.properties​
  • Add a line of the form:
filtering.algorithm.<filter-name>=<comparator-class>

where <filter-name> is the unique name for your custom filter comparator and <comparator-class> is the fully qualified class name of the comparator.

For example:

filtering.algorithm.BondRating=com.example.BondRatingComparator
Tip: For the full definition of the filtering.algorithm.<filter-name> property, see Refiner configuration properties.

Using a custom filter in client code

To use a custom filter in a client application, call the appropriate API methods provided in the StreamLink library that your application uses.


See also: