Package org.geotools.gce.imagemosaic

Interface GranuleImageCache

All Known Implementing Classes:
GuavaGranuleImageCache
public interface GranuleImageCache
A bounded, shared pool of decoded whole-granule images that ImageMosaicReaders can reuse across requests, sized by total decoded bytes with LRU eviction. Built and owned by the caller, injected into readers at construction time through Hints.GRANULE_IMAGE_CACHE and enabled via the ImageMosaicFormat.CACHE_GRANULES read parameter. Implementations must be thread-safe.

Entries are keyed by owning mosaic plus granule URL, image index and band selection, so the pool can shed a mosaic's whole footprint at once through invalidateMosaic(String) when its reader is disposed (store reload, remove or reset): heap then tracks the mosaic's lifecycle instead of lingering until the LRU bound reclaims it. A stale single granule (an in-place overwrite, a re-harvest, a delete) is dropped with invalidateGranule(URL), and invalidateAll() clears the pool. The band selection is part of the key because it's typically associated with multispectral/hyperspectral images where there are too many bands to cache the whole set.

A cached BufferedImage is shared, as-is, by every request that hits it, so the read path must treat it strictly read-only: no consumer may write into its raster in place, or it would corrupt other requests' and other mosaics' reads.

  • Method Details

    • reconfigure

      void reconfigure(long maximumSizeBytes, long defaultThresholdBytes)
      Applies new sizing while keeping this instance's identity, so readers holding it through Hints.GRANULE_IMAGE_CACHE see the change with no rebuild on their side. A change in total size may drop the current entries and free their heap at once; the threshold is applied in place.

    • isEnabled

      boolean isEnabled()
      Whether caching is on: a non-positive max size means the pool is present but denies caching.

    • size

      long size()
      Number of granule images currently held.

    • invalidateAll

      void invalidateAll()
      Drops all cached granule images.

    • invalidateGranule

      void invalidateGranule(URL granuleUrl)
      Drops every cached read of the given granule, whatever the mosaic, image index or band selection.

    • invalidateMosaic

      void invalidateMosaic(String mosaicId)
      Drops every entry owned by the given mosaic, called when its reader is disposed to free heap at once.

    • getMaximumSizeBytes

      long getMaximumSizeBytes()
      Maximum size of the pool, in bytes.

    • getDefaultThresholdBytes

      long getDefaultThresholdBytes()
      Largest decoded granule eligible for caching, in bytes (a read parameter can override it).

    • get

      BufferedImage get(ImageCacheKey key)
      Returns the cached image for the key, or null on a miss; never loads.

    • getOrLoad

      BufferedImage getOrLoad(ImageCacheKey key, Callable<BufferedImage> loader) throws Exception
      Returns the cached image for the key, loading it once atomically if absent. Returns null if the loader signals nothing was read by throwing GranuleImageCache.MissingRasterException; any other loader failure propagates.
      Throws:
      Exception