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:

For each new CAS that is passed to the Aggegrate 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 copmonents 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
 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 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.
 

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:
ResourceConfiguartionException - if the new configuration is invalid
ResourceInitializationException - if this component encounters a problem in reinitializing itself from the new configuration
ResourceConfigurationException

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:
AnalysisEngineComponentException - if this FlowController encounters a problem computing the flow for the CAS
AnalysisEngineProcessException

getRequiredCasInterface

Class 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.


Copyright © 2007 The Apache Software Foundation. All Rights Reserved.