Package com.luciad.fusion.tilestore

Class ALfnTileStore

java.lang.Object

com.luciad.fusion.tilestore.ALfnTileStore

All Implemented Interfaces:

ILfnResourceMetadataResolver, Closeable, AutoCloseable

Direct Known Subclasses:

ALfnTileStoreWrapper, TLfnFileSystemTileStore

public abstract class ALfnTileStore
extends Object
implements ILfnResourceMetadataResolver, Closeable

The main entry point for accessing a LuciadFusion Tile Store. The Tile Store provides:

• query of resource metadata
• add/put (put) of resource metadata
• delete of resources
• access to coverages, which provide functionality to handle individual tiles
• capabilities providing the Tile Store metadata and the supported operations (defined as constants in TLfnTileStoreOperation)

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

The Tile Store can be accessed via a LTS client or it can be directly accessed on the file system.

Implementations of this class are thread-safe.

Since:

10.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	ALfnTileStore.CommitPolicy	The commit policy determines when new tiles will be visible.
static final class	ALfnTileStore.ReadResult	The final result of a read operation ("get").
static class	ALfnTileStore.Result	The result of an operation on a Tile Store.
static final class	ALfnTileStore.WriteResult	The final result of a write operation ("put", "delete").

Constructor Summary

Constructors

Constructor	Description
ALfnTileStore()

Method Summary

Modifier and Type	Method	Description
void	close()	Closes this Tile Store instance.
boolean	deleteResource(String aID)	Deletes both the data and metadata of a resource.
Future<ALfnTileStore.WriteResult>	deleteUserData(String aKey, ILfnCallback<ALfnTileStore.WriteResult> aCallback)	Deletes binary user data from this Tile Store with a given key.
ALfnAsset	getAsset(String aID)	Gets an asset from the Tile Store.
abstract TLfnTileStoreCapabilities	getCapabilities()	Gets the capabilities offered by the Tile Store.
ALfnCoverage	getCoverage(String aID)	Gets a coverage from the Tile Store.
List<String>	getCoverageIds()	Gets the IDs of all this Tile Store's coverage metadatas.
TLfnTileStoreMetadata	getMetadata()	Returns the metadata of this Tile Store.
TLfnRasterAssetMetadata	getRasterAssetMetadata(String aID)	Gets a raster asset metadata.
TLfnRasterCoverageMetadata	getRasterCoverageMetadata(String aID)	Gets a raster coverage metadata.
<T extends ALfnResourceMetadata> T	getResourceMetadata(String aID)	Gets the metadata of a resource.
ALfnTheme	getTheme(String aID)	Gets a theme from the Tile Store.
TLfnThemeMetadata	getThemeMetadata(String aID)	Gets the metadata of a theme.
abstract URI	getURI()	Gets URI identifier of this Tile Store.
Future<ALfnTileStore.ReadResult>	getUserData(String aKey, WritableByteChannel aSink, ILfnCallback<ALfnTileStore.ReadResult> aCallback)	Gets binary user data from this Tile Store with a given key.
TLfnVectorAssetMetadata	getVectorAssetMetadata(String aID)	Gets a vector asset metadata.
TLfnVectorCoverageMetadata	getVectorCoverageMetadata(String aID)	Gets a vector coverage metadata.
abstract void	putMetadata(TLfnTileStoreMetadata aTileStoreMetadata)	Updates the metadata of this Tile Store.
TLfnRasterAssetMetadata	putRasterAssetMetadata(TLfnRasterAssetMetadata aMetadata)	Adds or updates an asset.
TLfnRasterCoverageMetadata	putRasterCoverageMetadata(TLfnRasterCoverageMetadata aMetadata)	Adds or updates a coverage.
<T extends ALfnResourceMetadata> T	putResourceMetadata(T aMetadata)	Adds or updates the metadata of a resource.
TLfnThemeMetadata	putThemeMetadata(TLfnThemeMetadata aMetadata)	Adds or updates a theme metadata.
Future<ALfnTileStore.WriteResult>	putUserData(String aKey, ReadableByteChannel aSource, ILfnCallback<ALfnTileStore.WriteResult> aCallback)	Puts binary user data in this Tile Store with a given key.
TLfnVectorAssetMetadata	putVectorAssetMetadata(TLfnVectorAssetMetadata aMetadata)	Adds or updates an asset.
TLfnVectorCoverageMetadata	putVectorCoverageMetadata(TLfnVectorCoverageMetadata aMetadata)	Adds or updates a coverage.
<R extends ALfnResourceMetadata> List<R>	query(ELfnResourceType aResourceType)	Gets all the resource metadatas in this Tile Store of a given type.
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.

Methods inherited from class java.lang.Object

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

Constructor Details

ALfnTileStore

public ALfnTileStore()

Method Details

getURI

public abstract URI getURI()

Gets URI identifier of this Tile Store.

Returns:

the URI

getCapabilities

public abstract TLfnTileStoreCapabilities getCapabilities()
                                                   throws IOException,
TLfnServiceException

Gets the capabilities offered by the Tile Store.

The capabilities provide the Tile Store metadata and the supported operations. The operations are defined as constants on this class.

Returns:

the Tile Store capabilities

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure

getMetadata

public TLfnTileStoreMetadata getMetadata()
                                  throws IOException,
TLfnServiceException

Returns the metadata of this Tile Store.

Short for

     getCapabilities().getMetadata()
   

Returns:

the Tile Store metadata

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure

Since:

2015.0

putMetadata

public abstract void putMetadata(TLfnTileStoreMetadata aTileStoreMetadata)
                          throws IOException,
TLfnServiceException

Updates the metadata of this Tile Store.

Parameters:

aTileStoreMetadata - The new metadata for this Tile Store

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure

Since:

2015.0

getCoverage

public ALfnCoverage getCoverage(String aID)
                         throws IOException,
TLfnServiceException

Gets a coverage from the Tile Store. Coverage IDs can be found using either:

• getCoverageIds()
• query(ILfnQueryHandler, TLfnQuery) and get the ID from the metadata

Parameters:

aID - the ID of the desired coverage

Returns:

the coverage or null if it does not exist

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure

See Also:

• ALfnCoverage

getAsset

public ALfnAsset getAsset(String aID)
                   throws IOException,
TLfnServiceException

Gets an asset from the Tile Store. Asset IDs can be found using either:

• query(ELfnResourceType.ASSET) and get the ID from the metadata
• query(ILfnQueryHandler, TLfnQuery) and get the ID from the metadata

Parameters:

aID - the ID of the desired asset

Returns:

the asset or null if it does not exist

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure

Since:

2013.1

getTheme

public ALfnTheme getTheme(String aID)
                   throws IOException,
TLfnServiceException

Gets a theme from the Tile Store. Theme IDs can be found using either:

• query(ELfnResourceType.THEME) and get the ID from the metadata
• query(ILfnQueryHandler, TLfnQuery) and get the ID from the metadata

Parameters:

aID - the ID of the desired theme

Returns:

the theme, or null if it does not exist

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure

getResourceMetadata

public <T extends ALfnResourceMetadata> T getResourceMetadata(String aID)
                                                       throws IOException,
TLfnServiceException

Gets the metadata of a resource.

This implementation throws UnsupportedOperationException. Subclasses should override it to do something useful.

Specified by:

getResourceMetadata in interface ILfnResourceMetadataResolver

Parameters:

aID - the ID of the desired resource

Returns:

the resource corresponding to the given ID, or null if it does not exist

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure

putResourceMetadata

public <T extends ALfnResourceMetadata> T putResourceMetadata(T aMetadata)
                                                       throws IOException,
TLfnServiceException

Adds or updates the metadata of a resource.

The put sequence is verified:

• addition of a new resource will fail if a resource with the same ID already exists;
• put of an existing resource will fail if the version of the updated metadata does not match the metadata on the LuciadFusion service.

In addition, the writability of the service is also verified. In these cases, a TLfnServiceException exception will be thrown.

This implementation throws UnsupportedOperationException. Subclasses should override it to do something useful.

Parameters:

aMetadata - the metadata describing the resource to be put

Returns:

the resource metadata with the new put sequence

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure or conflict

getThemeMetadata

public TLfnThemeMetadata getThemeMetadata(String aID)
                                   throws IOException,
TLfnServiceException

Gets the metadata of a theme. This implementation delegates to getResourceMetadata(String), which is suitable for most subclasses.

Parameters:

aID - the ID of the desired theme

Returns:

the theme corresponding to the given ID, or null if it does not exist

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure

putThemeMetadata

public TLfnThemeMetadata putThemeMetadata(TLfnThemeMetadata aMetadata)
                                   throws IOException,
TLfnServiceException

Adds or updates a theme metadata.

The put sequence is verified:

• addition of a new theme will fail if a theme with the same ID already exists;
• put of an existing theme will fail if the version of the updated metadata does not match the metadata on the LuciadFusion service.

In addition, the writability of the service is also verified. In these cases, a TLfnServiceException exception will be thrown.

This implementation delegates to putResourceMetadata(com.luciad.fusion.tilestore.metadata.ALfnResourceMetadata), which is suitable for most subclasses.

Parameters:

aMetadata - the metadata describing the theme to be put

Returns:

the metadata with the new put sequence

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure or conflict

getRasterCoverageMetadata

public TLfnRasterCoverageMetadata getRasterCoverageMetadata(String aID)
                                                     throws IOException,
TLfnServiceException

Gets a raster coverage metadata. This implementation delegates to getResourceMetadata(String), which is suitable for most subclasses.

Parameters:

aID - the ID of the desired raster coverage

Returns:

the raster coverage corresponding to the given ID, or null if it does not exist

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure

putRasterCoverageMetadata

public TLfnRasterCoverageMetadata putRasterCoverageMetadata(TLfnRasterCoverageMetadata aMetadata)
                                                     throws IOException,
TLfnServiceException

Adds or updates a coverage.

The put sequence is verified:

• addition of a new coverage will fail if a coverage with the same ID already exists
• put of an existing coverage will fail if the version of the updated metadata does not match the metadata on the LuciadFusion service.

In these cases, an exception will be thrown with code TLfnServiceException

This implementation delegates to putResourceMetadata(com.luciad.fusion.tilestore.metadata.ALfnResourceMetadata), which is suitable for most subclasses.

Parameters:

aMetadata - the metadata describing the coverage to be put

Returns:

the metadata with the new put sequence

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure

getVectorCoverageMetadata

public TLfnVectorCoverageMetadata getVectorCoverageMetadata(String aID)
                                                     throws IOException,
TLfnServiceException

Gets a vector coverage metadata. This implementation delegates to getResourceMetadata(String), which is suitable for most subclasses.

Parameters:

aID - the ID of the vector coverage

Returns:

the vector coverage corresponding to the given ID, or null if it does not exist

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure

Since:

11.0

putVectorCoverageMetadata

public TLfnVectorCoverageMetadata putVectorCoverageMetadata(TLfnVectorCoverageMetadata aMetadata)
                                                     throws IOException,
TLfnServiceException

Adds or updates a coverage.

The put sequence is verified:

• addition of a new coverage will fail if a coverage with the same ID already exists
• put of an existing coverage will fail if the version of the updated metadata does not match the metadata on the LuciadFusion service.

In these cases, an exception will be thrown with code TLfnServiceException

This implementation delegates to putResourceMetadata(com.luciad.fusion.tilestore.metadata.ALfnResourceMetadata), which is suitable for most subclasses.

Parameters:

aMetadata - the metadata describing the coverage to be put

Returns:

the metadata with the new put sequence

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure

Since:

11.0

getRasterAssetMetadata

public TLfnRasterAssetMetadata getRasterAssetMetadata(String aID)
                                               throws IOException,
TLfnServiceException

Gets a raster asset metadata. This implementation delegates to getResourceMetadata(String), which is suitable for most subclasses.

Parameters:

aID - the ID of the desired raster asset

Returns:

the raster asset corresponding to the given ID, or null if it does not exist

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure

putRasterAssetMetadata

public TLfnRasterAssetMetadata putRasterAssetMetadata(TLfnRasterAssetMetadata aMetadata)
                                               throws IOException,
TLfnServiceException

Adds or updates an asset.

The put sequence is verified:

• addition of a new asset will fail if an asset with the same ID already exists
• put of an existing asset will fail if the version of the updated metadata does not match the metadata on the LuciadFusion service.

In these cases, an exception will be thrown with code TLfnServiceException.

This implementation delegates to putResourceMetadata(com.luciad.fusion.tilestore.metadata.ALfnResourceMetadata), which is suitable for most subclasses.

Parameters:

aMetadata - the metadata describing the asset to be put

Returns:

the metadata with the new put sequence

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure

getVectorAssetMetadata

public TLfnVectorAssetMetadata getVectorAssetMetadata(String aID)
                                               throws IOException,
TLfnServiceException

Gets a vector asset metadata. This implementation delegates to getResourceMetadata(String), which is suitable for most subclasses.

Parameters:

aID - the ID of the desired vector asset

Returns:

the vector asset corresponding to the given ID, or null if it does not exist

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure

Since:

11.0

putVectorAssetMetadata

public TLfnVectorAssetMetadata putVectorAssetMetadata(TLfnVectorAssetMetadata aMetadata)
                                               throws IOException,
TLfnServiceException

Adds or updates an asset.

The put sequence is verified:

• addition of a new asset will fail if an asset with the same ID already exists
• put of an existing asset will fail if the version of the updated metadata does not match the metadata on the LuciadFusion service.

In these cases, an exception will be thrown with code TLfnServiceException.

This implementation delegates to putResourceMetadata(com.luciad.fusion.tilestore.metadata.ALfnResourceMetadata), which is suitable for most subclasses.

Parameters:

aMetadata - the metadata describing the asset to be put

Returns:

the metadata with the new put sequence

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure

Since:

11.0

deleteResource

public boolean deleteResource(String aID)
                       throws IOException,
TLfnServiceException

Deletes both the data and metadata of a resource. As soon as this method returns, the resource can be considered deleted for all practical purposes. Note however that space reclamation may or may not be immediate, since it is taken care of by a background process.

Parameters:

aID - the ID of a resource to be deleted

Returns:

true if the resource has been deleted, false if the resource does not exist

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure

query

public Future<?> query(ILfnQueryHandler aHandler,
 TLfnQuery aQuery)

Queries the Tile Store for resources' metadata. The query returns the metadata of resources that match a given filter and type. Even though the API is asynchronous, implementations may be synchronous or asynchronous. The default implementations are in fact synchronous, but that is an implementation detail which may change at any time.

Parameters:

aHandler - the handler for the results

aQuery - the query to be performed

Returns:

the future of the request, which could be asynchronous

getCoverageIds

public List<String> getCoverageIds()

Gets the IDs of all this Tile Store's coverage metadatas. This is a blocking call. It is a convenience method for the asynchronous query(ILfnQueryHandler, TLfnQuery). Any checked exceptions on the asynchronous handler will be wrapped in a RuntimeException.

Returns:

the IDs of all this Tile Store's coverages, possibly empty but never null

Since:

2013.1

query

public <R extends ALfnResourceMetadata> List<R> query(ELfnResourceType aResourceType)

Gets all the resource metadatas in this Tile Store of a given type. This is a blocking call. It is a convenience method for the asynchronous query(ILfnQueryHandler, TLfnQuery). Any checked exceptions on the asynchronous handler will be wrapped in a RuntimeException.

Type Parameters:

R - the expected resource type, which must not be null

Parameters:

aResourceType -

Returns:

all this Tile Store's resource metadatas matching the specified type, possibly empty but never null

Since:

2014.0

putUserData

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

Puts binary user data in this Tile Store 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.

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.WriteResult.PUT if data with the given key already existed, ALfnTileStore.WriteResult.CREATED if it is new.

Since:

2015.0

getUserData

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

Gets binary user data from this Tile Store 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.

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 value ALfnTileStore.ReadResult.FOUND if data with the given key exists, ALfnTileStore.Result.Code.NOT_FOUND otherwise.

Since:

2015.0

deleteUserData

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

Deletes binary user data from this Tile Store 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.

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 value ALfnTileStore.WriteResult.DELETED if data existed, ALfnTileStore.WriteResult.NOT_FOUND otherwise.

Since:

2015.0

toString

public String toString()

Returns the URI as a string representation of this Tile Store.

Overrides:

toString in class Object

Returns:

the URI as a string representation of this Tile Store

close

public void close()
           throws IOException

Closes this Tile Store instance. This method does nothing, but subclasses may override it to do something useful.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException - in case of an I/O failure