public class TLfnCachingTileStore extends ALfnTileStoreWrapper
All write operations (
ALfnTileStoreWrapper.putResourceMetadata(T) etc.) work on the remote Tile Store.
These operations propagate failures of the remote Tile Store onto the handlers.
query(com.luciad.fusion.tilestore.ILfnQueryHandler, com.luciad.fusion.tilestore.TLfnQuery) operation first tries the remote Tile Store, and only falls back to the tile cache in case of a failure.
ALfnCoverage.getTile(com.luciad.fusion.core.TLfnTileCoordinates, long, java.nio.channels.WritableByteChannel, java.nio.ByteBuffer, com.luciad.fusion.tilestore.ILfnReadCallback) operation tries the tile cache first, and only falls back to the remote Tile Store in case of a cache miss.
This may return stale tiles: when tiles are deleted or updated on the remote Tile Store, a stale cached version may still be returned.
The staleness of cached tiles can be controlled with the expiration duration, but is ignored if the remote Tile Store is offline.
A low expiration duration yields tiles that are less state, at the expense of bandwidth.
Caching and expiration of tiles works according to the following rules:
Read operations query(com.luciad.fusion.tilestore.ILfnQueryHandler, com.luciad.fusion.tilestore.TLfnQuery) and
ALfnCoverage.getTile(com.luciad.fusion.core.TLfnTileCoordinates, long, java.nio.channels.WritableByteChannel, java.nio.ByteBuffer, com.luciad.fusion.tilestore.ILfnReadCallback) never propagate failures of the remote Tile Store onto the handlers.
This allows users to continue working offline.
The remote Tile Store instance is owned (created and maintained) by an instance of this class. Closing an instance
also closes the Tile Store it owns. Remote Tile Store instances are created through the
When the remote Tile Store is offline, an instance of this class will regularly attempt to reconnect by recreating a new remote Tile Store instance.
The tile cache instance is never owned by an instance of this class. This means that the tile cache instance is
not closed when the caching instance is closed. Tile stores that are retrieved from an
must be closed by destroying the tile store provider instance.
In either case, the tile cache must not be in use by other clients.
It is a known limitation of this implementation that it ignores the modification time of a 'getTile' request. As a result, the implementation never returns "not modified", but always transfers the whole data, even if it has a modification time less than or equal to a modification time. In other words, the benefit of "conditional" 'getTile' requests is lost.
|Constructor and Description|
Constructs an instance of this class, using a local Tile Store owned by the caller as tile cache.
Constructs an instance of this class, using a tile cache owned by the instance.
|Modifier and Type||Method and Description|
Closes this Tile Store instance.
Gets the capabilities offered by the Tile Store.
Gets a coverage from the Tile Store.
Gets the metadata of a resource.
Checks if this caching Tile Store is working in online or offline mode.
Queries the Tile Store for resources' metadata.
Returns the URI as a string representation of this Tile Store.
deleteResource, deleteUserData, getAsset, getCoverageIds, getMetadata, getRasterAssetMetadata, getRasterCoverageMetadata, getTheme, getThemeMetadata, getURI, getUserData, getVectorAssetMetadata, getVectorCoverageMetadata, putMetadata, putRasterAssetMetadata, putRasterCoverageMetadata, putResourceMetadata, putThemeMetadata, putUserData, putVectorAssetMetadata, putVectorCoverageMetadata, query
public TLfnCachingTileStore(ALfnTileStoreProvider aTileStoreProvider, java.net.URI aTileStoreUri, ALfnTileStore aTileCache, long aLowMark, long aHighMark, long aExpirationDuration) throws TLfnServiceException, java.io.IOException
Closing this instance will close the remote Tile Store but not the tile cache, since it is owned by the caller.
The tile cache
(aTileCache) must not be in use by other clients.
aTileStoreProvider- the Tile Store provider which will be used to (re)create the Tile Store(s) from URI
aTileStoreUri- the URI of the backing Tile Store
aTileCache- the tile cache, which must be a
TLfnFileSystemTileStoreor a wrapper thereof. The tile cache instance will not be closed when this object is closed, it is the responsibility of the caller to close it. Must not be in use by other clients.
aLowMark- the cache size's low mark, in bytes, which must be positive and strictly smaller than the high mark. This is the size the cache will be reduced to when the cache is swept. This is not a strict guarantee, it is more a guideline. Setting the low mark to a significantly smaller value than the high mark will result in less frequent sweeps, at the cost of falling back to nearly no cached tiles. A good trade-off typically involves a low mark that is at 75 % of the high mark. It makes no sense to set the low mark higher than 95 % of the high mark, because that would result in too frequent sweeps with little benefit. The system will guard itself against this by keeping at least a 5 % distance between the low and high mark.
When using a high mark of Long.MAX_VALUE, the low mark is irrelevant and can be set to
aHighMark- the cache size's high mark, in bytes, which must be positive. When the cache size grows larger than the high mark, the oldest tiles will automatically be swept in an attempt to keep its size between the high and low mark. Because this sweeping is an asynchronous background process, there is no guarantee that the cache size will be between the low and high mark at all times. The marks are more guidelines than strict guarantees.
For maximum flexibility when working offline, use
Long.MAX_VALUE as high mark (when disk space is no issue).
aExpirationDuration- the expiration duration of cached tiles in milliseconds. A low value yields cached tiles which are more up-to-date, at the expense of bandwidth: expired tiles will need to be reloaded from the remote Tile Store more often. Use a high value of one hour or more if you don't require up-to-date tiles. Use a low value of a couple of minutes or less if you require up-to-date tiles. For a Tile Store containing truly static tiles, you can even use
public TLfnCachingTileStore(ALfnTileStoreProvider aTileStoreProvider, java.net.URI aTileStoreUri, java.net.URI aTileCacheUri, long aLowMark, long aHighMark, long aExpirationDuration) throws java.io.IOException, TLfnServiceException
Closing this instance will close both the remote Tile Store and the tile cache.
The tile cache
(aTileCacheUri) must not be in use by other clients.
aTileStoreProvider- a Tile Store provider from which both Tile Store and tile cache will be created. It must not be
aTileStoreUri- the URI of the remote Tile Store, which must not be
aTileCacheUri- the URI of the tile cache, which must not be
null. Must not be in use by other clients.
aLowMark- the low mark
aHighMark- the high mark
aExpirationDuration- the expiration duration in milliseconds since epoch
java.io.IOException- if creation of the tile cache or remote Tile Store failed
TLfnServiceException- if creation of the tile cache or remote Tile Store failed
TLfnCachingTileStore(ALfnTileStoreProvider, java.net.URI, ALfnTileStore, long, long, long)
public java.util.concurrent.Future<?> query(ILfnQueryHandler aHandler, TLfnQuery aQuery)
public TLfnTileStoreCapabilities getCapabilities() throws java.io.IOException, TLfnServiceException
The capabilities provide the Tile Store metadata and the supported operations. The operations are defined as constants on this class.
public ALfnCoverage getCoverage(java.lang.String aID) throws java.io.IOException, TLfnServiceException
public <T extends ALfnResourceMetadata> T getResourceMetadata(java.lang.String aID) throws java.io.IOException, TLfnServiceException
This implementation throws
Subclasses should override it to do something useful.
aID- the ID of the desired resource
nullif it does not exist
java.io.IOException- in case of an I/O failure
TLfnServiceException- in case of a service processing failure
public boolean isOnline()
trueif this cache is online,
falseif is working in offline mode
public void close() throws java.io.IOException