com.sas.util
Class TransformingComparator

com.sas.util.TransformingComparator

All Implemented Interfaces:

com.sas.beans.PropertyChangeSource, com.sas.beans.VetoableChangeSource, com.sas.ComponentInterface, com.sas.LinkPropertiesInterface, com.sas.ModelInterface, com.sas.PublicClonable, com.sas.ViewInterface, MultipleValueEventSourceInterface, java.beans.PropertyChangeListener, java.io.ObjectInputValidation, java.io.Serializable, java.lang.Cloneable, java.util.Comparator, java.util.EventListener

public class TransformingComparator

A Comparator which run the items through a TransformInterface before comparing. This class is useful when you wish to sort objects by a field stored within the objects. For example, when you attach an ordered collection of objects on a list box, you can provide a display transform which is used to fetch a display value for each item; this value is displayed in the list box. If you wish to sort the collection, you probably want to sort it based on the same criteria with which the collection is displayed in the list box, i.e. the display transform. TransformingComparator serves this role by using a transform to obtain the sort key used when compariing items during a sort.

This class supports the use of either one or two transforms, to be applied to the left and right values when compare(Object, Object) is called. When comparing two items, a and b, the items are each passed through the transform objects to yield transformed values a_t and b_t and these results are compared using the comparator. For example, if you wish to sort raw data in a table date, but do so based on formatted values, you may use a TransformingComparator with an instance of FormatTransform Or, if you have formatted character data but you wish to compare the raw numbers, you can use a TransformingComparator with an instance of ParseTransform which parses strings into numeric values.

The transform may be null, which acts as the IdentityTransform. The comparison is deferred to another Comparator instance that is passed to the constructor. For example, this comparator may be a StringComparator if the tranformed values will be Strings. If no comparator is specified, the default instance of GenericComparator is used.

If you construct a TransformingComparator with just one transform, it is applied to both the left and right hand side. If a transform is null, then the corresponding value is not transformed.

The TransformingComparator comes in handy when you wish to compare two objects based on a string property of each. Write a simple transform which extracts that string value from the object, and use that in the constructor. Then, you need not build a special purpose Comparator for that class.

For example, if you have an interface I with a public String getText() method, use the following to sort a collection of instances which implement I:

 public class IToTextTransform
        implements com.sas.util.transforms.TransformInterface
 {
    public Object transform(Object object)
           throws com.sas.util.transforms.TransformException
    {
       try
       {
          return ((I) object)o.getText();
       }
       catch (Exception e)
       {
          throw new TransformException(e.getMessage());
       }
    }

    public static final IToTextTransform defaultInstance = new IToTextTransform();
 }

    ...
    collection.sort(new TransformingComparator( IToTextTransform.defaultInstance ));
 

Most times when sorting, you don't know if a given value will passed as the the left or right hand side to the compare method, so the majority of the time, you'll want to specify the same transform for both. But in match merge algorithms, you may have a fixed type for all left hand side operands, and a different fixed type for all the right hand operands, so you would want two transforms. Or, for searching, you may transform the lookup item once and use a null transform for the left hand side, and then apply the transform to all items in the search space.

Since:

1.2

See Also:

IdentityTransform, GenericComparator, Serialized Form

Field Summary

Fields inherited from class com.sas.util.StringComparator

defaultInstance

Fields inherited from interface com.sas.util.Comparator

EQUALS, GREATER_THAN, INCOMPARABLE, LESS_THAN

Constructor Summary

TransformingComparator()
Default constructor.

TransformingComparator(com.sas.util.Comparator comparator)
Default constructor.

TransformingComparator(com.sas.util.Comparator comparator, com.sas.util.transforms.TransformInterface transform)
Construct a TransformingComparator that uses the same transform for both the left and right values when comparing.

TransformingComparator(com.sas.util.Comparator comparator, com.sas.util.transforms.TransformInterface leftTransform, com.sas.util.transforms.TransformInterface rightTransform)
Construct a transform with specific tranforms for the left and right values.

Method Summary

int	compare(java.lang.Object left, java.lang.Object right) Compare the left object to the right object.
com.sas.util.Comparator	getComparator() Return the comparator that is used to compare the transformed values
com.sas.util.transforms.TransformInterface	getLeftTransform() Return the transform to use on the left side value in compare(Object, Object)
com.sas.util.transforms.TransformInterface	getRightTransform() Return the transform to use on the right side value in compare(Object, Object)
void	setComparator(com.sas.util.Comparator newComparator) Set the comparator that is used to compare the transformed values.
void	setLeftTransform(com.sas.util.transforms.TransformInterface newLeftTransform) Set the transform to use on the left side value in compare(Object, Object)
void	setRightTransform(com.sas.util.transforms.TransformInterface newRightTransform) Set the transform to use on the right side value in compare(Object, Object)

Methods inherited from class com.sas.util.StringComparator

clone, getCollator, getStartChar, isAscending, isCaseSensitive, setAscending, setCaseSensitive, setCollator, setStartChar, toString

Constructor Detail

TransformingComparator

public TransformingComparator()

Default constructor. This TransformingComparator will use the a GenericComparator.defaultInstance and a ParseTransform. The ParseTransform will convert String data to numeric values using the locale default number format. This constructor is an alias for new TransformingComparator(GenericComparator.defaultInstance, ParseTransform.defaultInstance)

TransformingComparator

public TransformingComparator(com.sas.util.Comparator comparator)

Default constructor. This TransformingComparator will use the a ParseTransform The ParseTransform will convert String data to numeric values using the locale default number format. This constructor is an alias for new TransformingComparator(comparator, ParseTransform.defaultInstance)

Parameters:

comparator - the comparator to compare the transformed values comparator.compare(a_t, b_t) If comparator is null, GenericComparator.defaultInstance is used.

TransformingComparator

public TransformingComparator(com.sas.util.Comparator comparator,
                              com.sas.util.transforms.TransformInterface transform)

Construct a TransformingComparator that uses the same transform for both the left and right values when comparing. This constructor is an alias for new TransformingComparator(comparator, transform, transform)

Parameters:

comparator - the comparator to compare the transformed values comparator.compare(a_t, b_t)

TransformingComparator

public TransformingComparator(com.sas.util.Comparator comparator,
                              com.sas.util.transforms.TransformInterface leftTransform,
                              com.sas.util.transforms.TransformInterface rightTransform)

Construct a transform with specific tranforms for the left and right values.

Parameters:

comparator - the comparator to compare the transformed values. If comparator is null, GenericComparator.defaultInstance is used. comparator.compare(a_t, b_t). You probably want to use TransformingComparator(Comparator comparator, TransformInterface transform) in most cases.

leftTransform - the transform to use on the left side value in compare(Object, Object)

rightTransform - the transform to use on the right side value in compare(Object, Object)

Method Detail

setComparator

public void setComparator(com.sas.util.Comparator newComparator)

Set the comparator that is used to compare the transformed values.

Parameters:

newComparator - the new value for the comparator property. If null, the GenericComparator.defaultInstance is used.

getComparator

public com.sas.util.Comparator getComparator()

Return the comparator that is used to compare the transformed values

Returns:

the value of the comparator property.

setLeftTransform

public void setLeftTransform(com.sas.util.transforms.TransformInterface newLeftTransform)

Set the transform to use on the left side value in compare(Object, Object)

Parameters:

newLeftTransform - the new value for the leftTransform property. If null, an IdentityTransform is used.

getLeftTransform

public com.sas.util.transforms.TransformInterface getLeftTransform()

Return the transform to use on the left side value in compare(Object, Object)

Returns:

the value of the leftTransform property.

setRightTransform

public void setRightTransform(com.sas.util.transforms.TransformInterface newRightTransform)

Set the transform to use on the right side value in compare(Object, Object)

Parameters:

newRightTransform - the new value for the rightTransform property. If null, an IdentityTransform is used.

getRightTransform

public com.sas.util.transforms.TransformInterface getRightTransform()

Return the transform to use on the right side value in compare(Object, Object)

Returns:

the value of the rightTransform property.

compare

public int compare(java.lang.Object left,
                   java.lang.Object right)

Compare the left object to the right object. The left object is first passed through the left transform; the right object is first passed through the right transform;

Specified by:

compare in interface java.util.Comparator

Overrides:

compare in class StringComparator

Parameters:

left - the left hand side of the comparison

right - the right hand side of the comparison

Returns:

LESS_THAN, EQUALS, GREATER_THAN, or INCOMPARABLE. If either of the transforms throws a TransformException, compare returns INCOMPARABLE

See Also:

Comparator.LESS_THAN, Comparator.EQUALS, Comparator.GREATER_THAN