com.luciad.fusion.core

LuciadLightspeedClass ALfnEnvironment

java.lang.Object

com.luciad.fusion.core.ALfnEnvironment

public abstract class ALfnEnvironment
extends Object

An opaque handle to the execution environment for LuciadFusion. The environment provides the shared context for LuciadFusion functionality. The environment handle will be interpreted by LuciadFusion and should be closed by the application once all LuciadFusion processing is finished.

Since:

10.0

See Also:

newInstance()

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ALfnEnvironment() Deprecated. Do not use this constructor. You are not supposed to create subclasses of this class. Use the newInstance() method instead.

Method Summary

Modifier and Type	Method and Description
abstract void	addPathPrefix(String aName, String aPathPrefix) Adds a path prefix which maps a symbolic name onto a path prefix and vice versa.
abstract void	addTileDataCodec(ILcdEarthTileDataCodec aCodec, ELfnDataType aDataType) Adds (registers) a codec.
abstract void	close() Closes this environment and releases all its resources.
abstract void	configureDataModel(TLcdDataModel aDataModel) Configures an additional data model on the XML encoder and decoder.
abstract int	getCallbackThreadCount() Gets the number of pooled threads to handle asynchronous callbacks from a Tile Store.
abstract Map<String,String>	getPathPrefixes() Gets an unmodifiable snapshot of the path prefixes.
abstract Collection<ILcdEarthTileDataCodec>	getTileDataCodecs(ELfnDataType aDataType) Gets the registered tile data codecs.
static ALfnEnvironment	newInstance() Creates a new environment.
abstract boolean	removePathPrefixes(String... aNames) Removes the path prefix for the given symbolic name(s).
abstract boolean	removeTileDataCodec(ILcdEarthTileDataCodec aCodec, ELfnDataType aDataType) Removes a tile data codec.
abstract void	setCallbackThreadCount(int aThreadCount) Sets the number of pooled threads to handle asynchronous callbacks from a Tile Store.

Methods inherited from class java.lang.Object

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

Constructor Detail

ALfnEnvironment

protected ALfnEnvironment()

Deprecated. Do not use this constructor. You are not supposed to create subclasses of this class. Use the newInstance() method instead.

Do not use this constructor. You are not supposed to create subclasses of this class. Use the newInstance() method instead.

Method Detail

newInstance

public static ALfnEnvironment newInstance()

Creates a new environment. A single environment should be created and used for all LuciadFusion functionality (client, server, fusion engine). The environment should be closed when no longer in use.

configureDataModel

public abstract void configureDataModel(TLcdDataModel aDataModel)

Configures an additional data model on the XML encoder and decoder. The additional model can support a custom XML schema, for instance an extension schema for ISO 19115 metadata.

Parameters:

aDataModel - a data model to be added

addTileDataCodec

public abstract void addTileDataCodec(ILcdEarthTileDataCodec aCodec,
                                      ELfnDataType aDataType)

Adds (registers) a codec.

The tile data codec can be used when encoding or decoding supported tile data of the specified type. The data type should be null if it is not relevant.

The encoded format of the specified codec must have a MIME type as format name, f.i. image/jpeg, and no format class.

Parameters:

aCodec - the codec to be added

aDataType - the data type

removeTileDataCodec

public abstract boolean removeTileDataCodec(ILcdEarthTileDataCodec aCodec,
                                            ELfnDataType aDataType)

Removes a tile data codec.

Parameters:

aCodec - the codec to be removed

aDataType - the data type or null if it is not relevant

Returns:

true if a codec was removed, false otherwise

getTileDataCodecs

public abstract Collection<ILcdEarthTileDataCodec> getTileDataCodecs(ELfnDataType aDataType)

Gets the registered tile data codecs.

By default the environment has the following codecs:

Data Type	MIME type	Comments
IMAGE	image/jpeg	Supports transparency
IMAGE	image/png	Supports transparency
ELEVATION	image/png	16 bit precision, limited support for decimal values
ELEVATION	image/tiff	Supports decimal values with 32 bits float precision

Parameters:

aDataType - the data type or null if it is not relevant

Returns:

an unmodifiable collection of codecs.

close

public abstract void close()
                    throws IOException,
                           InterruptedException

Closes this environment and releases all its resources. The resources may include caches, thread pools, file system coverages, etc. This call may block if resources are still in use.

If not closed explicitly, the environment will automatically be closed on finalize(). This may happen at an undetermined time in the future, if at all. If you have time-dependent code that relies on the environment being closed at a specific point in time, you should explicitly close it.

Closing the environment multiple times does not throw and has the same effect as closing it once.

Throws:

IOException - in case of an I/O failure

InterruptedException - when the closing is interrupted

getCallbackThreadCount

public abstract int getCallbackThreadCount()

Gets the number of pooled threads to handle asynchronous callbacks from a Tile Store. These threads will be shared among all models decoded with a Tile Store model decoder. For example results of GetTile operations will be handled by these threads.

These threads are named Callback-i/n where i is their index in the pool (offset by 1) and n is the pool size. When your application is slow and you see that the callback threads are fully loaded, it may be a good idea to increase their number.

The default callback thread count is 4.

Returns:

the callback thread count

Since:

2012.0

setCallbackThreadCount

public abstract void setCallbackThreadCount(int aThreadCount)

Sets the number of pooled threads to handle asynchronous callbacks from a Tile Store.

Parameters:

aThreadCount - the new thread count

Since:

2012.0

See Also:

getCallbackThreadCount()

addPathPrefix

public abstract void addPathPrefix(String aName,
                                   String aPathPrefix)

Adds a path prefix which maps a symbolic name onto a path prefix and vice versa. When either the name or the path prefix is null, a warning will be logged and it will not have been added. The mapping of path prefixes is bidirectional, so both the name and the path prefix must be unique. When a duplicate name or path prefix is added, it will be replaced.

Path prefixes are internally converted to their canonical forms. Uniqueness of path prefixes is based on their canonical form. This means for example that a path prefix "T:" is the same as "/T:".

If the file for the path prefix does not exist, a warning will be logged.

Examples of supported path prefixes:

• Windows style network paths such as "pathPrefix"="\\SERVER\Data"
• Windows style paths with drive letters such as "path.prefix"="X:\Data"
• Unix style paths such as "anyString"="/mnt/server/data/"

Parameters:

aName - a symbolic name to replace the path prefix with, for example "my.data". If null, the path prefix will be ignored and everything will behave as if the path prefix was never added.

aPathPrefix - a path prefix, denoting the local path, for example "//my/data". If null, the path prefix will be ignored and everything will behave as if the path

Since:

2013.0

removePathPrefixes

public abstract boolean removePathPrefixes(String... aNames)

Removes the path prefix for the given symbolic name(s). If one of the given names is null, a warning will be logged and it will not have been removed.

Removing a path prefix does not unset any system properties.

Parameters:

aNames - the symbolic names for which to remote the path prefix(es). May be empty but never null.

Returns:

true if at least one path prefix substitution actually existed, false otherwise

Since:

2013.0

getPathPrefixes

public abstract Map<String,String> getPathPrefixes()

Gets an unmodifiable snapshot of the path prefixes. The path prefixes are a mapping of symbolic names onto path prefixes, and vice versa. This mapping is bidirectional. This means that both names and path prefixes are unique.

Path prefixes are necessary for remote fusion, when the mount points of the source data are different on client and engine server. Both the client and the engine server need access to the same source data. Because they run on different systems, the mount points of the source data may be different. In that case, you need to define a common symbolic name on each system, which maps onto a path prefix which is different on each system.

Consider for example the use case of a remote engine server on Linux, and a client application on Windows. The client application wants to fuse an input file "X:/my/input/data/imagery.tif". On the server, the path to the input file is "/mnt/my/input/data/imagery.tif". In order to make this work, path prefix substitutions need to be defined on both client and server. For example, on the client this could be "my.input.data" → "/X:/my/input/data", while on the server it is "my.input.data" → "/smb/my/input/data". The name needs to be same on client and server, the value is specific for each. This substitution happens transparently to the user. On the wire, substituted paths will look like "${my.input.data}/imagery.tif".

By default, the map contains the path prefixes defined by system properties starting with "luciad.fusion.path.prefix". For example, defining a system property "luciad.fusion.path.prefix.my.input.data=/mnt/my/input/data" is equivalent to setting a path prefix with name "my.input.data" and path prefix "/mnt/my/input/data".

Returns:

an unmodifiable snapshot of the path prefix substitutions, possibly empty but never null

Since:

2013.0