ptolemy.actor.util
Interface CQComparator

All Superinterfaces:
java.util.Comparator
All Known Implementing Classes:
TimedEvent.TimeComparator, TMEventComparator

public interface CQComparator
extends java.util.Comparator

This interface extends the java.util.Comparator interface, which defines the compare() method. The extension defines additional methods that specifically support the CalendarQueue class. That class needs to associate an entry in the queue with a virtual bin number, and needs to be able to periodically recompute the width of its bins. Thus, merely being able to compare entries is not sufficient.

Since:
Ptolemy II 0.2
Version:
$Id: CQComparator.java,v 1.30 2004/04/13 03:11:43 cxh Exp $
Author:
Lukito Muliadi, Edward A. Lee
See Also:
CalendarQueue, Comparator
Accepted Rating:
Yellow (liuj)
Proposed Rating:
Green (eal)

Method Summary
 long getVirtualBinNumber(java.lang.Object entry)
          Given an entry, return a virtual bin number for the entry.
 void setBinWidth(java.lang.Object[] entryArray)
          Given an array of entries, set an appropriate bin width for a calendar queue to hold these entries.
 void setZeroReference(java.lang.Object zeroReference)
          Set the zero reference, to be used in calculating the virtual bin number.
 
Methods inherited from interface java.util.Comparator
compare, equals
 

Method Detail

getVirtualBinNumber

public long getVirtualBinNumber(java.lang.Object entry)
Given an entry, return a virtual bin number for the entry. The virtual bin number is a quantized version of whatever key is being used to compare entries. The calculation performed should be something like:

(entry - zeroReference) / binWidth,

with the result cast to long.

Classes that implement this interface will in general need to perform a downcast on the arguments (of type Object) to the appropriate user defined classes. If the arguments are not of appropriate type, the implementation should throw a ClassCastException. Note that this method cannot return long.MAX_VALUE, which is used internally by the CalendarQueue.

Parameters:
entry - An object that can be inserted in a calendar queue.
Returns:
The index of the bin.

setBinWidth

public void setBinWidth(java.lang.Object[] entryArray)
Given an array of entries, set an appropriate bin width for a calendar queue to hold these entries. This method assumes that the entries provided are all different, and are in increasing order. Ideally, the bin width is chosen so that the average number of entries in non-empty bins is equal to one. If the argument is null set the default bin width.

Parameters:
entryArray - An array of entries.

setZeroReference

public void setZeroReference(java.lang.Object zeroReference)
Set the zero reference, to be used in calculating the virtual bin number.

Parameters:
zeroReference - The starting point for bins.