com.luciad.fusion.tilestore

LuciadFusionClass ALfnCoverage

java.lang.Object

com.luciad.fusion.tilestore.ALfnResource<ALfnCoverageMetadata>

com.luciad.fusion.tilestore.ALfnCoverage

public abstract class ALfnCoverage
extends ALfnResource<ALfnCoverageMetadata>

Provides the description of the coverage and also functionality to put, get and delete individual tiles of the coverage. A coverage defines a multi-level grid of tiles that must share the following characteristics:

• data type ELfnDataType, for example IMAGE or ELEVATION
• (native) geographic reference, for example WGS 84 geodetic system
• (native) tile format, for example jpg or png

By default, the coverage operations implemented in this class throw an UnsupportedOperationException. Implementations of this class should override and implement the operation methods that need to be supported.

Implementations of this class are thread-safe.

User data

You can associate arbitrary binary data with a coverage using its user data. Each coverage has a key-blob store that you can use to store your own data.

This user data is stored on the Tile Store itself, so you can access from anywhere. When the coverage is removed, the user data is also removed.

Note: this store is not optimized for very frequent access, large blobs or many keys.

Since:

10.0

Constructor Summary

Constructors

Constructor and Description
ALfnCoverage()

Method Summary

Modifier and Type	Method and Description
Future<?>	deleteTile(ILfnDeleteTileHandler aHandler, TLfnTileCoordinates aCoordinates) Deprecated. use deleteTile(com.luciad.fusion.core.TLfnTileCoordinates, com.luciad.fusion.util.ILfnCallback) instead
Future<ALfnTileStore.WriteResult>	deleteTile(TLfnTileCoordinates aCoordinates, ILfnCallback<ALfnTileStore.WriteResult> aCallback) Asynchronously deletes a tile from this coverage.
Future<ALfnTileStore.WriteResult>	deleteUserData(String aKey, ILfnCallback<ALfnTileStore.WriteResult> aCallback) Deletes binary user data from this resource with a given key.
Future<?>	exportTo(ILfnExportHandler aHandler, WritableByteChannel aSink) Deprecated. use ALfnResource.exportTo(java.nio.channels.WritableByteChannel, ILcdShape, com.luciad.reference.ILcdGeoReference, ILfnProgressCallback) instead
Future<ALfnTileStore.ReadResult>	exportTo(WritableByteChannel aSink, ILcdShape aAreaOfInterest, ILcdGeoReference aAreaOfInterestGeoReference, ILfnProgressCallback<ALfnTileStore.ReadResult> aCallback) Asynchronously exports this resource's data to a channel, excluding metadata.
Future<?>	getTile(ILfnGetTileHandler aHandler, TLfnTileCoordinates aCoordinates, long aModificationTime, WritableByteChannel aSink, ByteBuffer aMessageDigest) Deprecated. use getTile(com.luciad.fusion.core.TLfnTileCoordinates, long, java.nio.channels.WritableByteChannel, java.nio.ByteBuffer, ILfnReadCallback) instead
Future<ALfnTileStore.ReadResult>	getTile(TLfnTileCoordinates aCoordinates, long aModificationTime, WritableByteChannel aSink, ByteBuffer aMessageDigest, ILfnReadCallback aCallback) Asynchronously gets a tile from this coverage, including the tile message digest.
Iterable<TLfnTileCoordinates>	getTileCoordinates() Returns an Iterable to iterate over all the coordinates of all tiles that are in the coverage.
TLfnTransactionStatus	getTransactionStatus() Gets the status of the Tile Store's transaction management for this coverage.
Future<ALfnTileStore.ReadResult>	getUserData(String aKey, WritableByteChannel aSink, ILfnCallback<ALfnTileStore.ReadResult> aCallback) Gets binary user data from this resource with a given key.
Future<?>	importFrom(ILfnImportHandler aHandler, ReadableByteChannel aSource) Deprecated. use importFrom(java.nio.channels.ReadableByteChannel, ILfnProgressCallback) instead
Future<ALfnTileStore.WriteResult>	importFrom(ReadableByteChannel aSource, ILfnProgressCallback<ALfnTileStore.WriteResult> aCallback) Asynchronously imports this resource's data from a source channel, excluding metadata.
Future<?>	putTile(ILfnPutTileHandler aHandler, TLfnTileCoordinates aCoordinates, ReadableByteChannel aSource, ByteBuffer aMessageDigest) Deprecated. use putTile(com.luciad.fusion.core.TLfnTileCoordinates, java.nio.channels.ReadableByteChannel, java.nio.ByteBuffer, com.luciad.fusion.util.ILfnCallback) instead
Future<ALfnTileStore.WriteResult>	putTile(TLfnTileCoordinates aCoordinates, ReadableByteChannel aSource, ByteBuffer aMessageDigest, ILfnCallback<ALfnTileStore.WriteResult> aCallback) Asynchronously puts a tile into this coverage, including the tile digest.
Future<ALfnTileStore.WriteResult>	putUserData(String aKey, ReadableByteChannel aSource, ILfnCallback<ALfnTileStore.WriteResult> aCallback) Puts binary user data related in this resource with a given key.
String	toString()

Methods inherited from class com.luciad.fusion.tilestore.ALfnResource

getMetadata, getSize

Methods inherited from class java.lang.Object

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

Constructor Detail

ALfnCoverage

public ALfnCoverage()

Method Detail

putTile

public Future<ALfnTileStore.WriteResult> putTile(TLfnTileCoordinates aCoordinates,
                                                 ReadableByteChannel aSource,
                                                 ByteBuffer aMessageDigest,
                                                 ILfnCallback<ALfnTileStore.WriteResult> aCallback)

Asynchronously puts a tile into this coverage, including the tile digest. A put operation may result in a new tile having been created, an existing one having been overwritten, or failure. These cases are distinguished by different call-backs on a handler.

Parameters:

aCallback - the asynchronous callback that will be called upon success or failure. Upon success, the implementation does not guarantee that the tile has been committed to persistent storage. It does allow applications to track commitment, see ALfnTileStore.WriteResult.

aCoordinates - the coordinates defining the location of the tile within the coverage

aSource - the channel providing the tile data. Implementations will deplete the channel, but will not close it. It is up to the application to close the channel.

aMessageDigest - a byte buffer containing the message digest of the tile, or null if digests are not required by this coverage. The message digest should be computed on the contents of aData using the message digest algorithm that is specified on this coverage's metadata. Callers of this method should make sure the message digest has been written into the byte buffer at the moment the last byte has been read from aData. Correspondingly, implementations of this method should only access aMessageDigest after aData has been fully read. If the digest algorithm on the coverage metadata is null, aMessageDigest may be null or empty.

Returns:

the future of the asynchronous request

Since:

2015.0

See Also:

ILfnCallback, ALfnTileStore.WriteResult, ALfnCoverageMetadata.getMessageDigestAlgorithm()

putTile

public Future<?> putTile(ILfnPutTileHandler aHandler,
                         TLfnTileCoordinates aCoordinates,
                         ReadableByteChannel aSource,
                         ByteBuffer aMessageDigest)

Deprecated. use putTile(com.luciad.fusion.core.TLfnTileCoordinates, java.nio.channels.ReadableByteChannel, java.nio.ByteBuffer, com.luciad.fusion.util.ILfnCallback) instead

deleteTile

public Future<ALfnTileStore.WriteResult> deleteTile(TLfnTileCoordinates aCoordinates,
                                                    ILfnCallback<ALfnTileStore.WriteResult> aCallback)

Asynchronously deletes a tile from this coverage. A delete operation may result in a tile having been deleted, no tile having been deleted, or failure. These cases are distinguished by different call-backs on a handler.

Parameters:

aCallback - the asynchronous callback that will be called upon success or failure.Upon success, the implementation does not guarantee that the tile has been reliably removed from persistent storage. It does allow applications to track commitment, see ILfnDeleteTileHandler.deleted(long, long, long).

aCoordinates - the coordinates defining the location of the tile within the coverage

Returns:

the future of the asynchronous request

See Also:

ILfnCallback, ALfnTileStore.WriteResult

deleteTile

public Future<?> deleteTile(ILfnDeleteTileHandler aHandler,
                            TLfnTileCoordinates aCoordinates)

Deprecated. use deleteTile(com.luciad.fusion.core.TLfnTileCoordinates, com.luciad.fusion.util.ILfnCallback) instead

getTile

public Future<ALfnTileStore.ReadResult> getTile(TLfnTileCoordinates aCoordinates,
                                                long aModificationTime,
                                                WritableByteChannel aSink,
                                                ByteBuffer aMessageDigest,
                                                ILfnReadCallback aCallback)

Asynchronously gets a tile from this coverage, including the tile message digest. A get operation may result in a tile having been found or not, or a tile not having been modified since the specified time, or a failure. These cases are distinguished by different call-backs on a handler.

The tile data is returned in the native format and geographic reference of the coverage.

If the tile is missing, or was not modified since the specified modification time, this method will not write to the channel. The channel will never be closed.

The modification time can be used to conditionally get a tile. The tile data will only be retrieved if the current tile modification time is greater than the one specified.

This request supports cancellation through the Future. In case of cancellation before completion, the handler will not be notified. The caller should check the future first for successful completion or cancellation via Future.get().

Parameters:

aCallback - the asynchronous callback for the request

aCoordinates - the coordinates defining the location of the tile within the coverage

aModificationTime - the time after which the tile must have been modified or -1 to get the current tile, regardless of its modification time

aSink - the channel to which the tile data will be written. Implementations will not close the channel

aMessageDigest - a byte buffer to which the message digest of the tile will be written, or null. This argument can be null if you are not interested in the resulting message digest, or if the digest algorithm on the coverage metadata is null, in which case nothing will be written to it anyway. In the latter case, the buffer can be empty as well. The message digest is computed on the contents of aData using the message digest algorithm that is specified on this coverage's metadata. The message digest may be accessed from the moment ILfnGetTileHandler.found(long, long) is called on aHandler. Correspondingly, implementations should make sure aMessageDigest is filled in at the moment ILfnGetTileHandler.found(long, long) is called.

Returns:

the future of the asynchronous request

See Also:

ALfnTileStore.ReadResult, ILfnReadCallback

getTile

public Future<?> getTile(ILfnGetTileHandler aHandler,
                         TLfnTileCoordinates aCoordinates,
                         long aModificationTime,
                         WritableByteChannel aSink,
                         ByteBuffer aMessageDigest)

Deprecated. use getTile(com.luciad.fusion.core.TLfnTileCoordinates, long, java.nio.channels.WritableByteChannel, java.nio.ByteBuffer, ILfnReadCallback) instead

importFrom

public Future<ALfnTileStore.WriteResult> importFrom(ReadableByteChannel aSource,
                                                    ILfnProgressCallback<ALfnTileStore.WriteResult> aCallback)

Description copied from class: ALfnResource

Asynchronously imports this resource's data from a source channel, excluding metadata. For coverages, the resource data are the files containing the tiles (the tile containers). For assets, the resource data are the source files, relevant for asset sources in Tile Store. The source channel's content should be the result of an ALfnResource.exportTo(java.nio.channels.WritableByteChannel, com.luciad.shape.ILcdShape, com.luciad.reference.ILcdGeoReference, com.luciad.fusion.tilestore.ILfnProgressCallback<com.luciad.fusion.tilestore.ALfnTileStore.ReadResult>) operation. This operation can only be performed when this resource is empty.

An import is a write operation, but it is implemented outside of the transaction subsystem. The result is a WriteResult with code CREATED and without any transaction information. All transaction related fields are -1, and you may ignore them. Future implementations may return more useful transaction information, or even a code PUT.

The source channel will not be closed at the end of the import.

Overrides:

importFrom in class ALfnResource<ALfnCoverageMetadata>

Parameters:

aSource - the channel to import this resource from

aCallback - the callback, which may be null

Returns:

the future of the asynchronous request

importFrom

public Future<?> importFrom(ILfnImportHandler aHandler,
                            ReadableByteChannel aSource)

Deprecated. use importFrom(java.nio.channels.ReadableByteChannel, ILfnProgressCallback) instead

exportTo

public Future<ALfnTileStore.ReadResult> exportTo(WritableByteChannel aSink,
                                                 ILcdShape aAreaOfInterest,
                                                 ILcdGeoReference aAreaOfInterestGeoReference,
                                                 ILfnProgressCallback<ALfnTileStore.ReadResult> aCallback)

Description copied from class: ALfnResource

Asynchronously exports this resource's data to a channel, excluding metadata. For coverages, the resource data are the files containing the tiles (the tile containers). For assets, the resource data are the source files, relevant for asset sources in Tile Store. Progress is reported on the handler in bytes.

This request supports cancellation through the future. In case of cancellation before completion, the handler will not be notified. The caller should check the future first for successful completion or cancellation via Future.get().

An export is a read operations. The result of an import is a ReadResult with code FOUND.

The target channel will not be closed at the end of the export.

Overrides:

exportTo in class ALfnResource<ALfnCoverageMetadata>

Parameters:

aSink - the channel to export this asset to

aAreaOfInterest - an optional area of interest to limit the export to, may be null

aAreaOfInterestGeoReference - a geographic reference for the area of interest. If the area of interest is not null, then this parameter must also not be null.

aCallback - the callback, which may be null @return the future of the asynchronous request

exportTo

public Future<?> exportTo(ILfnExportHandler aHandler,
                          WritableByteChannel aSink)

Deprecated. use ALfnResource.exportTo(java.nio.channels.WritableByteChannel, ILcdShape, com.luciad.reference.ILcdGeoReference, ILfnProgressCallback) instead

getTransactionStatus

public TLfnTransactionStatus getTransactionStatus()
                                           throws IOException,
                                                  TLfnServiceException

Gets the status of the Tile Store's transaction management for this coverage.

This status can be used to track which added tiles have been committed to persistent storage.

Returns:

the status of the transactions on the Tile Store

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure

See Also:

putTile(com.luciad.fusion.core.TLfnTileCoordinates, java.nio.channels.ReadableByteChannel, java.nio.ByteBuffer, com.luciad.fusion.util.ILfnCallback<com.luciad.fusion.tilestore.ALfnTileStore.WriteResult>)

getTileCoordinates

public Iterable<TLfnTileCoordinates> getTileCoordinates()
                                                 throws IOException,
                                                        TLfnServiceException

Returns an Iterable to iterate over all the coordinates of all tiles that are in the coverage.

Note: care should be taken when calling this method. Coverages can be very large, in which case iterating over all tiles may be a costly operation.

In case an exception would occur during iteration (for example because of an I/O failure), the called method on the iterator will throw a RuntimeException (wrapping the original exception, in case of a checked exception).

This operation is currently not supported for remote coverages accessed through the LTS protocol. Only local file system coverages support the operation. Its primary use case is corruption checking on local file system Tile Stores.

Since 2013.0, the iterable no longer throws ConcurrentModificationExceptions. It is possible to keep on iterating over the tile coordinates even while write operations are still ongoing. As a result, the tile coordinates returned by the iteration may return stale values. It may "miss" recently added tiles, and it may still return recently deleted tiles. When no write operations have happened since the creation of the iterable, it is still safe to assume that the iteration returns the complete set (and nothing but the complete set) of tile coordinates.

Returns:

an Iterable to iterate over all tiles that are available in the coverage.

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure

Since:

2012.0

putUserData

public Future<ALfnTileStore.WriteResult> putUserData(String aKey,
                                                     ReadableByteChannel aSource,
                                                     ILfnCallback<ALfnTileStore.WriteResult> aCallback)

Description copied from class: ALfnResource

Puts binary user data related in this resource with a given key. User data is opaque binary data, and is used internally to store checkpoints and replication settings.

The user data is read from the given channel. If user data with the given key already exists, it is overwritten and this call returns true.

The user data key is an arbitrary string, but you are encouraged to use a java-like hierarchical naming scheme, for example "com.luciad.fusion.yourUniqueKey".

This operation is asynchronous. Callers can use the returned Future to wait for the result, or use a handler to be notified of the result.

This operation is optional. Use TLfnTileStoreOperation.isUserDataSupported(com.luciad.fusion.tilestore.TLfnTileStoreCapabilities) to check if this operation is supported.

Overrides:

putUserData in class ALfnResource<ALfnCoverageMetadata>

Parameters:

aKey - A key associated with the user data.

aSource - The input channel the user data is read from.

aCallback - A callback that will be invoked when the operation is finished. May be null.

Returns:

A future, with result code ALfnTileStore.Result.Code.PUT if data with the given key already existed, ALfnTileStore.Result.Code.CREATED if it is new.

Since:

2013.0

getUserData

public Future<ALfnTileStore.ReadResult> getUserData(String aKey,
                                                    WritableByteChannel aSink,
                                                    ILfnCallback<ALfnTileStore.ReadResult> aCallback)

Description copied from class: ALfnResource

Gets binary user data from this resource with a given key.

The user data is written to the given channel, if it exists.

The user data key is an arbitrary string, but you are encouraged to use a java-like hierarchical naming scheme, for example "com.luciad.fusion.youruniquekey".

This operation is asynchronous. Callers can use the returned Future to wait for the result, or use a handler to be notified of the result.

This operation is optional. Use TLfnTileStoreOperation.isUserDataSupported(com.luciad.fusion.tilestore.TLfnTileStoreCapabilities) to check if this operation is supported.

Overrides:

getUserData in class ALfnResource<ALfnCoverageMetadata>

Parameters:

aKey - A key associated with the user data.

aSink - The output channel the data is written to, if it exists.

aCallback - A callback that will be invoked when the operation is finished. May be null.

Returns:

A future, with result code ALfnTileStore.ReadResult.FOUND if data with the given key exists, ALfnTileStore.Result.Code.NOT_FOUND otherwise.

Since:

2013.0

deleteUserData

public Future<ALfnTileStore.WriteResult> deleteUserData(String aKey,
                                                        ILfnCallback<ALfnTileStore.WriteResult> aCallback)

Description copied from class: ALfnResource

Deletes binary user data from this resource with a given key.

The user data key is an arbitrary string, but you should use a java-like hierarchical naming scheme.

This operation is asynchronous. Callers can use the returned Future to wait for the result, or use a handler to be notified of the result.

This operation is optional. User TLfnTileStoreOperation.isUserDataSupported(com.luciad.fusion.tilestore.TLfnTileStoreCapabilities) to check if this operation is supported.

Overrides:

deleteUserData in class ALfnResource<ALfnCoverageMetadata>

Parameters:

aKey - A key associated with the user data.

aCallback - A callback that will be invoked when the operation is finished. May be null.

Returns:

A future, with result code ALfnTileStore.WriteResult.DELETED if data existed, ALfnTileStore.Result.Code.NOT_FOUND otherwise.

Since:

2013.0

toString

public String toString()

Overrides:

toString in class Object