senselogic.sitevision.api.node

Interface NodeComparatorUtil

@Requireable(value="NodeComparatorUtil")
public interface NodeComparatorUtil

Node comparator utility interface.

Node comparators created by this utility can be used for easy node comparison and when sorting a collection of nodes via Collections.sort(List<Node>, Comparator<Node>) or such.

An instance of the Sitevision class implementing this interface can be obtained via Utils.getNodeComparatorUtil(). See Utils for how to obtain an instance of the Utils interface.

Since:

Sitevision 3.6

Author:

Magnus Lövgren

Method Summary

Modifier and Type	Method and Description
Comparator<Node>	getCalendarPropertyComparator(String aCalendarPropertyName) Returns a comparator that compares nodes by the value of a calendar property.
CompoundComparatorBuilder	getCompoundComparatorBuilder() Gets a builder for creating a compound comparator that allows comparison based on multiple node comparators.
Comparator<Node>	getIntPropertyComparator(String aIntPropertyName) Returns a comparator that compares nodes by the value of a calendar property.
Comparator<Node>	getPropertyComparator(String aPropertyName) Returns a comparator that compares nodes by the string value of a property in a case-insensitive manner.
Comparator<Node>	getPropertyComparator(String aPropertyName, Locale aLocale) Returns a comparator that compares nodes by the string value of a property in a case-insensitive manner using a specified locale.
<V extends Comparable> Comparator<Node>	getResolverComparator(Resolver<Node,V> aResolver) Gets a comparator that compares nodes by the values extracted by a resolver.
Comparator<Node>	getReversedComparator(Comparator<Node> aNodeComparator) Returns a comparator that reverses the result of another.

Method Detail

getPropertyComparator

Comparator<Node> getPropertyComparator(String aPropertyName)

Returns a comparator that compares nodes by the string value of a property in a case-insensitive manner.

This is a convenience for the getPropertyComparator(String, java.util.Locale) method, using the current locale as returned by PortletContextUtil.getCurrentLocale().

Example
This Velocity code will sort the $listOfNodes List by comparing the 'displayName' property for each Node

    #set ($nodeComparatorUtil = $sitevisionUtils.NodeComparatorUtil)
    #set ($displayNameComparator = $nodeComparatorUtil.getPropertyComparator('displayName'))

    #set ($instanceCreatorUtil = $sitevisionUtils.InstanceCreatorUtil)
    #set ($collections = $instanceCreatorUtil.CollectionsInstance)

    $collections.sort($listOfNodes, $displayNameComparator)
 

Note! This comparator imposes orderings that are inconsistent with equals.

Parameters:

aPropertyName - the name of the property

Returns:

a comparator

See Also:

getPropertyComparator(String, java.util.Locale)

getPropertyComparator

Comparator<Node> getPropertyComparator(String aPropertyName,
                                       Locale aLocale)

Returns a comparator that compares nodes by the string value of a property in a case-insensitive manner using a specified locale.

The property value will be extracted as a string using PropertyUtil, and a null value will be treated as an empty string.

Why using proper Locale is important

The comparators returned from this method will rely on a Collator and they have different comparison rules for different locales. The returned comparator might give unexpected results if a locale is used that doesn't match actual property values. This is best illustrated by an example of how typical swedish values will be compared with different locales. Assume we have a List of nodes that should be compared by a certain property and these are the actual string values for the property of the nodes in the list:

"a", "A", "b", "B", "z", "Z", "å", "Å", "ä", "Ä", "ö", "Ö"

When using the Collections.sort(List<Node>, Comparator<Node>) method to sort the list, this is how they typically(*) will be sorted with different locales:

Some examples

Locale	Result (*)
Swedish	"a", "A", "b", "B", "z", "Z", "å", "Å", "ä", "Ä", "ö", "Ö"
Norwegian	"a", "A", "b", "B", "z", "Z", "ä", "Ä", "ö", "Ö", "å", "Å"
English	"a", "A", "å", "Å", "ä", "Ä", "b", "B", "ö", "Ö", "z", "Z"
German	"a", "A", "å", "Å", "ä", "Ä", "b", "B", "ö", "Ö", "z", "Z"

(* this comparator is case-insensitive so ["a", "A"] can as well be ordered ["A", "a"] depending on initial order)

Note! This comparator imposes orderings that are inconsistent with equals.

Parameters:

aPropertyName - the name of the property. Note! If aPropertyName is null or whitespace only, the returned comparator will be non-comparing, i.e. a NO-OP comparator that always will return 0 ("equal") for all nodes.

aLocale - the locale that should be used when comparing two properties. If aLocale is null, the current locale (as of PortletContextUtil.getCurrentLocale() will be used).

Returns:

a comparator

getCalendarPropertyComparator

Comparator<Node> getCalendarPropertyComparator(String aCalendarPropertyName)

Returns a comparator that compares nodes by the value of a calendar property.

The property value will be extracted as a calendar using PropertyUtil, and comparing a null value will result in -1 (i.e. less than a non-null).

Note! This comparator imposes orderings that are inconsistent with equals.

Parameters:

aCalendarPropertyName - the name of the calendar property Note! If aCalendarPropertyName is null or whitespace only, the returned comparator will be non-comparing, i.e. a NO-OP comparator that always will return 0 ("equal") for all nodes.

Returns:

a comparator

Since:

Sitevision 3.6.3

getIntPropertyComparator

Comparator<Node> getIntPropertyComparator(String aIntPropertyName)

Returns a comparator that compares nodes by the value of a calendar property.

The property value will be extracted as an int using PropertyUtil, and a no value value will be treated as 0.

Note! This comparator imposes orderings that are inconsistent with equals.

Parameters:

aIntPropertyName - the name of the int property Note! If aIntPropertyName is null or whitespace only, the returned comparator will be non-comparing, i.e. a NO-OP comparator that always will return 0 ("equal") for all nodes.

Returns:

a comparator

Since:

Sitevision 3.6.3

getReversedComparator

Comparator<Node> getReversedComparator(Comparator<Node> aNodeComparator)

Returns a comparator that reverses the result of another.

The compareTo method of this comparator multiplies the result of another comparator's compareTo method with -1. This will typically lead to a completely reversed order when sorted.

Note! This comparator imposes orderings that are inconsistent with equals.

Parameters:

aNodeComparator - a comparator Note! If aNodeComparator is null, the returned comparator will be non-comparing, i.e. a NO-OP comparator that always will return 0 ("equal") for all nodes.

Returns:

a comparator

Since:

Sitevision 3.6.3

getCompoundComparatorBuilder

CompoundComparatorBuilder getCompoundComparatorBuilder()

Gets a builder for creating a compound comparator that allows comparison based on multiple node comparators.

Returns:

a CompoundComparatorBuilder

Since:

Sitevision 3.6.3

getResolverComparator

<V extends Comparable> Comparator<Node> getResolverComparator(Resolver<Node,V> aResolver)

Gets a comparator that compares nodes by the values extracted by a resolver.

Example
This Comparator can be helpful when you want to sort sv:collaborationGroup nodes in "most active" order. An example of how this can be implemented this in server-side Javascript is demonstrated below:

    var myIdentity = require('PortletContextUtil').getCurrentUserIdentity(),
       userIdentityWrapper = require('UserFactory').getUserIdentityWrapper(myIdentity),
       myGroups,
       group,
       count,
       i;

    if (userIdentityWrapper) {
       myGroups = userIdentityWrapper.getCollaborationGroups();
       myGroups = toSortedList(myGroups);
       count = myGroups.size();

       // Render my groups
       for (i = 0; i < count; i++) {
          group = myGroups.get(i);
          ...
       }
    }

    // Helper function that uses a ResolverComparator to sort a collection of Collaboration groups
    function toSortedList(groups) {
       var sortedGroups = require('InstanceCreatorUtil').getList(),
          collections,
          groupDateResolver,
          resolverComparator;

       sortedGroups.addAll(groups); // Wrap in list to make it sortable

       if (sortedGroups.size() > 1) {
          // Create a resolver that can resolve appropriate Date from a collaboration group
          groupDateResolver = require('NodeResolverUtil').getCollaborationDateResolver();

          // Create a comparator that compares values extracted by the resolver
          resolverComparator = require('NodeComparatorUtil').getResolverComparator(groupDateResolver);

          // Get Collections and Sort!
          collections = require('CollectionsInstance');
          collections.sort(sortedGroups, resolverComparator);
          collections.reverse(sortedGroups); // ...and reverse result to get 'latest' first
       }
       return sortedGroups;
    }
 

Note! Beware of resolved null values (null will always be "less" than a non-null)!

Type Parameters:

V - The comparable value type

Parameters:

aResolver - the node value resolver

Returns:

a node comparator. Note! If aResolver is null, the returned comparator will be non-comparing, i.e. a NO-OP comparator that always will return 0 ("equal") for all nodes.

Since:

Sitevision 4.1

See Also:

NodeResolverUtil