Package com.luciad.earth.tileset.util

Class TLcdEarthAsynchronousTileSet

java.lang.Object
com.luciad.earth.tileset.util.ALcdEarthTileSetWrapper
com.luciad.earth.tileset.util.TLcdEarthAsynchronousTileSet
All Implemented Interfaces:
ILcdEarthTileSet, ILcdBounded, ILcdDisposable, AutoCloseable
public class TLcdEarthAsynchronousTileSet extends ALcdEarthTileSetWrapper
A wrapper for an ILcdEarthTileSet that can execute produceTile and updateTile requests asynchronously using an ExecutorService. By using this wrapper, any existing tileset can be extended with asynchronous operation support. This simplifies the implementation of custom tilesets.

This tileset is thread-safe for tile reading if the delegate tileset is also thread-safe for tile reading.

Since:
8.2

  • Constructor Details

    • TLcdEarthAsynchronousTileSet

      public TLcdEarthAsynchronousTileSet(ILcdEarthTileSet aDelegate, String aDisplayName)
      Creates a new asynchronous wrapper around the specified tileset that uses an ExecutorService with a single thread to produce tiles. The display name parameter is used to name the thread created by this tileset.
      Parameters:
      aDelegate - the tileset to be wrapped
      aDisplayName - the name to be used for the worker thread

    • TLcdEarthAsynchronousTileSet

      public TLcdEarthAsynchronousTileSet(ILcdEarthTileSet aDelegate, String aDisplayName, int aNumThreads)
      Creates a new asynchronous wrapper around the specified tileset that uses an ExecutorService with the specified number of threads to produce tiles. The display name parameter is used to name the threads created by this tileset.
      Parameters:
      aDelegate - the tileset to be wrapped
      aDisplayName - the name to be used for the worker thread
      aNumThreads - the number of threads to use

    • TLcdEarthAsynchronousTileSet

      public TLcdEarthAsynchronousTileSet(ILcdEarthTileSet aTileSet, ExecutorService aExecutorService)
      Constructs a new TLcdEarthAsynchronousExecutorTileSet that uses the specified executor service to produce tiles. The specified executor service will be shut down when this tileset is disposed.
      Parameters:
      aTileSet - the delegate tileset
      aExecutorService - the executor service
      See Also:

    • TLcdEarthAsynchronousTileSet

      public TLcdEarthAsynchronousTileSet(ILcdEarthTileSet aTileSet, ExecutorService aExecutorService, boolean aShutDownExecutorServiceOnDispose)
      Constructs a new TLcdEarthAsynchronousExecutorTileSet that uses the specified executor service to produce tiles.
      Parameters:
      aTileSet - the delegate tileset
      aExecutorService - the executor service
      aShutDownExecutorServiceOnDispose - whether aExecutorService will be shut down when this tileset is disposed or not
      See Also:

  • Method Details

    • isShutdownExecutorServiceOnDispose

      public boolean isShutdownExecutorServiceOnDispose()
      Whether executor service will be shut down when this tileset is disposed or not.
      Returns:
      true if the executor service will be shut down when this tileset is disposed; false otherwise
      See Also:

    • setPriority

      public void setPriority(int aNewPriority)
      Sets the priority of the thread used by this asynchronous tileset. This method has no effect if an ExecutorService was specified in the constructor.
      Parameters:
      aNewPriority - a priority value accepted by java.lang.Thread#setPriority()

    • getPriority

      public int getPriority()
      Returns the priority of the thread used by this asynchronous tileset if no ExecutorService was specified in the constructor. Otherwise an invalid priority is returned.
      Returns:
      a priority value accepted by java.lang.Thread#setPriority() if no ExecutorService was specified in the constructor. Otherwise an invalid priority is returned.

    • setDelegateTileOperationMode

      public void setDelegateTileOperationMode(TLcdEarthTileOperationMode aDelegateTileOperationMode)
      Sets the tile operation mode used on the delegate tile set when producing tiles asynchronously.

      If the delegate mode is set to TLcdEarthTileOperationMode.PREFER_ASYNCHRONOUS then the tile production may (partially) occur on other threads then those of this tile set. Otherwise, if the mode is set to TLcdEarthTileOperationMode.FORCE_SYNCHRONOUS then the tile production can only occur on the threads of this tile set. This can for example be used to ensure full control on the threading from a single ExecutorService.

      The default value is TLcdEarthTileOperationMode.PREFER_ASYNCHRONOUS.

      Parameters:
      aDelegateTileOperationMode - the tile operation mode

    • getDelegateTileOperationMode

      public TLcdEarthTileOperationMode getDelegateTileOperationMode()
      Returns the tile operation mode used on the delegate tile set when producing tiles asynchronously.
      Returns:
      the tile operation mode
      See Also:

    • produceTile

      public void produceTile(ILcdEarthTileSetCoverage aCoverage, int aLevel, long aTileX, long aTileY, ILcdGeoReference aGeoReference, TLcdEarthTileFormat aFormat, TLcdEarthTileOperationMode aMode, ILcdEarthTileSetCallback aCallback, Object aContext)
      Description copied from interface: ILcdEarthTileSet
      Produces the requested tile, and invoke the supplied callback when done. The resulting tile is passed to the call back's tileAvailable() method. If the tile cannot be produced for some reason, the method tileNotAvailable() should be called instead.

      If the tileset supports it and aMode is TLcdEarthTileOperationMode.PREFER_ASYNCHRONOUS, the tile request may be executed asynchronously. However, the callback must be invoked at some point in time, unless the cancelTile() method is used to cancel the tile request before it is executed. If aMode is TLcdEarthTileOperationMode.FORCE_SYNCHRONOUS, the request must be executed synchronously and the callback must be invoked before produceTile() returns.

      Tiles may be requested in reference systems other than the native geo reference of the underlying data, provided that the isGeoReferenceSupported() method returns true for the requested reference. If this is not the case, the tileset should call tileNotAvailable(). If the tileset calls tileAvailable(), the geo reference of the resulting tile must be equal to aGeoReference, and the tile's bounds must likewise be expressed in this reference.

      Similarly, tiles may be requested in different data formats, as described by TLcdEarthTileFormat. The format determines the type of the data object that will be contained in the requested tile. To check if a format is supported, use isFormatSupported(). If the specified format is not supported, the tileset should call tileNotAvailable().

      The context parameter may be used to pass application-specific data into the tileset. If it is not needed, its value may be null.

      Specified by:
      produceTile in interface ILcdEarthTileSet
      Overrides:
      produceTile in class ALcdEarthTileSetWrapper
      Parameters:
      aCoverage - the coverage from which the tile is requested
      aLevel - the level from which the tile is requested
      aTileX - the column index of the requested tile
      aTileY - the row index of the requested tile
      aGeoReference - the reference system in which the tile should be returned
      aFormat - the desired format of the tile's data
      aMode - controls the synchronous or asynchronous behaviour of the tileset
      aCallback - will be invoked when the tile is available to be used
      aContext - application-specific data to be used by the tileset, if any

    • updateTile

      public void updateTile(ALcdEarthTile aEarthTile, TLcdEarthTileOperationMode aMode, ILcdEarthTileSetCallback aCallback, Object aContext)
      Description copied from interface: ILcdEarthTileSet
      Produces an updated version of the given tile, if necessary. Produces the same tile if the given tile is up to date.
      Specified by:
      updateTile in interface ILcdEarthTileSet
      Overrides:
      updateTile in class ALcdEarthTileSetWrapper
      Parameters:
      aEarthTile - tile to check
      aMode - controls the synchronous or asynchronous behaviour of the tileset
      aCallback - will be invoked when the tile is available to be used
      aContext - application-specific data to be used by the tileset, if any

    • cancelTile

      public void cancelTile(int aLevel, long aTileX, long aTileY, ILcdEarthTileSetCoverage aCoverage, ILcdGeoReference aGeoReference, TLcdEarthTileFormat aFormat, ILcdEarthTileSetCallback aCallback, Object aContext)
      Description copied from class: ALcdEarthTileSetWrapper
      This method should be overridden if the produceTile and/or updateTile is overridden and the new implementation calls the implementation of this class using different parameters than passed to it.

      If the produceTile is overridden as 

       super.produceTile( myCoverage, aLevel, aTileX, aTileY, aGeoReference, aFormat, aMode, new MyTileSetCallback( aCallback ), aContext );
      this method should be overridden as 
       super.cancelTile( aLevel, aTileX, aTileY, myCoverage, aGeoReference, aFormat, new MyTileSetCallback( aCallback ), aContext );
      where MyTileSetCallback instances with the same delegate callback are equal.
      Specified by:
      cancelTile in interface ILcdEarthTileSet
      Overrides:
      cancelTile in class ALcdEarthTileSetWrapper
      Parameters:
      aLevel - the level from which the tile is requested
      aTileX - the column index of the requested tile
      aTileY - the row index of the requested tile
      aCoverage - the coverage from which the tile is requested
      aGeoReference - the reference system in which the tile is requested
      aFormat - the format in which the tile is requested
      aCallback - would be invoked when the tile would have been available to be used
      aContext - application-specific data to be used by the tileset, if any

    • dispose

      public void dispose()
      This will also shut down the executor service depending on the isShutdownExecutorServiceOnDispose() setting and cancel any remaining tasks that were submitted to the ExecutorService by this tileset.
      Specified by:
      dispose in interface ILcdDisposable
      Specified by:
      dispose in interface ILcdEarthTileSet
      Overrides:
      dispose in class ALcdEarthTileSetWrapper