com.bc.ceres.jai.tilecache

Class SwappingTileCache

java.lang.Object

java.util.Observable

com.bc.ceres.jai.tilecache.SwappingTileCache

All Implemented Interfaces:

com.sun.media.jai.util.CacheDiagnostics, javax.media.jai.TileCache

public final class SwappingTileCache
extends Observable
implements javax.media.jai.TileCache, com.sun.media.jai.util.CacheDiagnostics

A tile cache based on Sun Microsystems' reference implementation of the javax.media.jai.TileCache interface. In opposite to the Sun implementation, we'll never throw away any tiles but instead swap them to a SwapSpace.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_HASHTABLE_CAPACITY The default hashtable capacity (heuristic)
static long	DEFAULT_MEMORY_CAPACITY The default memory capacity of the cache (16 MB).
static File	DEFAULT_SWAP_DIR The default directory where tiles are stored if they don't fit into memory anymore.

Constructor Summary

Constructors

Constructor and Description
SwappingTileCache() No args constructor.
SwappingTileCache(long memoryCapacity, SwapSpace swapSpace) Constructor.

Method Summary

Modifier and Type	Method and Description
void	add(RenderedImage owner, int tileX, int tileY, Raster tile) Adds a tile to the cache.
void	add(RenderedImage owner, int tileX, int tileY, Raster tile, Object tileCacheMetric) Adds a tile to the cache with an associated tile compute cost.
void	addTiles(RenderedImage owner, Point[] tileIndices, Raster[] tiles, Object tileCacheMetric) Adds an array of tiles to the tile cache.
void	disableDiagnostics() Turn off diagnostic notification
void	dump()
void	enableDiagnostics() Enable Tile Monitoring and Diagnostics
void	flush() Removes -ALL- tiles from the cache.
Object	getCachedObject()
static javax.media.jai.EnumeratedParameter[]	getCachedTileActions()
long	getCacheHitCount()
long	getCacheMemoryUsed()
long	getCacheMissCount()
long	getCacheTileCount()
long	getMemoryCapacity() Returns the cache's memory capacity in bytes.
float	getMemoryThreshold() Returns the current memoryThreshold.
Raster	getTile(RenderedImage owner, int tileX, int tileY) Retrieves a tile from the cache.
int	getTileCapacity() Returns the cache's tile capacity.
Comparator	getTileComparator() Return the current comparator
Raster[]	getTiles(RenderedImage owner) Retrieves a contiguous array of all tiles in the cache which are owned by the specified image.
Raster[]	getTiles(RenderedImage owner, Point[] tileIndices) Returns an array of tile Rasters from the cache.
void	memoryControl() Removes tiles from the cache based on their last-access time (old to new) until the memory usage is memoryThreshold % of that of the memory capacity.
void	remove(RenderedImage owner, int tileX, int tileY) Removes a tile from the cache.
void	removeTiles(RenderedImage owner) Removes all the tiles that belong to a RenderedImage from the cache.
void	resetCounts() Reset hit and miss counters.
void	setMemoryCapacity(long memoryCapacity) Sets the cache's memory capacity to the desired number of bytes.
void	setMemoryThreshold(float mt) Set the memory threshold value.
void	setTileCapacity(int tileCapacity) Sets the cache's tile capacity to the desired number of tiles.
void	setTileComparator(Comparator c) The Comparator is used to produce an ordered list of tiles based on a user defined compute cost or priority metric.
String	toString() Returns a string representation of the class object.

Methods inherited from class java.util.Observable

addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_MEMORY_CAPACITY

public static final long DEFAULT_MEMORY_CAPACITY

The default memory capacity of the cache (16 MB).

See Also:

Constant Field Values

DEFAULT_HASHTABLE_CAPACITY

public static final int DEFAULT_HASHTABLE_CAPACITY

The default hashtable capacity (heuristic)

See Also:

Constant Field Values

DEFAULT_SWAP_DIR

public static final File DEFAULT_SWAP_DIR

The default directory where tiles are stored if they don't fit into memory anymore.

Constructor Detail

SwappingTileCache

public SwappingTileCache()

No args constructor. Use the DEFAULT_MEMORY_CAPACITY of 16 Megs.

SwappingTileCache

public SwappingTileCache(long memoryCapacity,
                         SwapSpace swapSpace)

Constructor. The memory capacity should be explicitly specified.

Parameters:

memoryCapacity - The maximum cache memory size in bytes.

swapSpace - The space used to swap out tiles.

Throws:

IllegalArgumentException - If memoryCapacity is less than 0.

Method Detail

getCachedTileActions

public static javax.media.jai.EnumeratedParameter[] getCachedTileActions()

Returns:

An array of EnumeratedParameters corresponding to the numeric values returned by the getAction() method of the CachedTile implementation used by SunTileCache. The "name" of each EnumeratedParameter provides a brief string describing the numeric action value.

add

public void add(RenderedImage owner,
                int tileX,
                int tileY,
                Raster tile)

Adds a tile to the cache.

If the specified tile is already in the cache, it will not be cached again. If by adding this tile, the cache exceeds the memory capacity, older tiles in the cache are removed to keep the cache memory usage under the specified limit.

Specified by:

add in interface javax.media.jai.TileCache

Parameters:

owner - The image the tile blongs to.

tileX - The tile's X index within the image.

tileY - The tile's Y index within the image.

tile - The tile to be cached.

add

public void add(RenderedImage owner,
                int tileX,
                int tileY,
                Raster tile,
                Object tileCacheMetric)

Adds a tile to the cache with an associated tile compute cost.

If the specified tile is already in the cache, it will not be cached again. If by adding this tile, the cache exceeds the memory capacity, older tiles in the cache are removed to keep the cache memory usage under the specified limit.

Specified by:

add in interface javax.media.jai.TileCache

Parameters:

owner - The image the tile blongs to.

tileX - The tile's X index within the image.

tileY - The tile's Y index within the image.

tile - The tile to be cached.

tileCacheMetric - Metric for prioritizing tiles

addTiles

public void addTiles(RenderedImage owner,
                     Point[] tileIndices,
                     Raster[] tiles,
                     Object tileCacheMetric)

Adds an array of tiles to the tile cache.

Specified by:

addTiles in interface javax.media.jai.TileCache

Parameters:

owner - The RenderedImage that the tile belongs to.

tileIndices - An array of Points containing the tileX and tileY indices for each tile.

tiles - The array of tile Rasters containing tile data.

tileCacheMetric - Object which provides an ordering metric associated with the RenderedImage owner.

Since:

1.1

remove

public void remove(RenderedImage owner,
                   int tileX,
                   int tileY)

Removes a tile from the cache.

If the specified tile is not in the cache, this method does nothing.

Specified by:

remove in interface javax.media.jai.TileCache

removeTiles

public void removeTiles(RenderedImage owner)

Removes all the tiles that belong to a RenderedImage from the cache.

Specified by:

removeTiles in interface javax.media.jai.TileCache

Parameters:

owner - The image whose tiles are to be removed from the cache.

getTile

public Raster getTile(RenderedImage owner,
                      int tileX,
                      int tileY)

Retrieves a tile from the cache.

If the specified tile is not in the cache, this method returns null. If the specified tile is in the cache, its last-access time is updated.

Specified by:

getTile in interface javax.media.jai.TileCache

Parameters:

owner - The image the tile blongs to.

tileX - The tile's X index within the image.

tileY - The tile's Y index within the image.

getTiles

public Raster[] getTiles(RenderedImage owner)

Retrieves a contiguous array of all tiles in the cache which are owned by the specified image. May be null if there were no tiles in the cache. The array contains no null entries.

Specified by:

getTiles in interface javax.media.jai.TileCache

Parameters:

owner - The RenderedImage to which the tiles belong.

Returns:

An array of all tiles owned by the specified image or null if there are none currently in the cache.

getTiles

public Raster[] getTiles(RenderedImage owner,
                         Point[] tileIndices)

Returns an array of tile Rasters from the cache. Any or all of the elements of the returned array may be null if the corresponding tile is not in the cache.

Specified by:

getTiles in interface javax.media.jai.TileCache

Parameters:

owner - The RenderedImage that the tile belongs to.

tileIndices - An array of Points containing the tileX and tileY indices for each tile.

Since:

1.1

flush

public void flush()

Removes -ALL- tiles from the cache.

Specified by:

flush in interface javax.media.jai.TileCache

getTileCapacity

public int getTileCapacity()

Returns the cache's tile capacity.

This implementation of TileCache does not use the tile capacity. This method always returns 0.

Specified by:

getTileCapacity in interface javax.media.jai.TileCache

setTileCapacity

public void setTileCapacity(int tileCapacity)

Sets the cache's tile capacity to the desired number of tiles.

This implementation of TileCache does not use the tile capacity. The cache size is limited by the memory capacity only. This method does nothing and has no effect on the cache.

Specified by:

setTileCapacity in interface javax.media.jai.TileCache

Parameters:

tileCapacity - The desired tile capacity for this cache in number of tiles.

getMemoryCapacity

public long getMemoryCapacity()

Returns the cache's memory capacity in bytes.

Specified by:

getMemoryCapacity in interface javax.media.jai.TileCache

setMemoryCapacity

public void setMemoryCapacity(long memoryCapacity)

Sets the cache's memory capacity to the desired number of bytes. If the new memory capacity is smaller than the amount of memory currently being used by this cache, tiles are removed from the cache until the memory usage is less than the specified memory capacity.

Specified by:

setMemoryCapacity in interface javax.media.jai.TileCache

Parameters:

memoryCapacity - The desired memory capacity for this cache in bytes.

Throws:

IllegalArgumentException - If memoryCapacity is less than 0.

enableDiagnostics

public void enableDiagnostics()

Enable Tile Monitoring and Diagnostics

Specified by:

enableDiagnostics in interface com.sun.media.jai.util.CacheDiagnostics

disableDiagnostics

public void disableDiagnostics()

Turn off diagnostic notification

Specified by:

disableDiagnostics in interface com.sun.media.jai.util.CacheDiagnostics

getCacheTileCount

public long getCacheTileCount()

Specified by:

getCacheTileCount in interface com.sun.media.jai.util.CacheDiagnostics

getCacheMemoryUsed

public long getCacheMemoryUsed()

Specified by:

getCacheMemoryUsed in interface com.sun.media.jai.util.CacheDiagnostics

getCacheHitCount

public long getCacheHitCount()

Specified by:

getCacheHitCount in interface com.sun.media.jai.util.CacheDiagnostics

getCacheMissCount

public long getCacheMissCount()

Specified by:

getCacheMissCount in interface com.sun.media.jai.util.CacheDiagnostics

resetCounts

public void resetCounts()

Reset hit and miss counters.

Specified by:

resetCounts in interface com.sun.media.jai.util.CacheDiagnostics

Since:

1.1

setMemoryThreshold

public void setMemoryThreshold(float mt)

Set the memory threshold value.

Specified by:

setMemoryThreshold in interface javax.media.jai.TileCache

Since:

1.1

getMemoryThreshold

public float getMemoryThreshold()

Returns the current memoryThreshold.

Specified by:

getMemoryThreshold in interface javax.media.jai.TileCache

Since:

1.1

toString

public String toString()

Returns a string representation of the class object.

Overrides:

toString in class Object

getCachedObject

public Object getCachedObject()

Returns:

the Object that represents the actual cache.

memoryControl

public void memoryControl()

Removes tiles from the cache based on their last-access time (old to new) until the memory usage is memoryThreshold % of that of the memory capacity.

Specified by:

memoryControl in interface javax.media.jai.TileCache

setTileComparator

public void setTileComparator(Comparator c)

The Comparator is used to produce an ordered list of tiles based on a user defined compute cost or priority metric. This determines which tiles are subject to "ordered" removal during a memory control operation.

Specified by:

setTileComparator in interface javax.media.jai.TileCache

Since:

1.1

getTileComparator

public Comparator getTileComparator()

Return the current comparator

Specified by:

getTileComparator in interface javax.media.jai.TileCache

Since:

1.1

dump

public void dump()