public class TLfnCachingTileStore extends ALfnTileStoreWrapper
All write operations (ALfnTileStoreWrapper.deleteResource(java.lang.String)
, ALfnTileStoreWrapper.putResourceMetadata(T)
etc.) work on the remote Tile Store.
These operations propagate failures of the remote Tile Store onto the handlers.
The 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.
The 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:
isOnline()
.
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 ALfnTileStoreProvider
.
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 ALfnTileStoreProvider
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.
ALfnTileStore.CommitPolicy, ALfnTileStore.ReadResult, ALfnTileStore.Result, ALfnTileStore.WriteResult
fDelegate
Constructor and Description |
---|
TLfnCachingTileStore(ALfnTileStoreProvider aTileStoreProvider,
URI aTileStoreUri,
ALfnTileStore aTileCache,
long aLowMark,
long aHighMark,
long aExpirationDuration)
Constructs an instance of this class, using a local Tile Store owned by the caller as tile cache.
|
TLfnCachingTileStore(ALfnTileStoreProvider aTileStoreProvider,
URI aTileStoreUri,
URI aTileCacheUri,
long aLowMark,
long aHighMark,
long aExpirationDuration)
Constructs an instance of this class, using a tile cache owned by the instance.
|
Modifier and Type | Method and Description |
---|---|
void |
close()
Closes this Tile Store instance.
|
TLfnTileStoreCapabilities |
getCapabilities()
Gets the capabilities offered by the Tile Store.
|
ALfnCoverage |
getCoverage(String aID)
Gets a coverage from the Tile Store.
|
<T extends ALfnResourceMetadata> |
getResourceMetadata(String aID)
Gets the metadata of a resource.
|
boolean |
isOnline()
Checks if this caching Tile Store is working in online or offline mode.
|
Future<?> |
query(ILfnQueryHandler aHandler,
TLfnQuery aQuery)
Queries the Tile Store for resources' metadata.
|
String |
toString()
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, URI aTileStoreUri, ALfnTileStore aTileCache, long aLowMark, long aHighMark, long aExpirationDuration) throws TLfnServiceException, 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 URIaTileStoreUri
- the URI of the backing Tile StoreaTileCache
- the tile cache, which must be a TLfnFileSystemTileStore
or 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 0
.
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 Long.MAX_VALUE
.TLfnServiceException
IOException
public TLfnCachingTileStore(ALfnTileStoreProvider aTileStoreProvider, URI aTileStoreUri, URI aTileCacheUri, long aLowMark, long aHighMark, long aExpirationDuration) throws 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 null
.aTileStoreUri
- the URI of the remote Tile Store, which must not be null
aTileCacheUri
- the URI of the tile cache, which must not be null
. Must not be in use by other clients.aLowMark
- the low markaHighMark
- the high markaExpirationDuration
- the expiration duration in milliseconds since epochIOException
- if creation of the tile cache or remote Tile Store failedTLfnServiceException
- if creation of the tile cache or remote Tile Store failedTLfnCachingTileStore(ALfnTileStoreProvider, java.net.URI, ALfnTileStore, long, long, long)
public Future<?> query(ILfnQueryHandler aHandler, TLfnQuery aQuery)
ALfnTileStore
query
in class ALfnTileStoreWrapper
aHandler
- the handler for the resultsaQuery
- the query to be performedpublic TLfnTileStoreCapabilities getCapabilities() throws IOException, TLfnServiceException
ALfnTileStore
The capabilities provide the Tile Store metadata and the supported operations. The operations are defined as constants on this class.
getCapabilities
in class ALfnTileStoreWrapper
IOException
- in case of an I/O failureTLfnServiceException
- in case of a service processing failurepublic ALfnCoverage getCoverage(String aID) throws IOException, TLfnServiceException
ALfnTileStore
ALfnTileStore.getCoverageIds()
ALfnTileStore.query(ILfnQueryHandler, TLfnQuery)
and get the ID from the metadatagetCoverage
in class ALfnTileStoreWrapper
aID
- the ID of the desired coveragenull
if it does not existIOException
- in case of an I/O failureTLfnServiceException
- in case of a service processing failureALfnCoverage
public <T extends ALfnResourceMetadata> T getResourceMetadata(String aID) throws IOException, TLfnServiceException
ALfnTileStore
This implementation throws UnsupportedOperationException
.
Subclasses should override it to do something useful.
getResourceMetadata
in interface ILfnResourceMetadataResolver
getResourceMetadata
in class ALfnTileStoreWrapper
aID
- the ID of the desired resourcenull
if it does not existIOException
- in case of an I/O failureTLfnServiceException
- in case of a service processing failurepublic boolean isOnline()
true
if this cache is online, false
if is working in offline modepublic void close() throws IOException
ALfnTileStore
close
in interface Closeable
close
in interface AutoCloseable
close
in class ALfnTileStoreWrapper
IOException
- in case of an I/O failurepublic String toString()
ALfnTileStore
toString
in class ALfnTileStoreWrapper