org.esa.snap.core.image

Class FileTileCache

java.lang.Object

org.esa.snap.core.image.FileTileCache

All Implemented Interfaces:

javax.media.jai.TileCache

public class FileTileCache
extends Object
implements javax.media.jai.TileCache

A class implementing a caching mechanism for image tiles.

TileCache provides a mechanism by which an OpImage may cache its computed tiles. There may be multiple TileCaches used in an application up to the point of having a different TileCache for each OpImage.

The TileCache used for a particular OpImage is derived from the RenderingHints assigned to the associated imaging chain node. If the node is constructed using JAI.create() and no TileCache is specified in the RenderingHints parameter, then one is derived from the RenderingHints associated with the instance of the JAI class being used.

In the Sun reference implementation, the cache size is limited by the memory capacity, which is set to a default value at construction or subsequently using the setMemoryCapacity() method. The initial value may be obtained using getMemoryCapacity(). The tile capacity is not used as different images may have very different tile sizes so that this metric is not a particularly meaningful control of memory resource consumption in general.

See Also:

JAI, RenderedOp, RenderingHints

Constructor Summary

Constructors

Constructor and Description
FileTileCache(File cacheDir)

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 compute cost
void	addTiles(RenderedImage owner, Point[] tileIndices, Raster[] tiles, Object tileCacheMetric) Adds an array of tiles to the tile cache.
void	flush() Advises the cache that all of its tiles may be discarded.
long	getMemoryCapacity() Returns the memory capacity in bytes.
float	getMemoryThreshold() Returns the memory threshold, which is the fractional amount of cache memory to retain during tile removal.
Raster	getTile(RenderedImage owner, int tileX, int tileY) Retrieves a tile.
int	getTileCapacity() Deprecated. as of JAI 1.1.
Comparator	getTileComparator() Returns the Comparator currently set for use in ordering the CachedTiles stored by the TileCache.
Raster[]	getTiles(RenderedImage owner) Retrieves an 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() Advises the cache that some of its tiles may be discarded.
void	remove(RenderedImage owner, int tileX, int tileY) Advises the cache that a tile is no longer needed.
void	removeTiles(RenderedImage owner) Advises the cache that all tiles associated with a given image are no longer needed.
void	setMemoryCapacity(long memoryCapacity) Sets the memory capacity to a desired number of bytes.
void	setMemoryThreshold(float memoryThreshold) Sets the memoryThreshold value to a floating point number that ranges from 0.0 to 1.0.
void	setTileCapacity(int tileCapacity) Deprecated. as of JAI 1.1.
void	setTileComparator(Comparator comparator) Sets a Comparator which imposes an order on the CachedTiles stored in the TileCache.

Methods inherited from class java.lang.Object

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

Constructor Detail

FileTileCache

public FileTileCache(File cacheDir)

Method Detail

add

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

Adds a tile to the cache.

Specified by:

add in interface javax.media.jai.TileCache

Parameters:

owner - The RenderedImage that the tile belongs to.

tileX - The X index of the tile in the owner's tile grid.

tileY - The Y index of the tile in the owner's tile grid.

tile - A Raster containing the tile data.

add

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

Adds a tile to the cache with an associated compute cost

Specified by:

add in interface javax.media.jai.TileCache

Parameters:

owner - The RenderedImage that the tile belongs to.

tileX - The X index of the tile in the owner's tile grid.

tileY - The Y index of the tile in the owner's tile grid.

tile - A Raster containing the tile data.

tileCacheMetric - An Object as a tile metric.

Since:

JAI 1.1

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:

JAI 1.1

getTile

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

Retrieves a tile. Returns null if the tile is not present in the cache.

Specified by:

getTile in interface javax.media.jai.TileCache

Parameters:

owner - The RenderedImage that the tile belongs to.

tileX - The X index of the tile in the owner's tile grid.

tileY - The Y index of the tile in the owner's tile grid.

getTiles

public Raster[] getTiles(RenderedImage owner)

Retrieves an array of all tiles in the cache which are owned by the specified image.

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.

Since:

JAI 1.1

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. The length of the returned array must be the same as that of the parameter array and the ith Raster in the returned array must correspond to the ith tile index in the parameter array.

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:

JAI 1.1

removeTiles

public void removeTiles(RenderedImage owner)

Advises the cache that all tiles associated with a given image are no longer needed. It is legal to implement this method as a no-op.

Specified by:

removeTiles in interface javax.media.jai.TileCache

Parameters:

owner - The RenderedImage owner of the tiles to be removed.

remove

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

Advises the cache that a tile is no longer needed. It is legal to implement this method as a no-op.

Specified by:

remove in interface javax.media.jai.TileCache

Parameters:

owner - The RenderedImage that the tile belongs to.

tileX - The X index of the tile in the owner's tile grid.

tileY - The Y index of the tile in the owner's tile grid.

flush

public void flush()

Advises the cache that all of its tiles may be discarded. It is legal to implement this method as a no-op.

Specified by:

flush in interface javax.media.jai.TileCache

memoryControl

public void memoryControl()

Advises the cache that some of its tiles may be discarded. It is legal to implement this method as a no-op.

Specified by:

memoryControl in interface javax.media.jai.TileCache

Since:

JAI 1.1

setTileCapacity

public void setTileCapacity(int tileCapacity)

Deprecated. as of JAI 1.1.

Sets the tile capacity to a desired number of tiles. If the capacity is smaller than the current capacity, tiles are flushed from the cache. It is legal to implement this method as a no-op.

Specified by:

setTileCapacity in interface javax.media.jai.TileCache

Parameters:

tileCapacity - The new capacity, in tiles.

getTileCapacity

public int getTileCapacity()

Deprecated. as of JAI 1.1.

Returns the tile capacity in tiles. It is legal to implement this method as a no-op which should be signaled by returning zero.

Specified by:

getTileCapacity in interface javax.media.jai.TileCache

setMemoryCapacity

public void setMemoryCapacity(long memoryCapacity)

Sets the memory capacity to a desired number of bytes. If the memory capacity is smaller than the amount of memory currently used by the cache, tiles are flushed until the TileCache's memory usage is less than memoryCapacity.

Specified by:

setMemoryCapacity in interface javax.media.jai.TileCache

Parameters:

memoryCapacity - The new capacity, in bytes.

getMemoryCapacity

public long getMemoryCapacity()

Returns the memory capacity in bytes.

Specified by:

getMemoryCapacity in interface javax.media.jai.TileCache

setMemoryThreshold

public void setMemoryThreshold(float memoryThreshold)

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:

memoryThreshold - Retained fraction of memory

Throws:

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

Since:

JAI 1.1

getMemoryThreshold

public float getMemoryThreshold()

Returns the memory threshold, which is the fractional amount of cache memory to retain during tile removal.

Specified by:

getMemoryThreshold in interface javax.media.jai.TileCache

Since:

JAI 1.1

setTileComparator

public void setTileComparator(Comparator comparator)

Sets a Comparator which imposes an order on the CachedTiles stored in the TileCache. This ordering is used in memoryControl() to determine the sequence in which tiles will be removed from the TileCache so as to reduce the memory to the level given by the memory threshold. The Objects passed to the compare() method of the Comparator will be instances of CachedTile. CachedTiles will be removed from the TileCache in the ascending order imposed by this Comparator. If no Comparator is currently set, the TileCache should use an implementation-dependent default ordering. In the Sun Microsystems, Inc., implementation of TileCache, this ordering is the least recently used ordering, i.e., the tiles least recently used will be removed first by memoryControl().

Specified by:

setTileComparator in interface javax.media.jai.TileCache

Parameters:

comparator - A Comparator which orders the CachedTiles stored by the TileCache; if null an implementation-dependent algorithm will be used.

Since:

JAI 1.1

getTileComparator

public Comparator getTileComparator()

Returns the Comparator currently set for use in ordering the CachedTiles stored by the TileCache.

Specified by:

getTileComparator in interface javax.media.jai.TileCache

Returns:

The tile Comparator or null if the implementation-dependent ordering algorithm is being used.

Since:

JAI 1.1