com.luciad.fusion.engine

LuciadFusionClass ALfnEngineEnvironment

java.lang.Object

com.luciad.fusion.engine.ALfnEngineEnvironment

public abstract class ALfnEngineEnvironment
extends Object

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

The engine environment also provides configuration of the execution environment. The following configurations are provided:

• data formats, via registration on the environment's composite format
• directory for storing engine checkpoint files
• default tile sizes per data type
• model reference decoder

The environment also provides support for custom data formats:

• registration on the composite format
• a model reference decoder is provided, to determine the model reference
• custom data formats that allow the configuration of the data model name should support the data model name property for creating model decoders that produce models with a provided data model name
• for optimal processing during fusion, custom data formats should support the buffer property and input stream factory property for creating model decoders

Since:

10.0

See Also:

newInstance(ALfnEnvironment), newInstance(ALfnEnvironment, Supplier)

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
abstract void	close() Closes this environment and releases all its resources.
abstract File	getCheckpointDirectory() Deprecated. This setting is not used anymore. Fusion engine checkpoints are now stored in the coverage user data on the Tile Store. Using null to disable checkpoints is still valid, but instead you should set the checkpoint interval to -1 (you can set it on the session builders for raster or vector data).
abstract TLfnCompositeFormat	getCompositeFormat() Returns the composite format that is used by the engine session to decode the source assets.
abstract int	getDefaultTileSize(ELfnDataType aDataType) Gets the default tile size for a data type.
abstract int	getEngineThreadCount() Gets the number of threads used by an engine.
abstract ALfnEnvironment	getEnvironment() Returns the core environment.
ALcdImagingEngine	getImagingEngine() Gets the imaging engine for the environment, which may be null to indicate that fusion should use the default imaging engine.
abstract ILcdModelReferenceDecoder	getModelReferenceDecoder() Gets the model reference decoder.
abstract File	getS63PermitDirectory() Gets the directory containing all the S-63 permits.
static ALfnEngineEnvironment	newInstance(ALfnEnvironment aEnvironment) Creates a new engine environment that uses the default supported formats.
static ALfnEngineEnvironment	newInstance(ALfnEnvironment aEnvironment, Supplier<List<ALfnFormat>> aFormatSupplier) Creates a new engine environment that uses the given supported formats.
abstract void	setCheckpointDirectory(File aCheckpointDirectory) Deprecated. This setting is not used anymore. Fusion engine checkpoints are now stored in the coverage user data on the Tile Store. Using null to disable checkpoints is still valid, but instead you should set the checkpoint interval to -1 (you can set it on the session builders for raster or vector data).
abstract void	setDefaultTileSize(ELfnDataType aDataType, int aTileSize) Sets the default tile size for a data type.
abstract void	setEngineThreadCount(int aThreadCount) Sets the thread count for engines.
abstract void	setModelReferenceDecoder(ILcdModelReferenceDecoder aModelReferenceDecoder) Sets a model reference decoder.
abstract void	setS63PermitDirectory(File aDir) Sets the S-63 permit directory on this engine environment.

Methods inherited from class java.lang.Object

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

Constructor Detail

ALfnEngineEnvironment

protected ALfnEngineEnvironment()

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

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

Method Detail

newInstance

public static ALfnEngineEnvironment newInstance(ALfnEnvironment aEnvironment)

Creates a new engine environment that uses the default supported formats. A single engine environment should be created. The environment should be closed when no longer in use.

Parameters:

aEnvironment - the core environment.

newInstance

public static ALfnEngineEnvironment newInstance(ALfnEnvironment aEnvironment,
                                                Supplier<List<ALfnFormat>> aFormatSupplier)

Creates a new engine environment that uses the given supported formats. A single engine environment should be created. The environment should be closed when no longer in use.

Parameters:

aEnvironment - the core environment.

aFormatSupplier - the supplier of formats to decode the source assets

Since:

2023.1

getEnvironment

public abstract ALfnEnvironment getEnvironment()

Returns the core environment.

Returns:

the core environment used by this engine environment.

getCompositeFormat

public abstract TLfnCompositeFormat getCompositeFormat()

Returns the composite format that is used by the engine session to decode the source assets. It defines which types of source assets are supported by the fusion engine.

The format initially has all the supported formats defined by ALfnFormat.createDefaultFormats(ALfnEngineEnvironment) when the environment is created with newInstance(ALfnEnvironment), or newInstance(ALfnEnvironment, Supplier) when the supplier is null. If the supplier is not null the format initially has all the formats provided through the supplier. formats can be removed and additional ones registered. These formats and can be used for registering formats that need to be processed by the fusion engine.

Returns:

the composite format

getModelReferenceDecoder

public abstract ILcdModelReferenceDecoder getModelReferenceDecoder()

Gets the model reference decoder. The default decoder supports WKT, EPSG, RPC and Luciad reference files. The model reference decoder is used by the formats for decoding data.

Returns:

the model reference decoder

setModelReferenceDecoder

public abstract void setModelReferenceDecoder(ILcdModelReferenceDecoder aModelReferenceDecoder)

Sets a model reference decoder.

Parameters:

aModelReferenceDecoder - a model reference decoder

See Also:

getModelReferenceDecoder()

getCheckpointDirectory

public abstract File getCheckpointDirectory()

Deprecated. This setting is not used anymore. Fusion engine checkpoints are now stored in the coverage user data on the Tile Store. Using null to disable checkpoints is still valid, but instead you should set the checkpoint interval to -1 (you can set it on the session builders for raster or vector data).

Gets the directory where the engine checkpoints are stored. By default, a location within the user's home directory is used. This directory will be used by the engine.

The checkpoint directory may be null,

Returns:

the checkpoint directory, possibly null

setCheckpointDirectory

public abstract void setCheckpointDirectory(File aCheckpointDirectory)

Deprecated. This setting is not used anymore. Fusion engine checkpoints are now stored in the coverage user data on the Tile Store. Using null to disable checkpoints is still valid, but instead you should set the checkpoint interval to -1 (you can set it on the session builders for raster or vector data).

Sets the checkpoint directory. The directory does not need to exist, and may even be null.

When the directory is null, the saving of checkpoints is disabled. There are configurations where this is may be required, depending on three settings:

1. Saving checkpoints enabled or disabled
2. Commit policy PER_TILE or PER_COVERAGE (see ALfnTileStore.CommitPolicy)
3. Produce tiles at all levels or not (see TLfnRasterCoverageMetadata.Builder.levelsToProduce(int[]))

Currently, not all combinations of these three settings are supported. The limitations are:

• Saving checkpoints enabled + commit policy PER_COVERAGE commit policy → all levels must be produced. This is currently only supported for raster sessions. Vector sessions always combine all except the most detailed level.
• Saving checkpoints enabled + not all levels are produced → commit policy must be PER_TILE.
• Commit policy PER_COVERAGE + not all levels produced → saving of checkpoints must be disabled.

If saving of checkpoints is enabled while the Tile Store has a per-coverage commit policy and not all levels are set to be produced, fusion may either fail when attempting to resume from checkpoint, or resume using old versions of a tile.

Parameters:

aCheckpointDirectory - the new directory for storing checkpoints

See Also:

getCheckpointDirectory()

getEngineThreadCount

public abstract int getEngineThreadCount()

Gets the number of threads used by an engine. The default thread count is the number of available processors.

Returns:

the thread count

setEngineThreadCount

public abstract void setEngineThreadCount(int aThreadCount)

Sets the thread count for engines.

Parameters:

aThreadCount - the new thread count

See Also:

getEngineThreadCount()

getDefaultTileSize

public abstract int getDefaultTileSize(ELfnDataType aDataType)

Gets the default tile size for a data type.

The standard tile sizes are 256 for image and 64 for elevation.

Parameters:

aDataType - the data type

Returns:

the tile size

See Also:

TLfnRasterCoverageMetadata.getTileWidth(), TLfnRasterCoverageMetadata.getTileHeight()

setDefaultTileSize

public abstract void setDefaultTileSize(ELfnDataType aDataType,
                                        int aTileSize)

Sets the default tile size for a data type.

Parameters:

aDataType - the data type

aTileSize - the tile size

See Also:

getDefaultTileSize(com.luciad.fusion.tilestore.ELfnDataType)

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.

Note that this does not close the core environment.

If not closed explicitly, the client 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 client environment being closed at a specific point in time, you should explicitly close it.

Closing the client 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

getS63PermitDirectory

public abstract File getS63PermitDirectory()

Gets the directory containing all the S-63 permits. The default is "<user.home>/.luciadfusion/Permits/S-63".

Since:

2015.0

setS63PermitDirectory

public abstract void setS63PermitDirectory(File aDir)

Sets the S-63 permit directory on this engine environment. This directory must be an ancestor of the directory containing all the S-63 permits for all the S-63 data. You can also set it using the system property "com.luciad.fusion.engine.s63PermitDirectory".

• This method has priority over the the system property.
• The system property has priority over the default.
• The default is "<user.home>/.luciadfusion/Permits/S-63".

Setting the S-63 permit directory is a configuration action. All configuration actions must be done before the engine environment is used. If you call this method, you must do so before calling getCompositeFormat(), otherwise an IllegalStateException will be thrown.

Parameters:

aDir - The S-63 permit directory, or null to clear the override and fall back to the system property or the default.

Throws:

IllegalStateException - If you call this method after you've already started using this engine environment.

Since:

2015.0

getImagingEngine

public ALcdImagingEngine getImagingEngine()

Gets the imaging engine for the environment, which may be null to indicate that fusion should use the default imaging engine.

Returns:

the imaging engine for the environment, which may be null

Since:

2016.0