org.apache.uima.flow

Interface FlowController

All Known Implementing Classes:

CasFlowController_ImplBase, 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 and 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 Detail

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.