public abstract class ALfnEngine extends Object
This class represents the engine of LuciadFusion, which is responsible for processing (=fusing) the source data so it can be served later on to clients.
An engine instance is created for a specific coverage in a tile store. Once you have the engine, you
can start the fusion process by calling the fuse
method. The engine also reports about the progress
of the fusion job. You
can stop
fusing any time you want, and continue afterwards by re-calling the
fuse
method.
Engine instances are created through the factories (TLfnEngineFactory
and
TLfnLFSEngineFactory
) available in this package. The TLfnEngineFactory
creates an engine which will perform the fusion locally. The TLfnLFSEngineFactory
will do the fusion
remotely. Note that even when the target tile store is remote and not locally, you can still do the fusion locally.
The package documentation
contains an example illustrating how to fuse a
raster.
Modifier | Constructor and Description |
---|---|
protected |
ALfnEngine()
Creates a new engine.
|
Modifier and Type | Method and Description |
---|---|
void |
addSessionHandler(ILfnRasterSessionHandler aHandler)
Register a
raster session handler on this engine. |
void |
addSessionHandler(ILfnVectorSessionHandler aHandler)
Register a
vector session handler on this engine. |
abstract Future<Void> |
fuse(ILfnCallback<Void> aCallback)
Starts the actual fusion.
|
String |
getCoverageId()
Returns the
ID of the target coverage
for this engine. |
abstract ILfnEngineSession |
getEngineSession()
Returns the
session information associated with this engine. |
abstract Throwable |
getFailure()
Returns the error that caused this engine to fail and abort.
|
abstract Future<TLfnProgress> |
getInitialProgress(ILfnCallback<TLfnProgress> aCallback)
Computes the initial progress of the fusion process, before the engine was started.
|
abstract TLfnProgress |
getProgress()
Returns the current progress of the fusion engine.
|
abstract ELfnStatus |
getStatus()
Returns the current status of the fusion engine.
|
URI |
getTileStoreUri()
Returns the uri of the Tile Store that contains the target coverage.
|
void |
removeSessionHandler(ILfnRasterSessionHandler aHandler)
Unregister a handler from this engine.
|
void |
removeSessionHandler(ILfnVectorSessionHandler aHandler)
Unregister a handler from this engine.
|
abstract void |
stop()
Stops this engine.
|
protected ALfnEngine()
Creates a new engine.
Warning: it is highly unlikely you ever need to use this constructor. Typically, you create an engine using the
TLfnEngineFactory
or the TLfnLFSEngineFactory
(for remote fusion).
public abstract Future<Void> fuse(ILfnCallback<Void> aCallback)
Starts the actual fusion. If no initial progress computation has been started, this method will do this as well.
The future returned by this method may throw an ExecutionException
with the following checked exceptions as its cause:
IOException
TLfnServiceException
InterruptedException
Using the asynchronous callback is equivalent to using the Future.get
family of methods.
The callback is notified of the same exceptions as those thrown by the Future.get
family of methods.
Checked exceptions are reported directly on the handler, but when thrown via the Future.get
family of
methods they are wrapped in an ExecutionException
to be compliant with the signature of that method.
An engine instance can only execute a single fusion at a time.
If you call fuse(com.luciad.fusion.util.ILfnCallback<java.lang.Void>)
multiple times on the same engine instance, no new fusion process will be started, but rather the caller will attach to the already running fusion process.
This allows multiple independent callers to steer and listen for the fusion process of the same coverage ID.
It is possible to start/stop/resume a fusion engine any number of times by calling fuse()
and Future.cancel()
and then fuse()
again.
An engine environment may have multiple engines associated with it, but supports only a single fusion at a time.
When fuse()
is called on an engine while another engine in the same environment is already fusing,
the second engine won't start until the first one has finished.
If you explicitly want to run multiple fusion engines simultaneously, you need to create separate ALfnEngineEnvironments
.
aCallback
- a callback for reporting the result and errors. May be null
.IllegalStateException
- when this fusion engine is already running.public abstract void stop()
Stops this engine. As a result, the future returned by an earlier call to fuse(com.luciad.fusion.util.ILfnCallback<java.lang.Void>)
will throw CancellationException.
This is equivalent to calling Future.cancel(boolean)
on the future returned by an earlier call to fuse(com.luciad.fusion.util.ILfnCallback<java.lang.Void>)
.
It is possible to continue to fusion process later on after calling this method. Just re-call the fuse(com.luciad.fusion.util.ILfnCallback)
method and the engine will continue fusing.
public abstract TLfnProgress getProgress()
Returns the current progress of the fusion engine. As long as the initial progress has not been computed, this
method will return TLfnProgress.UNKNOWN
. When the engine has stopped, the progress at the moment the
engine was stopped is returned.
Note that this method will not trigger the computation of the initial progress. If that is what you're after,
you should use getInitialProgress(com.luciad.fusion.util.ILfnCallback<com.luciad.fusion.util.TLfnProgress>)
instead, where you can block for the result.
The returned TLfnProgress
object is a snapshot of the progress at the moment the method is called. The
returned object will not update when the fusion process continues. If you want to show a progress report to the user, you
can for example call at regular intervals this method:
Future<Void> future = engine.fuse(null);
final Timer progressReporter = new Timer();
progressReporter.scheduleAtFixedRate( new TimerTask() {
@Override
public void run() {
TLfnProgress progress = engine.getProgress();
System.out.println("Percentage done: " + progress.getAsFraction() * 100 + "%");
if ( engine.getStatus() == ELfnStatus.COMPLETED || engine.getStatus() == ELfnStatus.FAILED ){
progressReporter.cancel();
}
}
}, 0, 500 );
null
getInitialProgress(com.luciad.fusion.util.ILfnCallback<com.luciad.fusion.util.TLfnProgress>)
public abstract ELfnStatus getStatus()
ELfnStatus.STOPPED
: When the fusion process was not yet started or if it was cancelledELfnStatus.STARTED
: When the fusion process was started and/or is currently runningELfnStatus.COMPLETED
: When the fusion process was completed successfullyELfnStatus.FAILED
: When the fusion process terminated unsuccessfullypublic abstract Future<TLfnProgress> getInitialProgress(ILfnCallback<TLfnProgress> aCallback)
Future
.
The initial progress has the total tile count as bound, and the checkpointed tile count as value.
Note that it is possible to cancel the computation of the initial progress by canceling the future.
The future returned by this method may throw an ExecutionException with the following checked exceptions as its cause:
IOException
TLfnServiceException
InterruptedException
public abstract ILfnEngineSession getEngineSession()
session
information associated with this engine.null
.public String getCoverageId()
ID
of the target coverage
for this engine.public URI getTileStoreUri()
public abstract Throwable getFailure()
null
if the engine hasn't failed.public void addSessionHandler(ILfnRasterSessionHandler aHandler)
raster session handler
on this engine.
Note: to configure whether to continue of abort when non-fatal failures occur, you
should use ALfnCoverageMetadata.isIgnoreNonFatalFailures()
.
aHandler
- The handler to addpublic void removeSessionHandler(ILfnRasterSessionHandler aHandler)
aHandler
- The handler to removepublic void addSessionHandler(ILfnVectorSessionHandler aHandler)
vector session handler
on this engine.
Note: to configure whether to continue of abort when non-fatal failures occur, you
should use ALfnCoverageMetadata.isIgnoreNonFatalFailures()
.
aHandler
- The handler to addpublic void removeSessionHandler(ILfnVectorSessionHandler aHandler)
aHandler
- The handler to remove