public interface AnalysisEngine extends ConfigurableResource, CasObjectProcessor
 An AnalysisEngine operates on an "analysis structure" (implemented by
 CAS). The CAS contains the artifact to be processed as
 well as semantic information already inferred from that artifact. The AnalysisEngine analyzes
 this information and adds new information to the CAS.
 
 To create an instance of an Analysis Engine, an application should call
 UIMAFramework.produceAnalysisEngine(ResourceSpecifier).
 
A typical application interacts with the Analysis Engine interface as follows:
newCAS() to create a new Common Analysis System appropriate for this
 AnalysisEngine.CAS interface to populate the CAS with the artifact to be
 analyzed any information known about this document (e.g. the language of a text document).ResultSpecification that
 identifies the results you would like this AnalysisEngine to generate (e.g. people, places, and
 dates), and call the {#link setResultSpecification(ResultSpecification) method.process(CAS) - the AnalysisEngine will perform its analysis.CAS.CAS.reset() to clear out the CAS and prepare for processing a new
 artifact.
 Important: It is highly recommended that you reuse CAS objects rather than
 calling newCAS() prior to each analysis. This is because CAS objects
 may be expensive to create and may consume a significant amount of memory.
 
 Instead of using the CAS interface, applications may wish to use the Java-object-based
 JCas interface. In that case, the call to newCAS from step 1 above would be
 replaced by newJCas(), and the process(JCas) method would be used.
 
 Analysis Engine implementations may or may not be capable of simultaneously processing multiple
 documents in a multithreaded environment. See the documentation associated with the
 implementation or factory method (e.g.
 (UIMAFramework.produceAnalysisEngine(ResourceSpecifier)) that you are
 using.
| Modifier and Type | Field and Description | 
|---|---|
| static String | MDC_ANNOTATOR_CONTEXT_NAME | 
| static String | MDC_ANNOTATOR_IMPL_NAME | 
| static String | MDC_CAS_ID | 
| static String | MDC_ROOT_CONTEXT_ID | 
| static String | PARAM_CONFIG_PARAM_SETTINGSDeprecated. 
 | 
| static String | PARAM_MBEAN_NAME_PREFIXKey for the initialization parameter whose value is a String representing the prefix that will
 be added to all of the JMX MBean names that are generated by this AE (and its components, if it
 is an aggregate). | 
| static String | PARAM_MBEAN_SERVERKey for the initialization parameter whose value is a JMX MBeanServer instance, with which this
 AnalysisEngine will register an MBean that allows monitoring of the AE's performance through
 JMX. | 
| static String | PARAM_NUM_SIMULTANEOUS_REQUESTSKey for the initialization parameter whose value is the number of simultaneous calls to
  process(CAS)that will be supported. | 
| static String | PARAM_RESOURCE_MANAGERDeprecated. 
 | 
| static String | PARAM_THROTTLE_EXCESSIVE_ANNOTATOR_LOGGINGSometimes Annotators may log excessively, causing problems in production settings. | 
| static String | PARAM_TIMEOUT_PERIODKey for the initialization parameter whose value is the maximum number of milliseconds to wait
 for a pooled object (see  PARAM_NUM_SIMULTANEOUS_REQUESTS) to become available to serve
 aprocess(CAS)request. | 
PARAM_AGGREGATE_SOFA_MAPPINGS, PARAM_CONFIG_MANAGER, PARAM_EXTERNAL_OVERRIDE_SETTINGS, PARAM_PERFORMANCE_TUNING_SETTINGS, PARAM_UIMA_CONTEXT| Modifier and Type | Method and Description | 
|---|---|
| void | batchProcessComplete()Notifies this AnalysisEngine that processing of a batch has completed. | 
| void | collectionProcessComplete()Notifies this AnalysisEngine that processing of an entire collection has completed. | 
| ResultSpecification | createResultSpecification()
 A factory method used to create an instance of  ResultSpecificationfor use with this
 AnalysisEngine. | 
| ResultSpecification | createResultSpecification(TypeSystem aTypeSystem)A factory method used to create an instance of  ResultSpecificationfor use with this
 AnalysisEngine. | 
| AnalysisEngineMetaData | getAnalysisEngineMetaData()Gets the metadata that describes this  AnalysisEngine. | 
| String[] | getFeatureNamesForType(String aTypeName)Gets the names of the features that are defined on one of the CAS types that this AE inputs or
 outputs. | 
| Logger | getLogger()Gets the Logger that this Analysis Engine is currently using. | 
| AnalysisEngineManagement | getManagementInterface()Gets an object that can be used to do monitoring or management of this AnalysisEngine. | 
| Properties | getPerformanceTuningSettings()Gets the performance tuning settings in effect for this Analysis Engine. | 
| ResourceManager | getResourceManager()Gets the  ResourceManagerused by this AnalysisEngine. | 
| boolean | initialize(ResourceSpecifier aSpecifier,
          Map<String,Object> aAdditionalParams)Initializes this  Resourcefrom aResourceSpecifier. | 
| CAS | newCAS()Creates a new Common Analysis System appropriate for this Analysis Engine. | 
| JCas | newJCas() | 
| void | process(AnalysisProcessData aProcessData,
       ResultSpecification aResultSpec)Deprecated. 
 This is no longer used by the framework and was never intended for users to call.
             Use {#link #process(CAS)} instead. | 
| ProcessTrace | process(CAS aCAS)Invokes this AnalysisEngine's analysis logic. | 
| ProcessTrace | process(CAS aCAS,
       ResultSpecification aResultSpec)Invokes this AnalysisEngine's analysis logic. | 
| void | process(CAS aCAS,
       ResultSpecification aResultSpec,
       ProcessTrace aTrace)Invokes this AnalysisEngine's analysis logic. | 
| ProcessTrace | process(JCas aJCas)Similar to  process(CAS)but uses the Java-object-basedJCasinterface instead
 of the generalCASinterface. | 
| ProcessTrace | process(JCas aJCas,
       ResultSpecification aResultSpec)Similar to  process(CAS,ResultSpecification)but uses the Java-object-basedJCasinterface instead of the generalCASinterface. | 
| void | process(JCas aJCas,
       ResultSpecification aResultSpec,
       ProcessTrace aTrace)Similar to  process(CAS, ResultSpecification, ProcessTrace)but uses the
 Java-object-basedJCasinterface instead of the generalCASinterface. | 
| CasIterator | processAndOutputNewCASes(CAS aCAS)Processes a CAS, possibly producing multiple CASes as a result. | 
| JCasIterator | processAndOutputNewCASes(JCas aJCAS)Processes a JCAS, possibly producing multiple JCASes as a result. | 
| void | reconfigure()Reconfigures this Resource using the most current parameter settings. | 
| void | setLogger(Logger aLogger)Sets the Logger that this Analysis Engine will use. | 
| void | setResultSpecification(ResultSpecification aResultSpec)Sets the list of output types and features that the application wants this AnalysisEngine to
 produce. | 
getConfigParameterValue, getConfigParameterValue, setConfigParameterValue, setConfigParameterValuedestroy, getMetaData, getUimaContext, getUimaContextAdminprocessCas, processCas, typeSystemInitbatchProcessComplete, collectionProcessComplete, getProcessingResourceMetaData, isReadOnly, isStateless@Deprecated static final String PARAM_RESOURCE_MANAGER
Resource.PARAM_RESOURCE_MANAGERResourceManager
 that this AnalysisEngine should use. This value is used as a key in the
 aAdditionalParams Map that is passed to the
 initialize(ResourceSpecifier,Map) method.@Deprecated static final String PARAM_CONFIG_PARAM_SETTINGS
Resource.PARAM_CONFIG_PARAM_SETTINGSConfigurationParameterSettings
 object that holds configuration settings that will be used to configure this AnalysisEngine,
 overriding any conflicting settings specified in this AnalysisEngine's Descriptor. This value
 is used as a key in the aAdditionalParams Map that is passed to the
 initialize(ResourceSpecifier,Map) method.static final String PARAM_NUM_SIMULTANEOUS_REQUESTS
process(CAS) that will be supported. Analysis Engine implementations may use this to
 create a pool of objects (e.g. Annotators), each of which can process only one request at a
 time. Applications should be careful about setting this number higher than is necessary, since
 large pools of objects may increase initialization time and consume resources. Not all analysis
 engine implementations pay attention to this parameter.
 
 This value is used as a key in the aAdditionalParams Map that is passed to the
 initialize(ResourceSpecifier,Map) method.
static final String PARAM_TIMEOUT_PERIOD
PARAM_NUM_SIMULTANEOUS_REQUESTS) to become available to serve
 a process(CAS) request. If the processing has not begun within this time, an exception
 will be thrown. A value of zero will cause the AnalysisEngine to wait forever. Not all
 analysis* engine implementations pay attention to this parameter.
 
 This value is used as a key in the aAdditionalParams Map that is passed to the
 initialize(ResourceSpecifier,Map) method.
static final String PARAM_MBEAN_SERVER
 This value is used as a key in the aAdditionalParams Map that is passed to the
 initialize(ResourceSpecifier,Map) method.
static final String PARAM_MBEAN_NAME_PREFIX
The string must be a valid JMX MBean name (although a name with only a domain and no keys is permitted). See http://java.sun.com/j2se/1.5.0/docs/api/javax/management/ObjectName.html for details.
Examples of valid prefixes are:
UIMA will append additional key,value pairs to this prefix. In particular, UIMA uses the key "name" (as the very last component of the MBean name), as well as the keys "p0","p1","p2",etc (to represent the chain of aggregates containing an AE). So the application may not use any of these keys in its prefix.
 This value is used as a key in the aAdditionalParams Map that is passed to the
 initialize(ResourceSpecifier,Map) method.
static final String PARAM_THROTTLE_EXCESSIVE_ANNOTATOR_LOGGING
For this case, this key specifies that throttling should be applied to messages produced by annotators using loggers obtained by Annotator code using the getLogger() API.
The value specified should be an integer, and is the number of messages allowed before logging is suppressed. This number is applied to each logging level, separately. To suppress all logging, use 0.
static final String MDC_ANNOTATOR_IMPL_NAME
static final String MDC_ANNOTATOR_CONTEXT_NAME
static final String MDC_ROOT_CONTEXT_ID
static final String MDC_CAS_ID
boolean initialize(ResourceSpecifier aSpecifier, Map<String,Object> aAdditionalParams) throws ResourceInitializationException
Resource from a ResourceSpecifier. Applications do
 not need to call this method. It is called automatically by the ResourceFactory
 and cannot be called a second time.
 
 The AnalysisEngine interface defines several optional parameter that can be passed
 in the aAdditionalParams Map - see the PARAM constants on this
 interface.
initialize in interface ResourceaSpecifier - specifies how to create a resource or locate an existing resource service.aAdditionalParams - a Map containing additional parameters. May be null if there are no
          parameters. Each class that implements this interface can decide what additional
          parameters it supports.ResourceSpecifier is not of an appropriate type for this Resource. If the
         ResourceSpecifier is of an appropriate type but is invalid or if some
         other failure occurs, an exception should be thrown.ResourceInitializationException - if a failure occurs during initialization.Resource.initialize(ResourceSpecifier,Map)AnalysisEngineMetaData getAnalysisEngineMetaData()
AnalysisEngine. This is just a convenience
 method that calls Resource.getMetaData() and casts the result to a
 AnalysisEngineMetaData.CAS newCAS() throws ResourceInitializationException
process(CAS) method. Then, when the process
 method returns, the CAS will contain the results of the analysis.
 
 Important: CAS creation is expensive, so if at all possible an application should reuse
 CASes. When a CAS instance is no longer being used, call its CAS.reset() method, which
 will remove all prior analysis information, and then reuse that same CAS instance for another
 call to process(CAS).
 
 Note that the CAS allows multiple subjects of analysis (e.g. documents) and defines a separate
 "view" for each of them. If your application wants to work with a single subject of analysis,
 call the method CAS.getCurrentView() and operate on the returned view.
CAS appropriate for this AnalysisEngine.ResourceInitializationException - if a CAS could not be created because this AnalysisEngine's CAS metadata (type
           system, type priorities, or FS indexes) are invalid. Ideally this would be checked at
           AnalysisEngine initialization time, and it will likely be moved in the future.JCas newJCas() throws ResourceInitializationException
newCAS() but wraps the new CAS objects with the Java-object-based
 JCas interface.
 
 Note: the JCas that is returned is equivalent to what you would get if you called
 newCAS().getCurrentView().getJCas(). That is, this method returns a view of the
 default Sofa, NOT a Base CAS.
 
 Important: CAS creation is expensive, so if at all possible an application should reuse
 CASes. When a JCas instance is no longer being used, call its JCas.reset() method,
 which will remove all prior analysis information, and then reuse that same JCas instance for
 another call to process(JCas).
CAS appropriate for this AnalysisEngine.ResourceInitializationException - if a CAS could not be created because this AnalysisEngine's CAS metadata (type
           system, type priorities, or FS indexes) are invalid. Ideally this would be checked at
           AnalysisEngine initialization time, and it will likely be moved in the future.ProcessTrace process(CAS aCAS, ResultSpecification aResultSpec) throws ResultNotSupportedException, AnalysisEngineProcessException
Capability specification.)
 
 This version of the process method takes a ResultSpecification as an
 argument. The ResultSpecification is alist of output types and features that the
 application wants this AnalysisEngine to produce. If you are going to use the same
 ResultSpecification for multiple calls to process, it is not recommended
 to use this method. Instead call setResultSpecification(ResultSpecification) once and
 then call process(CAS) for each CAS that you want to process.
aCAS - the CAS containing the inputs to the processing. Analysis results will also be written
          to this CAS.aResultSpec - a list of outputs that this AnalysisEngine should produce.ResultNotSupportedException - if this AnalysisEngine is not capable of producing the results requested in
           aResultSpec.AnalysisEngineProcessException - if a failure occurs during processing.ProcessTrace process(CAS aCAS) throws AnalysisEngineProcessException
Capability specification.)
 
 This version of process does not take a ResultSpecification parameter. You
 may specify a ResultSpecification by calling
 setResultSpecification(ResultSpecification) prior to calling this method.
aCAS - the CAS containing the inputs to the processing. Analysis results will also be written
          to this CAS.AnalysisEngineProcessException - if a failure occurs during processing.void process(CAS aCAS, ResultSpecification aResultSpec, ProcessTrace aTrace) throws ResultNotSupportedException, AnalysisEngineProcessException
Capability specification.)
 
 This version of the process method takes a ResultSpecification as an
 argument. The ResultSpecification is a list of output types and features that the
 application wants this AnalysisEngine to produce. If you are going to use the same
 ResultSpecification for multiple calls to process, it is not recommended
 to use this method. Instead call setResultSpecification(ResultSpecification) once and
 then call process(CAS) for each CAS that you want to process.
 
 This version of this method also takes a ProcessTrace object as a parameter. This
 allows trace events to be written to an existing ProcessTrace rather than a new
 one.
aCAS - the CAS containing the inputs to the processing. Analysis results will also be written
          to this CAS.aResultSpec - a list of outputs that this AnalysisEngine should produce.aTrace - the object to which trace events will be recordedResultNotSupportedException - if this AnalysisEngine is not capable of producing the results requested in
           aResultSpec.AnalysisEngineProcessException - if a failure occurs during processing.@Deprecated void process(AnalysisProcessData aProcessData, ResultSpecification aResultSpec) throws ResultNotSupportedException, AnalysisEngineProcessException
Capability specification.)
 
 This version of this method is not normally used directly by applications. It is used to call
 Analysis Engines that are components within an aggregate Analysis Engine, so that they can
 share all information in the AnalysisProcessData object, which includes the CAS and the
 ProcessTrace.
aResultSpec - a list of outputs that this AnalysisEngine should produce. A null result
          specification is equivalent to a request for all possible results.aProcessData - the data that will be modified during processing. This includes the CAS and the
          ProcessTrace.ResultNotSupportedException - if this AnalysisEngine is not capable of producing the results requested in
           aResultSpec.AnalysisEngineProcessException - if a failure occurs during processing.ProcessTrace process(JCas aJCas) throws AnalysisEngineProcessException
process(CAS) but uses the Java-object-based JCas interface instead
 of the general CAS interface.aJCas - the JCas containing the inputs to the processing. Analysis results will also be
          written to this JCas.AnalysisEngineProcessException - if a failure occurs during processing.ProcessTrace process(JCas aJCas, ResultSpecification aResultSpec) throws ResultNotSupportedException, AnalysisEngineProcessException
process(CAS,ResultSpecification) but uses the Java-object-based
 JCas interface instead of the general CAS interface.
 
 This version of the process method takes a ResultSpecification as an
 argument. The ResultSpecification is a list of output types and features that the
 application wants this AnalysisEngine to produce. If you are going to use the same
 ResultSpecification for multiple calls to process, it is not recommended
 to use this method. Instead call setResultSpecification(ResultSpecification) once and
 then call process(JCas) for each CAS that you want to process.
aJCas - the JCas containing the inputs to the processing. Analysis results will also be
          written to this JCas.aResultSpec - a list of outputs that this AnalysisEngine should produce.ResultNotSupportedException - if this AnalysisEngine is not capable of producing the results requested in
           aResultSpec.AnalysisEngineProcessException - if a failure occurs during processing.void process(JCas aJCas, ResultSpecification aResultSpec, ProcessTrace aTrace) throws ResultNotSupportedException, AnalysisEngineProcessException
process(CAS, ResultSpecification, ProcessTrace) but uses the
 Java-object-based JCas interface instead of the general CAS interface.
 
 This version of the process method takes a ResultSpecification as an
 argument. The ResultSpecification is a list of output types and features that the
 application wants this AnalysisEngine to produce. If you are going to use the same
 ResultSpecification for multiple calls to process, it is not recommended
 to use this method. Instead call setResultSpecification(ResultSpecification) once and
 then call process(JCas) for each CAS that you want to process.
 
 This version of this method also takes a ProcessTrace object as a parameter. This
 allows trace events to be written to an existing ProcessTrace rather than a new
 one.
aJCas - the JCas containing the inputs to the processing. Analysis results will also be
          written to this JCas.aResultSpec - a list of outputs that this AnalysisEngine should produce.aTrace - the object to which trace events will be recordedResultNotSupportedException - if this AnalysisEngine is not capable of producing the results requested in
           aResultSpec.AnalysisEngineProcessException - if a failure occurs during processing.CasIterator processAndOutputNewCASes(CAS aCAS) throws AnalysisEngineProcessException
CasIterator interface to step through the output CASes.
 
 If this Analysis Engine does not produce output CASes, then the CasIterator will
 return no elements. You can check if an AnalysisEngine is capable of producing output CASes by
 checking the
 OperationalProperties.getOutputsNewCASes()
 operational property
 (getAnalysisEngineMetaData().getOperationalProperties().getOutputsNewCASes()).
 
 Once this method is called, the AnalysisEngine "owns" aCAS until such time as the
 CasIterator.hasNext() method returns false. That is, the caller should not attempt to
 modify or access the input CAS until it has read all of the elements from the CasIterator. If
 the caller wants to abort the processing before having read all of the output CASes, it may
 call CasIterator.release(), which will stop further processing from occurring, and
 ownership of aCAS will revert to the caller.
aCAS - the CAS to be processedAnalysisEngineProcessException - if a failure occurs during processingJCasIterator processAndOutputNewCASes(JCas aJCAS) throws AnalysisEngineProcessException
JCasIterator interface to step through the output JCASes.
 
 If this Analysis Engine does not produce output CASes, then the CasIterator will
 return no elements. You can check if an AnalysisEngine is capable of producing output CASes by
 checking the
 OperationalProperties.getOutputsNewCASes()
 operational property
 (getAnalysisEngineMetaData().getOperationalProperties().getOutputsNewCASes()).
 
 Once this method is called, the AnalysisEngine "owns" aJCAS until such time as the
 JCasIterator.hasNext() method returns false. That is, the caller should not attempt to
 modify or access the input JCAS until it has read all of the elements from the JCasIterator.
 outputCASes, it may call JCasIterator.release(), which will stop further processing
 from occurring, and ownership of aJCAS will revert to the caller.
aJCAS - the JCAS to be processedAnalysisEngineProcessException - if a failure occurs during processingvoid batchProcessComplete()
                   throws AnalysisEngineProcessException
AnalysisEngineProcessException - if an exception occurs during processingvoid collectionProcessComplete()
                        throws AnalysisEngineProcessException
 If this AnalysisEngine is an aggregate, this method will call the collectionProcessComplete
 method of all components of that aggregate. If the aggregate descriptor declares a
 fixedFlow or capabilityLanguageFlow, then the components'
 collectionProcessComplete methods will be called in the order specified by that flow element.
 Once all components in the flow have been called, any components not declared in the flow will
 be called, in arbitrary order. If there is no fixedFlow or
 capabilityLanguageFlow, then all components in the aggregate will be called in
 arbitrary order.
AnalysisEngineProcessException - if an exception occurs during processingResultSpecification createResultSpecification()
 A factory method used to create an instance of ResultSpecification for use with this
 AnalysisEngine. Applications use this method to construct ResultSpecifications to
 pass to this AnalysisEngine's setResultSpecification(ResultSpecification) method.
 
 
 See also createResultSpecification(TypeSystem) which should be used if the type system
 associated with this result specification is known at this point in time.
ResultSpecificationResultSpecification createResultSpecification(TypeSystem aTypeSystem)
ResultSpecification for use with this
 AnalysisEngine. Applications use this method to construct ResultSpecifications to
 pass to this AnalysisEngine's setResultSpecification(ResultSpecification) method.aTypeSystem - the type systemResultSpecificationResourceManager getResourceManager()
ResourceManager used by this AnalysisEngine.getResourceManager in interface Resourcevoid reconfigure()
          throws ResourceConfigurationException
ConfigurableResource.setConfigParameterValue(String,String,Object) do not take effect until this method is
 called.
 
 If this is an aggregate Analysis Engine, configuration parameter settings will be "pushed down"
 to delegate Analysis Engines that also declare those parameters. All annotators will be
 informed of the change by a call to their
 BaseAnnotator.reconfigure() methods.
reconfigure in interface ConfigurableResourceResourceConfigurationException - if the configuration is not validLogger getLogger()
void setLogger(Logger aLogger)
UIMAFramework.getLogger()) will be used.String[] getFeatureNamesForType(String aTypeName)
allAnnotatorFeatures == true,
 this method can be used to determine all of the feature names.aTypeName - type for which to get featuresaTypeName is not defined, null
         will be returned.Properties getPerformanceTuningSettings()
void setResultSpecification(ResultSpecification aResultSpec)
aResultSpec - specifies the list of output types and features that the application is interested in.AnalysisEngineManagement getManagementInterface()
Copyright © 2006–2022 The Apache Software Foundation. All rights reserved.