ca.odell.glazedlists.io
Class CachingList

java.lang.Object
  ca.odell.glazedlists.AbstractEventList<E>
      ca.odell.glazedlists.TransformedList
          ca.odell.glazedlists.io.CachingList

All Implemented Interfaces:

ListEventListener, EventList, Iterable, Collection, EventListener, List

public class CachingList
extends TransformedList

An EventList that caches elements from its source EventList. It is useful in cases when the get(int) method of an EventList is expensive. It can also be used when there are too many elements to keep in memory simultaneously. For caching to be effective, object access must be clustered.

This EventList caches the most recently requested n elements.

By overriding the preFetch(int) method, you can modify this CachingList to do predictive lookups for higher performance.

EventList Overview

Writable:	yes
Concurrency:	thread ready, not thread safe
Performance:	reads: O(log N), writes O(log N)
Memory:	O(N)
Unit Tests:	N/A
Issues:	22 32 43 262

Author:

Kevin Maltby

Field Summary

Fields inherited from class ca.odell.glazedlists.TransformedList

source

Fields inherited from class ca.odell.glazedlists.AbstractEventList

publisher, readWriteLock, updates

Constructor Summary

CachingList(EventList source, int maxSize)
Creates a CachingList that caches elements from the specified source EventList.

Method Summary

protected Object	fetch(int index, boolean recordHitsOrMisses) Fetches a particular element.
Object	get(int index) Returns the element at the specified position in this list.
float	getCacheHitRatio() Gets the ratio of cache hits to cache misses.
int	getCacheHits() Gets the total number of times that this list has fetched its result from the cache rather than from the source list.
int	getCacheMisses() Gets the total number of times that this list has fetched its result from the source list rather than the cache.
protected boolean	isWritable() Gets whether the source EventList is writable via this API.
void	listChanged(ListEvent listChanges) When the underlying list changes, this notification allows the object to repaint itself or update itself as necessary.
protected void	preFetch(int index) Pre-fetches a set of data given the index that was directly requested.
int	size() Returns the number of elements in this list.

Methods inherited from class ca.odell.glazedlists.TransformedList

add, addAll, clear, dispose, getSourceIndex, remove, removeAll, retainAll, set

Methods inherited from class ca.odell.glazedlists.AbstractEventList

add, addAll, addListEventListener, contains, containsAll, equals, getPublisher, getReadWriteLock, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, removeListEventListener, subList, toArray, toArray, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

CachingList

public CachingList(EventList source,
                   int maxSize)

Creates a CachingList that caches elements from the specified source EventList.

Parameters:

source - The source list to use to get values from

maxSize - The maximum size of the cache

Method Detail

size

public final int size()

Returns the number of elements in this list. If this list contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Specified by:

size in interface Collection

Specified by:

size in interface List

Overrides:

size in class TransformedList

Returns:

the number of elements in this list.

get

public final Object get(int index)

Returns the element at the specified position in this list.

Specified by:

get in interface List

Overrides:

get in class TransformedList

Parameters:

index - index of element to return.

Returns:

the element at the specified position in this list.

fetch

protected final Object fetch(int index,
                             boolean recordHitsOrMisses)

Fetches a particular element.

This might seem redundant with the existence of get(int). However, the goals of the methods are different. This method exists to be called by get(int) or preFetch(int). This distinction allows users overriding this class a means of entry retrieval which does not implicitly execute a pre-fetch. This is particularly key for users overriding preFetch(int)

Parameters:

index - The index of the value to retrieve

recordHitsOrMisses - Whether to increment the hit/miss counters (this should always be false when called from preFetch(int)).

Returns:

The value associated with the given index, or null if the index is not found.

preFetch

protected void preFetch(int index)

Pre-fetches a set of data given the index that was directly requested.

Each application that wishes to take advantage of pre-fetching should implement this method in a way which best fits their particular use cases. As such, no default pre-fetch behaviour could really be defined, and thus this method is empty by default.

Because pre-fetching can modify the cache, child classes of CachingList should use careful consideration of locking when implementing this method.

Parameters:

index - The index that was requested from the cache

isWritable

protected boolean isWritable()

Gets whether the source EventList is writable via this API.

Extending classes must override this method in order to make themselves writable.

Specified by:

isWritable in class TransformedList

getCacheHits

public final int getCacheHits()

Gets the total number of times that this list has fetched its result from the cache rather than from the source list.

Returns:

The number of times that this cache provided the result

getCacheMisses

public final int getCacheMisses()

Gets the total number of times that this list has fetched its result from the source list rather than the cache.

Returns:

The number of times that this cache couldn't provide the result

getCacheHitRatio

public final float getCacheHitRatio()

Gets the ratio of cache hits to cache misses. This is a number between 0 and 1, where 0 means the cache is unused and 1 means the cache was used exclusively.

listChanged

public final void listChanged(ListEvent listChanges)

When the underlying list changes, this notification allows the object to repaint itself or update itself as necessary.

It is mandatory that the calling thread has obtained the write lock on the source list. This is because the calling thread will have written to the source list to cause this event. This condition guarantees that no writes can occur while the listener is handling this event. It is an error to write to the source list while processing an event.

Specified by:

listChanged in interface ListEventListener

Specified by:

listChanged in class TransformedList

Parameters:

listChanges - a ListEvent describing the changes to the list