DiskMemTileCache (Support and utility classes 1.5.0 API)

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

Fields
Modifier and Type	Field and Description
`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.

Constructor Summary

Constructors
Constructor and Description
`DiskMemTileCache()` Creates a new cache with all parameters set to their default values.
`DiskMemTileCache(Map<String,Object> params)` Creates a new cache.

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`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, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers

Methods inherited from class java.lang.Object
equals, 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
- 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

Class DiskMemTileCache

Implementation note

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.util.Observable

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_MEMORY_CAPACITY

DEFAULT_MEMORY_THRESHOLD

DEFAULT_AUTO_FLUSH_MEMORY_INTERVAL

DEFAULT_TILE_POLLING_INTERVAL

KEY_INITIAL_MEMORY_CAPACITY

KEY_ALWAYS_DISK_CACHE

KEY_AUTO_FLUSH_MEMORY_ENABLED

KEY_AUTO_FLUSH_MEMORY_INTERVAL

Constructor Detail

DiskMemTileCache

DiskMemTileCache

Method Detail

add

add

remove

getTile

getTiles

removeTiles

setTilePollingInterval

getTilePollingInterval

addTiles

getTiles

flush

flushMemory

memoryControl

setTileCapacity

getTileCapacity

setMemoryCapacity

getMemoryCapacity

getCurrentMemory

setMemoryThreshold

getMemoryThreshold

setTileComparator

getTileComparator

getNumTiles

getNumResidentTiles

containsTile

containsResidentTile

setTileChanged

setAutoFlushMemoryEnabled

isAutoFlushMemoryEnabled

setAutoFlushMemoryInterval

getAutoFlushMemoryInterval

setDiagnostics

accept