com.luciad.earth.tileset.util

LuciadLightspeedClass 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 Summary

Constructors

Constructor and Description
TLcdEarthAsynchronousTileSet(ILcdEarthTileSet aTileSet, ExecutorService aExecutorService) Constructs a new TLcdEarthAsynchronousExecutorTileSet that uses the specified executor service to produce tiles.
TLcdEarthAsynchronousTileSet(ILcdEarthTileSet aTileSet, ExecutorService aExecutorService, boolean aShutDownExecutorServiceOnDispose) Constructs a new TLcdEarthAsynchronousExecutorTileSet that uses the specified executor service to produce tiles.
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.
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.

Method Summary

Modifier and Type	Method and Description
void	cancelTile(int aLevel, long aTileX, long aTileY, ILcdEarthTileSetCoverage aCoverage, ILcdGeoReference aGeoReference, TLcdEarthTileFormat aFormat, ILcdEarthTileSetCallback aCallback, Object aContext) 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.
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.
TLcdEarthTileOperationMode	getDelegateTileOperationMode() Returns the tile operation mode used on the delegate tile set when producing tiles asynchronously.
int	getPriority() Returns the priority of the thread used by this asynchronous tileset if no ExecutorService was specified in the constructor.
boolean	isShutdownExecutorServiceOnDispose() Whether executor service will be shut down when this tileset is disposed or not.
void	produceTile(ILcdEarthTileSetCoverage aCoverage, int aLevel, long aTileX, long aTileY, ILcdGeoReference aGeoReference, TLcdEarthTileFormat aFormat, TLcdEarthTileOperationMode aMode, ILcdEarthTileSetCallback aCallback, Object aContext) Produces the requested tile, and invoke the supplied callback when done.
void	setDelegateTileOperationMode(TLcdEarthTileOperationMode aDelegateTileOperationMode) Sets the tile operation mode used on the delegate tile set when producing tiles asynchronously.
void	setPriority(int aNewPriority) Sets the priority of the thread used by this asynchronous tileset.
void	updateTile(ALcdEarthTile aEarthTile, TLcdEarthTileOperationMode aMode, ILcdEarthTileSetCallback aCallback, Object aContext) Produces an updated version of the given tile, if necessary.

Methods inherited from class com.luciad.earth.tileset.util.ALcdEarthTileSetWrapper

containsTile, containsTileSetCoverage, getBounds, getDelegateTileSet, getLevelCount, getTileColumnCount, getTileRowCount, getTileSetCoverage, getTileSetCoverage, getTileSetCoverageCount, isFormatSupported, isGeoReferenceSupported, produceTile, updateTile

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.luciad.util.ILcdDisposable

close

Constructor Detail

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:

dispose()

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:

dispose()

Method Detail

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:

dispose()

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:

setDelegateTileOperationMode(com.luciad.earth.tileset.TLcdEarthTileOperationMode)

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 ILcdEarthTileSet

Specified by:

dispose in interface ILcdDisposable

Overrides:

dispose in class ALcdEarthTileSetWrapper