com.graphaware.common.util

Class BoundedSortedList<T,C extends Comparable<C>>

java.lang.Object

com.graphaware.common.util.BoundedSortedList<T,C>

Type Parameters:

T - type of the stored items.

C - type of the quantities associated with the items.

public class BoundedSortedList<T,C extends Comparable<C>>
extends Object

A thread-safe sorted list of items and related quantities, which is bounded by a configurable maximum capacity. Intended for frequent writes and occasional reads.

The list is at all times sorted by the provided quantity comparator (natural ordering by default). Adding an element that would be added after the last element of the list has no effect if the list if already full. Adding an element to any position in the list means that the last element will be discarded. Adding an element that already exists in the list is equivalent to removing the element and adding it again.

Note that the list can be configured with a capacity and maxCapacity. An example will be used to illustrate the difference. Let's say we want to keep track of 3 most popular items, where popularity is an integer number of likes. In that case we would construct a list of capacity 3. However, if that really was the capacity of the list, then after adding items with 100, 90, and 80 likes respectively would mean that an item with 79 likes will be ignored. Then, if the last item in the list is "unliked" by 10 people, we end up with a list of 100, 90, and 70. This is not the truth, since there is an item with 79 likes, which we've ignored. To account for these scenarios, it is possible to provide a maxCapacity, which adds some extra space to the list. In the example above, a capacity of 3 and maxCapacity of 4 would prevent the anomaly, since we would remember (but not show) the item with 79 likes.

Constructor Summary

Constructors

Constructor and Description
BoundedSortedList(int capacity) Construct a new list.
BoundedSortedList(int capacity, Comparator<C> comparator) Construct a new list.
BoundedSortedList(int capacity, int maxCapacity) Construct a new list.
BoundedSortedList(int capacity, int maxCapacity, Comparator<C> comparator) Construct a new list.

Method Summary

Modifier and Type	Method and Description
void	add(T item, C quantity) Add an item and its associated quantity to the list.
List<T>	getItems() Get a items of this list.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BoundedSortedList

public BoundedSortedList(int capacity)

Construct a new list. Items are ordered using the natural ordering of associated quantities.

Parameters:

capacity - capacity (and maxCapacity) of the list.

BoundedSortedList

public BoundedSortedList(int capacity,
                         Comparator<C> comparator)

Construct a new list.

Parameters:

capacity - capacity (and maxCapacity) of the list.

comparator - comparator for the quantities.

BoundedSortedList

public BoundedSortedList(int capacity,
                         int maxCapacity)

Construct a new list. Items are ordered using the natural ordering of associated quantities.

Parameters:

capacity - capacity of the list (as perceived by users).

maxCapacity - real capacity of the underlying list to mitigate the anomaly described in Javadoc of the class.

BoundedSortedList

public BoundedSortedList(int capacity,
                         int maxCapacity,
                         Comparator<C> comparator)

Construct a new list.

Parameters:

capacity - capacity of the list (as perceived by users).

maxCapacity - real capacity of the underlying list to mitigate the anomaly described in Javadoc of the class.

comparator - comparator for the quantities.

Method Detail

getItems

public List<T> getItems()

Get a items of this list.

Returns:

a list with the sorted items of the underlying list. The maximum number of items in the returned list is the "capacity" parameter passed into the constructor of this class.

add

public void add(T item,
                C quantity)

Add an item and its associated quantity to the list.

Parameters:

item - to add.

quantity - of the item.