org.jaitools.tilecache
Class DiskMemTileCache

java.lang.Object
  java.util.Observable
      org.jaitools.tilecache.DiskMemTileCache

All Implemented Interfaces:

javax.media.jai.TileCache

public class DiskMemTileCache
extends Observable
implements javax.media.jai.TileCache

This class implements JAI TileCache. It can store cached tiles on disk to allow applications to work with very large volumes of tiled image data without being limited by available memory. A subset of tiles (by default, the most recently accessed) are cached in memory to reduce access time.

The default behaviour is to cache newly added tiles into memory. If the cache needs to free memory to accommodate a tile, it does so by removing lowest priority tiles from memory and caching them to disk. Optionally, the user can specify that newly added tiles are cached to disk immediately.

Unlike the standard JAI TileCache implementation, resident tiles are cached using strong references. This is to support the use of this class with DiskMemImage as well as operations that need to cache tiles that are expensive to create (e.g. output of a time-consuming analysis). A disadvantage of this design is that when the cache is being used for easily generated tiles it can end up unnecessarily holding memory that is more urgently required by other parts of an application. To avoid this happening, the cache can be set to auto-flush resident tiles at regular intervals.

Implementation note

Tile polling and auto-flushing of memory resident tiles (if enabled) both run on low-priority background threads. These are marked as daemon threads to avoid these services blocking application shutdown.

Since:

1.0

Version:

$Id$

Author:

Michael Bedward, Simone Giannecchini, GeoSolutions SAS

See Also:

DiskCachedTile, TileAccessTimeComparator

Field Summary

static long	DEFAULT_AUTO_FLUSH_MEMORY_INTERVAL The default minimum period (2.5 seconds) of cache inactivity that must elapse before memory-resident tiles are automatically flushed.
static long	DEFAULT_MEMORY_CAPACITY The default memory capacity in bytes (64 * 2^20 = 64Mb)
static float	DEFAULT_MEMORY_THRESHOLD The default memory threshold value (0.75)
static long	DEFAULT_TILE_POLLING_INTERVAL The default interval (2 seconds) for polling each tile to check if its owning image has been garbage collected.
static String	KEY_ALWAYS_DISK_CACHE Key for the parameter controlling whether newly added tiles are immediately cached to disk as well as in memory.
static String	KEY_AUTO_FLUSH_MEMORY_ENABLED Key for the parameter controlling whether the cache will auto-flush memory-resident tiles.
static String	KEY_AUTO_FLUSH_MEMORY_INTERVAL Key for the cache auto-flush interval parameter.
static String	KEY_INITIAL_MEMORY_CAPACITY Key for the parameter controlling initial memory capacity of the tile cache.
protected Map<Object,Raster>	residentTiles Memory-resident tiles.
protected List<DiskCachedTile>	sortedResidentTiles Tiles sorted according to the current tile priority comparator.
protected Map<Object,DiskCachedTile>	tiles Map of all cached tiles.

Constructor Summary

DiskMemTileCache()
Creates a new cache with all parameters set to their default values.

DiskMemTileCache(Map<String,Object> params)
Creates a new cache.

Method Summary

void	accept(DiskMemTileCacheVisitor visitor) Accepts a DiskMemCacheVisitor object and calls its visit method for each tile in the cache.
void	add(RenderedImage owner, int tileX, int tileY, Raster data) Adds a tile to the cache if not already present.
void	add(RenderedImage owner, int tileX, int tileY, Raster data, Object tileCacheMetric) Adds a tile to the cache if not already present.
void	addTiles(RenderedImage owner, Point[] tileIndices, Raster[] tiles, Object tileCacheMetric) Adds all tiles for the given image to the cache.
boolean	containsResidentTile(RenderedImage owner, int tileX, int tileY) Checks whether a given tile is in this cache's memory storage.
boolean	containsTile(RenderedImage owner, int tileX, int tileY) Checks whether a given tile is in this cache.
void	flush() Removes ALL tiles from the cache: all resident tiles will be removed from memory and all files for disk-cached tiles will be discarded.
void	flushMemory() Removes all resident tiles from memory.
long	getAutoFlushMemoryInterval() Gets the current auto-flush interval.
long	getCurrentMemory() Gets the amount of memory currently being used for storage of memory-resident tiles.
long	getMemoryCapacity() Gets the amount of memory, in bytes, allocated for storage of resident tiles.
float	getMemoryThreshold() Returns the memory threshold, which is the fractional amount of cache memory to retain during tile removal.
int	getNumResidentTiles() Gets the number of tiles currently residing in the cache's memory storage.
int	getNumTiles() Gets the total number of tiles currently in the cache.
Raster	getTile(RenderedImage owner, int tileX, int tileY) Gets the specified tile from the cache if present.
int	getTileCapacity() Deprecated. Please do not use this method
Comparator	getTileComparator() Gets the comparator currently used to assign memory-residence priority to tiles.
long	getTilePollingInterval() Sets the interval between polling each tile to check if its owning image has been garbage collected.
Raster[]	getTiles(RenderedImage owner) Gets all cached tiles associated with the given image.
Raster[]	getTiles(RenderedImage owner, Point[] tileIndices) Gets the specified tiles for the given image.
boolean	isAutoFlushMemoryEnabled() Checks whether auto-flushing of memory-resident tiles is currently enabled.
void	memoryControl() Frees memory for resident tiles so that the fraction of memory occupied is no more than the current value of the mamory threshold.
void	remove(RenderedImage owner, int tileX, int tileY) Removes a tile from the cache.
void	removeTiles(RenderedImage owner) Removes all tiles that belong to the given image from the cache.
void	setAutoFlushMemoryEnabled(boolean enable) Enables or disables auto-flushing of memory resident with the currently set minimum interval.
void	setAutoFlushMemoryInterval(long interval) Sets the minimum period of cache inactivity, in milliseconds, that must elapse before automatically flushing memory-resident tiles.
void	setDiagnostics(boolean state) Enables or disables the publishing of cache messages to Observers.
void	setMemoryCapacity(long newCapacity) Resets the memory capacity of the cache.
void	setMemoryThreshold(float newThreshold) Sets the memoryThreshold value to a floating point number that ranges from 0.0 to 1.0.
void	setTileCapacity(int arg0) Deprecated. Please do not use this method
void	setTileChanged(RenderedImage owner, int tileX, int tileY) Informs the cache that a tile's data have changed.
void	setTileComparator(Comparator comp) Sets the comparator to use to assign memory-residence priority to tiles.
void	setTilePollingInterval(long interval) Sets the interval between polling each tile to check if its owning image has been garbage collected.

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, toString, wait, wait, wait

Field Detail

DEFAULT_MEMORY_CAPACITY

public static final long DEFAULT_MEMORY_CAPACITY

The default memory capacity in bytes (64 * 2^20 = 64Mb)

See Also:

setMemoryCapacity(long), Constant Field Values

DEFAULT_MEMORY_THRESHOLD

public static final float DEFAULT_MEMORY_THRESHOLD

The default memory threshold value (0.75)

See Also:

setMemoryThreshold(float), Constant Field Values

DEFAULT_AUTO_FLUSH_MEMORY_INTERVAL

public static final long DEFAULT_AUTO_FLUSH_MEMORY_INTERVAL

The default minimum period (2.5 seconds) of cache inactivity that must elapse before memory-resident tiles are automatically flushed.

See Also:

setAutoFlushMemoryInterval(long), Constant Field Values

DEFAULT_TILE_POLLING_INTERVAL

public static final long DEFAULT_TILE_POLLING_INTERVAL

The default interval (2 seconds) for polling each tile to check if its owning image has been garbage collected.

See Also:

setTilePollingInterval(long), Constant Field Values

KEY_INITIAL_MEMORY_CAPACITY

public static final String KEY_INITIAL_MEMORY_CAPACITY

Key for the parameter controlling initial memory capacity of the tile cache. This determines the maximum number of tiles that can be resident concurrently. The value must be numeric and will be treated as Long.

See Also:

setMemoryCapacity(long), DEFAULT_MEMORY_CAPACITY, Constant Field Values

KEY_ALWAYS_DISK_CACHE

public static final String KEY_ALWAYS_DISK_CACHE

Key for the parameter controlling whether newly added tiles are immediately cached to disk as well as in memory. The value must be one Boolean. If the value is Boolean.FALSE (the default), disk caching of tiles is deferred until required (ie. when memory needs to be freed for other tiles).

See Also:

Constant Field Values

KEY_AUTO_FLUSH_MEMORY_ENABLED

public static final String KEY_AUTO_FLUSH_MEMORY_ENABLED

Key for the parameter controlling whether the cache will auto-flush memory-resident tiles. The value must be Boolean. If the value is Boolean.TRUE, auto-flushing of resident tiles will be enabled when the cache is created. The default is Boolean.FALSE.

See Also:

setAutoFlushMemoryEnabled(boolean), Constant Field Values

KEY_AUTO_FLUSH_MEMORY_INTERVAL

public static final String KEY_AUTO_FLUSH_MEMORY_INTERVAL

Key for the cache auto-flush interval parameter. The value must be numeric and represents the interval, in milliseconds, between auto-flushes of resident tiles. Values less than or equal to zero are ignored.

See Also:

setAutoFlushMemoryInterval(long), DEFAULT_AUTO_FLUSH_MEMORY_INTERVAL, Constant Field Values

tiles

protected Map<Object,DiskCachedTile> tiles

Map of all cached tiles.

residentTiles

protected Map<Object,Raster> residentTiles

Memory-resident tiles.

sortedResidentTiles

protected List<DiskCachedTile> sortedResidentTiles

Tiles sorted according to the current tile priority comparator.

Constructor Detail

DiskMemTileCache

public DiskMemTileCache()

Creates a new cache with all parameters set to their default values.

DiskMemTileCache

public DiskMemTileCache(Map<String,Object> params)

Creates a new cache.

Parameters:

params - an optional map of parameters (may be empty or null)

Method Detail

add

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

Adds a tile to the cache if not already present.

Specified by:

add in interface javax.media.jai.TileCache

Parameters:

owner - the image that this tile belongs to

tileX - the tile column

tileY - the tile row

data - the tile data

add

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

Adds a tile to the cache if not already present.

Specified by:

add in interface javax.media.jai.TileCache

Parameters:

owner - the image that this tile belongs to

tileX - the tile column

tileY - the tile row

data - the tile data

tileCacheMetric - optional tile cache metric (may be null

remove

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

Removes a tile from the cache.

Specified by:

remove in interface javax.media.jai.TileCache

Parameters:

owner - the image that this tile belongs to

tileX - the tile column

tileY - the tile row

getTile

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

Gets the specified tile from the cache if present. If the tile is cached but not resident in memory it will be read from the cache's disk storage and made resident.

Specified by:

getTile in interface javax.media.jai.TileCache

Parameters:

owner - the image that the tile belongs to

tileX - the tile column

tileY - the tile row

Returns:

the requested tile or null if the tile was not cached

getTiles

public Raster[] getTiles(RenderedImage owner)

Gets all cached tiles associated with the given image. The tiles will be loaded into memory as space allows.

Specified by:

getTiles in interface javax.media.jai.TileCache

Parameters:

owner - the image for which tiles are requested

Returns:

an array of tile Rasters

removeTiles

public void removeTiles(RenderedImage owner)

Removes all tiles that belong to the given image from the cache.

Specified by:

removeTiles in interface javax.media.jai.TileCache

Parameters:

owner - the image owning the tiles to be removed

setTilePollingInterval

public void setTilePollingInterval(long interval)

Sets the interval between polling each tile to check if its owning image has been garbage collected. Any such tiles are removed from the cache.

Parameters:

interval - interval in milliseconds (values less than or equal to zero are ignored)

getTilePollingInterval

public long getTilePollingInterval()

Sets the interval between polling each tile to check if its owning image has been garbage collected. Any such tiles are removed from the cache. *

Returns:

interval in milliseconds

addTiles

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

Adds all tiles for the given image to the cache.

Specified by:

addTiles in interface javax.media.jai.TileCache

Parameters:

owner - the image that the tiles belong to

tileIndices - an array of Points specifying the column-row coordinates of each tile

tiles - tile data in the form of Raster objects

tileCacheMetric - optional metric (may be null)

getTiles

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

Gets the specified tiles for the given image.

Specified by:

getTiles in interface javax.media.jai.TileCache

Parameters:

owner - the image that the tiles belong to

tileIndices - an array of Points specifying the column-row coordinates of each tile

Returns:

data for the requested tiles as Raster objects

flush

public void flush()

Removes ALL tiles from the cache: all resident tiles will be removed from memory and all files for disk-cached tiles will be discarded.

The update action of each tile will be set to DiskCachedTile#ACTION_REMOVED.

Specified by:

flush in interface javax.media.jai.TileCache

flushMemory

public void flushMemory()

Removes all resident tiles from memory. No rewriting of tile data to disk is done.

memoryControl

public void memoryControl()

Frees memory for resident tiles so that the fraction of memory occupied is no more than the current value of the mamory threshold.

Specified by:

memoryControl in interface javax.media.jai.TileCache

See Also:

setMemoryThreshold(float)

setTileCapacity

@Deprecated
public void setTileCapacity(int arg0)

Deprecated. Please do not use this method

Does nothing.

Specified by:

setTileCapacity in interface javax.media.jai.TileCache

getTileCapacity

public int getTileCapacity()

Deprecated. Please do not use this method

Always returns 0.

Specified by:

getTileCapacity in interface javax.media.jai.TileCache

setMemoryCapacity

public void setMemoryCapacity(long newCapacity)

Resets the memory capacity of the cache. Setting capacity to 0 will flush all resident tiles from memory. Setting a capacity less than the current capacity could cause some memory-resident tiles being removed from memory.

Specified by:

setMemoryCapacity in interface javax.media.jai.TileCache

Parameters:

newCapacity - requested memory capacity for resident tiles

getMemoryCapacity

public long getMemoryCapacity()

Gets the amount of memory, in bytes, allocated for storage of resident tiles.

Specified by:

getMemoryCapacity in interface javax.media.jai.TileCache

Returns:

resident tile memory capacity in bytes

getCurrentMemory

public long getCurrentMemory()

Gets the amount of memory currently being used for storage of memory-resident tiles.

Returns:

current memory use in bytes

setMemoryThreshold

public void setMemoryThreshold(float newThreshold)

Sets the memoryThreshold value to a floating point number that ranges from 0.0 to 1.0. When the cache memory is full, the memory usage will be reduced to this fraction of the total cache memory capacity. For example, a value of .75 will cause 25% of the memory to be cleared, while retaining 75%.

Specified by:

setMemoryThreshold in interface javax.media.jai.TileCache

Parameters:

newThreshold - the new memory threshold between 0 and 1

Throws:

IllegalArgumentException - if the memoryThreshold is less than 0.0 or greater than 1.0

getMemoryThreshold

public float getMemoryThreshold()

Returns the memory threshold, which is the fractional amount of cache memory to retain during tile removal. This only applies if memory thresholding has been enabled by passing the parameter #KEY_USE_MEMORY_THRESHOLD to the constructor with a value of Boolean.TRUE.

Specified by:

getMemoryThreshold in interface javax.media.jai.TileCache

Returns:

the retained fraction of memory

setTileComparator

public void setTileComparator(Comparator comp)

Sets the comparator to use to assign memory-residence priority to tiles. If comp is null the default comparator (TileAccessTimeComparator) will be used.

Specified by:

setTileComparator in interface javax.media.jai.TileCache

Parameters:

comp - the comparator or null for the default

getTileComparator

public Comparator getTileComparator()

Gets the comparator currently used to assign memory-residence priority to tiles.

Specified by:

getTileComparator in interface javax.media.jai.TileCache

Returns:

the current comparator

getNumTiles

public int getNumTiles()

Gets the total number of tiles currently in the cache.

Returns:

number of cached tiles

getNumResidentTiles

public int getNumResidentTiles()

Gets the number of tiles currently residing in the cache's memory storage.

Returns:

number of memory-resident tiles

containsTile

public boolean containsTile(RenderedImage owner,
                            int tileX,
                            int tileY)

Checks whether a given tile is in this cache.

Parameters:

owner - the owning image

tileX - tile column

tileY - tile row

Returns:

true if the cache contains the tile; false otherwise

containsResidentTile

public boolean containsResidentTile(RenderedImage owner,
                                    int tileX,
                                    int tileY)

Checks whether a given tile is in this cache's memory storage.

Parameters:

owner - the owning image

tileX - tile column

tileY - tile row

Returns:

true if the tile is in cache memory; false otherwise

setTileChanged

public void setTileChanged(RenderedImage owner,
                           int tileX,
                           int tileY)
                    throws TileNotResidentException,
                           DiskCacheFailedException

Informs the cache that a tile's data have changed. The tile should be resident in memory as the result of a previous getTile request. If this is the case and the tile was previously written to disk, then the cache's disk copy of the tile will be refreshed.

If the tile is not resident in memory, for instance because of memory swapping for other tile accesses, the disk copy will not be refreshed and a TileNotResidentException is thrown.

Parameters:

owner - the owning image

tileX - tile column

tileY - tile row

Throws:

TileNotResidentException - if the tile is not resident

DiskCacheFailedException - if the tile is cached to disk but its data could not be updated

setAutoFlushMemoryEnabled

public final void setAutoFlushMemoryEnabled(boolean enable)

Enables or disables auto-flushing of memory resident with the currently set minimum interval.

Parameters:

enable - true to enable auto-flushing; false to disable

See Also:

setAutoFlushMemoryInterval(long)

isAutoFlushMemoryEnabled

public boolean isAutoFlushMemoryEnabled()

Checks whether auto-flushing of memory-resident tiles is currently enabled.

Returns:

true if the cache is auto-flushing; false otherwise

setAutoFlushMemoryInterval

public void setAutoFlushMemoryInterval(long interval)

Sets the minimum period of cache inactivity, in milliseconds, that must elapse before automatically flushing memory-resident tiles.

Parameters:

interval - interval in milliseconds (values less than or equal to zero are ignored)

getAutoFlushMemoryInterval

public long getAutoFlushMemoryInterval()

Gets the current auto-flush interval. This is the minimum period of cache inactivity, in milliseconds, that must elapse before automatically flushing tiles.

Returns:

interval in milliseconds

setDiagnostics

public void setDiagnostics(boolean state)

Enables or disables the publishing of cache messages to Observers.

Parameters:

state - true to publish diagnostic messages; false to suppress them

accept

public void accept(DiskMemTileCacheVisitor visitor)

Accepts a DiskMemCacheVisitor object and calls its visit method for each tile in the cache.

Parameters:

visitor - the visitor