Package org.apache.sis.image

Class ComputedTiles

java.lang.Object
java.lang.ref.Reference<T>
java.lang.ref.WeakReference<ComputedImage>
org.apache.sis.image.ComputedTiles
All Implemented Interfaces:
TileObserver, Disposable
final class ComputedTiles extends WeakReference<ComputedImage> implements Disposable, TileObserver
Weak reference to a ComputedImage image together with information about tile status. This class also contains necessary information for releasing resources when image is disposed. This class shall not contain any strong reference to the ComputedImage.

Despite the ComputedTiles class name, this class does not contain any reference to the tiles. Instead, it contains keys for getting the tiles from TileCache.GLOBAL. Consequently, this class "contains" the tiles only indirectly.

Since:
1.1
Version:
1.1

  • Field Details

    • VALID

      private static final int VALID
      Whether a tile in the cache is ready for use or needs to be recomputed because one if its sources changed its data. Those values are stored in cachedTiles map.
      • VALID means that the tile, if presents, is ready for use. A tile may be non-existent in the cache despite being marked VALID if the tile has been garbage-collected after it has been marked.
      • DIRTY means that the tile needs to be recomputed. If the tile is present, its data should be discarded but its storage space will be reused.
      • ERROR means that the previous attempt to compute this tile failed.
      • All other values means that the tile has been checkout out for a write operation. That value is incremented/decremented when the writable tile is acquired/released. Write operation status have precedence over the dirty state.
      • COMPUTING is a special case of above point when calculation just started.
      See Also:

    • DIRTY

      private static final int DIRTY
      Whether a tile in the cache is ready for use or needs to be recomputed because one if its sources changed its data. Those values are stored in cachedTiles map.
      • VALID means that the tile, if presents, is ready for use. A tile may be non-existent in the cache despite being marked VALID if the tile has been garbage-collected after it has been marked.
      • DIRTY means that the tile needs to be recomputed. If the tile is present, its data should be discarded but its storage space will be reused.
      • ERROR means that the previous attempt to compute this tile failed.
      • All other values means that the tile has been checkout out for a write operation. That value is incremented/decremented when the writable tile is acquired/released. Write operation status have precedence over the dirty state.
      • COMPUTING is a special case of above point when calculation just started.
      See Also:

    • ERROR

      private static final int ERROR
      Whether a tile in the cache is ready for use or needs to be recomputed because one if its sources changed its data. Those values are stored in cachedTiles map.
      • VALID means that the tile, if presents, is ready for use. A tile may be non-existent in the cache despite being marked VALID if the tile has been garbage-collected after it has been marked.
      • DIRTY means that the tile needs to be recomputed. If the tile is present, its data should be discarded but its storage space will be reused.
      • ERROR means that the previous attempt to compute this tile failed.
      • All other values means that the tile has been checkout out for a write operation. That value is incremented/decremented when the writable tile is acquired/released. Write operation status have precedence over the dirty state.
      • COMPUTING is a special case of above point when calculation just started.
      See Also:

    • COMPUTING

      private static final int COMPUTING
      Whether a tile in the cache is ready for use or needs to be recomputed because one if its sources changed its data. Those values are stored in cachedTiles map.
      • VALID means that the tile, if presents, is ready for use. A tile may be non-existent in the cache despite being marked VALID if the tile has been garbage-collected after it has been marked.
      • DIRTY means that the tile needs to be recomputed. If the tile is present, its data should be discarded but its storage space will be reused.
      • ERROR means that the previous attempt to compute this tile failed.
      • All other values means that the tile has been checkout out for a write operation. That value is incremented/decremented when the writable tile is acquired/released. Write operation status have precedence over the dirty state.
      • COMPUTING is a special case of above point when calculation just started.
      See Also:

    • cachedTiles

      private final Map<TileCache.Key,Integer> cachedTiles
      Indices of all cached tiles. Used for removing tiles from the cache when the image is disposed. Values can be ERROR, DIRTY, VALID or counts of writers as unsigned integers (including COMPUTING and VALID as special cases). All accesses to this collection must be synchronized.

    • sources

      private WritableRenderedImage[] sources
      All ComputedImage.sources that are writable, or null if none. This is used for removing tile observers when the ComputedImage is garbage-collected.

  • Constructor Details

    • ComputedTiles

      ComputedTiles(ComputedImage image, WritableRenderedImage[] ws)
      Creates a new weak reference to the given image and registers this ComputedTiles as a listener of all given sources. The listeners will be automatically removed when the ComputedImage is garbage collected.
      Parameters:
      image - the image for which to release tiles on garbage-collection.
      ws - sources to observe for changes, or null if none.

  • Method Details

    • isWritable

      private static boolean isWritable(Integer value)
      Returns true if the given value is COMPUTING or a greater unsigned value. Returns false if the value is null, VALID, DIRTY or ERROR.

    • isTileWritable

      final boolean isTileWritable(TileCache.Key key)
      Returns true if the specified tile is checked out for a write operation.
      Parameters:
      key - indices of the tile to check.
      Returns:
      whether the specified tile is checked out for a write operation.

    • isTileDirty

      final boolean isTileDirty(TileCache.Key key)
      Returns true if the specified tile needs to be recomputed. An absent tile is considered as dirty. If previous attempt to compute the tile failed, then an ImagingOpException is thrown again.
      Parameters:
      key - indices of the tile to check.
      Returns:
      whether the specified tile needs to be recomputed.
      Throws:
      ImagingOpException - if we already tried and failed to compute the specified tile.

    • trySetComputing

      final boolean trySetComputing(TileCache.Key key)
      If the specified tile is absent or DIRTY, sets its status to COMPUTING and returns true. Otherwise if there are no errors, does nothing and returns false.
      Parameters:
      key - indices of the tile to compute if dirty.
      Returns:
      whether the specified tile was absent or dirty.
      Throws:
      ImagingOpException - if we already tried and failed to compute the specified tile.

    • startWrite

      final boolean startWrite(TileCache.Key key)
      Increments the count of writers for the specified tile. If the specified tile was marked dirty or in error, that previous status is discarded.
      Parameters:
      key - indices of the tile to mark writable.
      Returns:
      true if the tile goes from having no writers to having one writer.
      Throws:
      ArithmeticException - if too many writers.

    • endWrite

      final boolean endWrite(TileCache.Key key, boolean success)
      Decrements the count of writers for the specified tile.
      Parameters:
      key - indices of the tile which was marked writable.
      success - whether the operation should be considered successful.
      Returns:
      true if the tile goes from having one writer to having no writers.

    • increment

      private static Integer increment(Integer value, Integer computing)
      If the value is VALID, DIRTY or ERROR, sets it to COMPUTING. Otherwise increments that value.
      Parameters:
      value - the value to increment.
      computing - must be COMPUTING.
      Returns:
      the incremented value.

    • decrement

      private static Integer decrement(Integer value, Integer status)
      If the value is VALID, DIRTY, ERROR or COMPUTING, sets that value to VALID or ERROR. Otherwise decrements that value.
      Parameters:
      value - the value to decrement.
      status - VALID or ERROR.
      Returns:
      the decremented value.

    • getWritableTileIndices

      final boolean getWritableTileIndices(List<Point> indices)
      Adds in the given list the indices of all tiles which are checked out for writing. If the given list is null, then this method stops the search at the first writable tile.
      Parameters:
      indices - the list where to add indices, or null if none.
      Returns:
      whether at least one tile is checked out for writing.

    • markDirtyTiles

      final boolean markDirtyTiles(int minTileX, int minTileY, int maxTileX, int maxTileY, boolean error)
      Marks all tiles in the given range of indices as in need of being recomputed. This method is invoked when some tiles of at least one source image changed. All arguments, including maximum values, are inclusive.
      Parameters:
      error - false for marking valid tiles as dirty, or true for marking tiles in error.
      Returns:
      true if at least one tile got its status updated.
      See Also:

    • tileUpdate

      public void tileUpdate(WritableRenderedImage source, int tileX, int tileY, boolean willBeWritable)
      Invoked when a source is changing the content of one of its tile. This method is interested only in events fired after the change is done. The tiles that depend on the modified tile are marked in need to be recomputed.
      Specified by:
      tileUpdate in interface TileObserver
      Parameters:
      source - the image that own the tile which is about to be updated.
      tileX - the x index of the tile that is being updated.
      tileY - the y index of the tile that is being updated.
      willBeWritable - if true, the tile is grabbed for writing; otherwise it is being released.

    • dispose

      public void dispose()
      Invoked when the ComputedImage has been garbage-collected. This method removes all cached tiles that were owned by the image and stops observing all sources. This method should not perform other cleaning work because it is not guaranteed to be invoked if this ComputedTiles is not registered as a TileObserver and if TileCache.GLOBAL does not contain any tile for the ComputedImage. The reason is because there would be nothing preventing this weak reference to be garbage collected before dispose() is invoked.
      Specified by:
      dispose in interface Disposable
      See Also:

    • unregister

      private void unregister(WritableRenderedImage[] ws, int i, RuntimeException failure)
      Stops observing writable sources for modifications. This method is invoked when the ComputedImage is garbage collected. It may also be invoked for rolling back observer registrations if an error occurred during ComputedTiles construction. This method clears the sources field immediately for allowing the garbage collector to release the sources in the event where this ComputedTiles would live longer than expected.
      Parameters:
      ws - a copy of sources. Cannot be null.
      i - index after the last source to stop observing.
      failure - if this method is invoked because an exception occurred, that exception.