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 anOpImage
may cache its computed tiles. There may be multipleTileCache
s used in an application up to the point of having a differentTileCache
for eachOpImage
.The
TileCache
used for a particularOpImage
is derived from theRenderingHints
assigned to the associated imaging chain node. If the node is constructed usingJAI.create()
and noTileCache
is specified in theRenderingHints
parameter, then one is derived from theRenderingHints
associated with the instance of theJAI
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 usinggetMemoryCapacity()
. 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 Description FileTileCache(File cacheDir)
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method 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 costvoid
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 theComparator
currently set for use in ordering theCachedTile
s stored by theTileCache
.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 tileRaster
s 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 thememoryThreshold
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 aComparator
which imposes an order on theCachedTile
s stored in theTileCache
.
-
-
-
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 interfacejavax.media.jai.TileCache
- Parameters:
owner
- TheRenderedImage
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
- ARaster
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 interfacejavax.media.jai.TileCache
- Parameters:
owner
- TheRenderedImage
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
- ARaster
containing the tile data.tileCacheMetric
- AnObject
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 interfacejavax.media.jai.TileCache
- Parameters:
owner
- TheRenderedImage
that the tile belongs to.tileIndices
- An array ofPoint
s containing thetileX
andtileY
indices for each tile.tiles
- The array of tileRaster
s containing tile data.tileCacheMetric
- Object which provides an ordering metric associated with theRenderedImage
owner.- Since:
- JAI 1.1
-
getTile
public Raster getTile(RenderedImage owner, int tileX, int tileY)
Retrieves a tile. Returnsnull
if the tile is not present in the cache.- Specified by:
getTile
in interfacejavax.media.jai.TileCache
- Parameters:
owner
- TheRenderedImage
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 interfacejavax.media.jai.TileCache
- Parameters:
owner
- TheRenderedImage
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 tileRaster
s from the cache. Any or all of the elements of the returned array may benull
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 ithRaster
in the returned array must correspond to the ith tile index in the parameter array.- Specified by:
getTiles
in interfacejavax.media.jai.TileCache
- Parameters:
owner
- TheRenderedImage
that the tile belongs to.tileIndices
- An array ofPoint
s containing thetileX
andtileY
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 interfacejavax.media.jai.TileCache
- Parameters:
owner
- TheRenderedImage
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 interfacejavax.media.jai.TileCache
- Parameters:
owner
- TheRenderedImage
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 interfacejavax.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 interfacejavax.media.jai.TileCache
- Since:
- JAI 1.1
-
getTileCapacity
@Deprecated 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 interfacejavax.media.jai.TileCache
-
setTileCapacity
@Deprecated 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 interfacejavax.media.jai.TileCache
- Parameters:
tileCapacity
- The new capacity, in tiles.
-
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 theTileCache
's memory usage is less thanmemoryCapacity
.- Specified by:
setMemoryCapacity
in interfacejavax.media.jai.TileCache
- Parameters:
memoryCapacity
- The new capacity, in bytes.
-
getMemoryCapacity
public long getMemoryCapacity()
Returns the memory capacity in bytes.- Specified by:
getMemoryCapacity
in interfacejavax.media.jai.TileCache
-
setMemoryThreshold
public void setMemoryThreshold(float memoryThreshold)
Sets thememoryThreshold
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 interfacejavax.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 interfacejavax.media.jai.TileCache
- Since:
- JAI 1.1
-
getTileComparator
public Comparator getTileComparator()
Returns theComparator
currently set for use in ordering theCachedTile
s stored by theTileCache
.- Specified by:
getTileComparator
in interfacejavax.media.jai.TileCache
- Returns:
- The tile
Comparator
ornull
if the implementation-dependent ordering algorithm is being used. - Since:
- JAI 1.1
-
setTileComparator
public void setTileComparator(Comparator comparator)
Sets aComparator
which imposes an order on theCachedTile
s stored in theTileCache
. This ordering is used inmemoryControl()
to determine the sequence in which tiles will be removed from theTileCache
so as to reduce the memory to the level given by the memory threshold. TheObject
s passed to thecompare()
method of theComparator
will be instances ofCachedTile
.CachedTile
s will be removed from theTileCache
in the ascending order imposed by thisComparator
. If noComparator
is currently set, theTileCache
should use an implementation-dependent default ordering. In the Sun Microsystems, Inc., implementation ofTileCache
, this ordering is the least recently used ordering, i.e., the tiles least recently used will be removed first bymemoryControl()
.- Specified by:
setTileComparator
in interfacejavax.media.jai.TileCache
- Parameters:
comparator
- AComparator
which orders theCachedTile
s stored by theTileCache
; ifnull
an implementation-dependent algorithm will be used.- Since:
- JAI 1.1
-
-