org.jaitools.tilecache
Class DiskMemTileCache

java.lang.Object
  extended by java.util.Observable
      extended by 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


Copyright © 2009-2013. All Rights Reserved.