Package org.apache.uima.flow

# Interface FlowController

All Known Implementing Classes:
  `CapabilityLanguageFlowController`, `CasFlowController_ImplBase`, `FixedFlowController`, `FlowController_ImplBase`, `JCasFlowController_ImplBase`

public interface FlowController
FlowControllers are components that decide how to route CASes within Aggregate Analysis Engines. There is always exactly one FlowController per Aggregate Analysis Engine.

FlowController's `initialize(FlowControllerContext)` method receives a `FlowControllerContext`, which is a subtype of `UimaContext` that has the following additional information useful for routing:

- A map from String keys to Analysis Engine Metadata for all Analysis Engines that the FlowController can route CASes to
- Declared Capabilities of the Aggregate AnalysisEngine containing this FlowController.

For each new CAS that is passed to the Aggregate Analysis Engine containing the FlowController, the FlowController's `computeFlow(AbstractCas)` method will be called. This method must construct and return a `Flow` object that is responsible for routing that CAS through the components of the Aggregate Analysis Engine.

A FlowController, like other components, can have custom configuration parameters that it accesses through its Context. These parameters can define the flow using whatever flow language the particular FlowController implementation requires. The `Flow` object can be given a handle to the CAS, so that it can use any information in the CAS to make its routing decisions.

For convenience, FlowController implementations can extend from the base classes `CasFlowController_ImplBase` or `JCasFlowController_ImplBase`, depending on which CAS interface they wish to use.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addAnalysisEngines(Collection<String> aKeys)`
  Notifies this FlowController that new Analysis Engines are now available to route CASes to.
  `void`
  `batchProcessComplete()`
  Completes the processing of a batch of CASes.
  `void`
  `collectionProcessComplete()`
  Notifies this component that processing of an entire collection has been completed.
  `Flow`
  `computeFlow(AbstractCas aCAS)`
  Invokes this FlowController on a CAS.
  `void`
  `destroy()`
  Frees all resources held by this FlowController.
  `Class<? extends AbstractCas>`
  `getRequiredCasInterface()`
  Returns the specific CAS interface that this FlowController requires the framework to pass to its `computeFlow(AbstractCas)` method.
  `void`
  `initialize(FlowControllerContext aContext)`
  Performs any startup tasks required by this component.
  `void`
  `reconfigure()`
  Alerts this FlowController that the values of its configuration parameters or external resources have changed.
  `void`
  `removeAnalysisEngines(Collection<String> aKeys)`
  Notifies this FlowController that some Analysis Engines are no longer available to route CASes to.

- ## Method Details

  - ### initialize

    void initialize(FlowControllerContext aContext) throws ResourceInitializationException
    Performs any startup tasks required by this component. The framework calls this method only once, just after the FlowController has been instantiated.

    The framework supplies this FlowController with a reference to the `FlowControllerContext` that it will use, for example to access configuration settings or resources. This FlowController should store a reference to this Context for later use.

    Parameters:
      `aContext` - Provides access to services and resources managed by the framework. This includes configuration parameters, logging, and access to external resources. Also provides the FlowController with the metadata of all of the AnalysisEngines that are possible targets for routing CASes.
    Throws:
      `ResourceInitializationException` - if the FlowController cannot initialize successfully.

  - ### reconfigure

    void reconfigure() throws ResourceConfigurationException, ResourceInitializationException
    Alerts this FlowController that the values of its configuration parameters or external resources have changed. This FlowController should re-read its configuration from the `UimaContext` and take appropriate action to reconfigure itself.

    In the abstract base classes provided by the framework, this is generally implemented by calling `destroy` followed by `initialize`. If a more efficient implementation is needed, you can override that implementation.

    Throws:
      `ResourceConfigurationException` - if the new configuration is invalid
      `ResourceInitializationException` - if this component encounters a problem in reinitializing itself from the new configuration

  - ### batchProcessComplete

    void batchProcessComplete() throws AnalysisEngineProcessException
    Completes the processing of a batch of CASes. The size of a batch is determined based on configuration provided by the application that is using this component. The purpose of `batchProcessComplete` is to give this component the change to flush information from memory to persistent storage. In the event of an error, this allows the processing to be restarted from the end of the last completed batch.

    If this component's descriptor declares that it is `recoverable`, then this component is required to be restartable from the end of the last completed batch.

    Throws:
      `AnalysisEngineProcessException` - if this component encounters a problem in flushing its state to persistent storage

  - ### collectionProcessComplete

    void collectionProcessComplete() throws AnalysisEngineProcessException
    Notifies this component that processing of an entire collection has been completed. In this method, this component should finish writing any output relating to the current collection.
    Throws:
      `AnalysisEngineProcessException` - if this component encounters a problem in its end-of-collection processing

  - ### destroy

    void destroy()
    Frees all resources held by this FlowController. The framework calls this method only once, when it is finished using this component.

  - ### computeFlow

    Flow computeFlow(AbstractCas aCAS) throws AnalysisEngineProcessException
    Invokes this FlowController on a CAS. The FlowController returns a `Flow` object that is responsible for routing this particular CAS through the components of this Aggregate. The `Flow` object should be given a handle to the CAS, so that it can use information in the CAS to make routing decisions.

    FlowController implementations will typically define their own class that implements `Flow` by extending from the base class `CasFlow_ImplBase` or `JCasFlow_ImplBase`. This method would then just instantiate the flow object, call its `setCas` method to provide a handle to the CAS, and return the flow object.

    Parameters:
      `aCAS` - A CAS that this FlowController should process. The framework will ensure that aCAS implements the specific CAS interface declared in the <casInterface> element of this FlowController's descriptor.
    Returns:
      a Flow object that has responsibility for routing `aCAS` through the Aggregate Analysis Engine.
    Throws:
      `AnalysisEngineProcessException` - if this FlowController encounters a problem computing the flow for the CAS

  - ### getRequiredCasInterface

    Class<? extends AbstractCas> getRequiredCasInterface()
    Returns the specific CAS interface that this FlowController requires the framework to pass to its `computeFlow(AbstractCas)` method.
    Returns:
      the required CAS interface. This must specify a subtype of `AbstractCas`.

  - ### addAnalysisEngines

    void addAnalysisEngines(Collection<String> aKeys)
    Notifies this FlowController that new Analysis Engines are now available to route CASes to. Prior to calling this method the framework will update `FlowControllerContext.getAnalysisEngineMetaDataMap()` with the metadata for these new Analysis Engines.

    This FlowController is not obligated to do anything in response to this method if it does not want to consider routing CASes to the new AnalysisEngines.

    The contract for this method is that the framework will not concurrently call any `Flow.next()` methods on any Flow objects produced by this FlowController, during the time between when the Analysis Engine MetaData map is updated and the time when this method completes.

    Parameters:
      `aKeys` - a Collection of Strings, each of which is the key of an Analysis Engine to which CASes can be routed. These are the same keys as used in `FlowControllerContext.getAnalysisEngineMetaDataMap()`.

  - ### removeAnalysisEngines

    void removeAnalysisEngines(Collection<String> aKeys) throws AnalysisEngineProcessException
    Notifies this FlowController that some Analysis Engines are no longer available to route CASes to. Prior to calling this method the framework will update `FlowControllerContext.getAnalysisEngineMetaDataMap()` and will remove the metadata for these new Analysis Engines.

    It is not required for a FlowController implementation to support this method. It may throw an exception if this operation is not supported (see `AnalysisEngineProcessException.REMOVE_AE_FROM_FLOW_NOT_SUPPORTED`. Also the FlowController may throw an Exception if it determines that it does not make sense for the flow to continue in the absence of the removed Analysis Engines (see `AnalysisEngineProcessException.FLOW_CANNOT_CONTINUE_AFTER_REMOVE`.

    The contract for this method is that the framework will not concurrently call any `Flow.next()` methods on any Flow objects produced by this FlowController, during the time between when the Analysis Engine MetaData map is updated and the time when this method completes.

    Parameters:
      `aKeys` - a Collection of Strings, each of which is the key of an Analysis Engine to which CASes may no longer be routed.
    Throws:
      `AnalysisEngineProcessException` - if the FlowController cannot continue with these Analysis Engines removed, or doesn't support removing Analysis Engines at all.