Package com.luciad.fusion.engine

Class ALfnEngine

java.lang.Object
com.luciad.fusion.engine.ALfnEngine
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.

Since:
10.0
See Also:

  • Constructor Details

  • Method Details

    • fuse

      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.

      Parameters:
      aCallback - a callback for reporting the result and errors. May be null.
      Returns:
      a future result which can be used to cancel the fusion or await its completion
      Throws:
      IllegalStateException - when this fusion engine is already running.
      Since:
      2012.0 this asynchronous method replaces its synchronous counterpart of earlier releases

    • stop

      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.

      Since:
      2013.0

    • getProgress

      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 );
      Returns:
      a progress (immutable), never null
      Since:
      2012.0 this method is non-blocking
      See Also:

    • getStatus

      public abstract ELfnStatus getStatus()
      Returns the current status of the fusion engine. The fusion engine can be in one of the following states:
      Returns:
      the current status of the fusion engine.
      Since:
      2013.0

    • getInitialProgress

      public abstract Future<TLfnProgress> getInitialProgress(ILfnCallback<TLfnProgress> aCallback)
      Computes the initial progress of the fusion process, before the engine was started. This is 0 if the fusion process is set up for the first time, or may be different if part of the fusion process has already been done before. The initial progress can be retrieved as the result of the returned 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
      Returns:
      a future result for the initial progress. The initial progress has the total tile count as bound, and the checkpointed tile count as value.
      Since:
      2012.0

    • getEngineSession

      public abstract ILfnEngineSession getEngineSession()
      Returns the session information associated with this engine.
      Returns:
      The session this engine is for, never null.
      Since:
      2013.0

    • getCoverageId

      public String getCoverageId()
      Returns the ID of the target coverage for this engine.
      Returns:
      The coverage ID of the target of this engine
      Since:
      2013.0

    • getTileStoreUri

      public URI getTileStoreUri()
      Returns the uri of the Tile Store that contains the target coverage.
      Returns:
      The URI of the Tile Store.
      Since:
      2013.0

    • getFailure

      public abstract Throwable getFailure()
      Returns the error that caused this engine to fail and abort.
      Returns:
      The error that caused this engine to fail. null if the engine hasn't failed.
      Since:
      2013.0

    • addSessionHandler

      public void addSessionHandler(ILfnRasterSessionHandler aHandler)
      Register a raster session handler on this engine.

      • The handler will immediately receive all failures that have already occurred
      • The handler will later receive any subsequent failures

      Note: to configure whether to continue of abort when non-fatal failures occur, you should use ALfnCoverageMetadata.isIgnoreNonFatalFailures().

      Parameters:
      aHandler - The handler to add
      Since:
      2013.0

    • removeSessionHandler

      public void removeSessionHandler(ILfnRasterSessionHandler aHandler)
      Unregister a handler from this engine.
      Parameters:
      aHandler - The handler to remove
      Since:
      2013.0

    • addSessionHandler

      public void addSessionHandler(ILfnVectorSessionHandler aHandler)
      Register a vector session handler on this engine.

      • The handler will immediately receive all failures that have already occurred
      • The handler will later receive any subsequent failures

      Note: to configure whether to continue of abort when non-fatal failures occur, you should use ALfnCoverageMetadata.isIgnoreNonFatalFailures().

      Parameters:
      aHandler - The handler to add
      Since:
      2013.0

    • removeSessionHandler

      public void removeSessionHandler(ILfnVectorSessionHandler aHandler)
      Unregister a handler from this engine.
      Parameters:
      aHandler - The handler to remove
      Since:
      2013.0