gov.va.vinci.leo.ae

Class LeoBaseAnnotator

java.lang.Object

org.apache.uima.analysis_component.AnalysisComponent_ImplBase

org.apache.uima.analysis_component.Annotator_ImplBase

org.apache.uima.analysis_component.JCasAnnotator_ImplBase

gov.va.vinci.leo.ae.LeoBaseAnnotator

All Implemented Interfaces:

LeoAnnotator, org.apache.uima.analysis_component.AnalysisComponent

Direct Known Subclasses:

LeoCachingAnnotator

public abstract class LeoBaseAnnotator
extends org.apache.uima.analysis_component.JCasAnnotator_ImplBase
implements LeoAnnotator

Base annotator class for holding functions that all annotators might take advantage of, such as loading resource files, etc.

Note: This base class assumes a string[] parameter of input types and a string output type in the uima parameters to know what input types to use and what output type to create.

Field Summary

Fields

Modifier and Type	Field and Description
protected String[]	excludeTypesFilter Optional, only process a CAS if it does not include instances of one of the types in this list.
protected String[]	includeTypesFilter Optional, only process CAS if it includes instances of one of the types in the list.
protected String[]	inputTypes The types of annotations to use as "anchors" or to be processed.
protected static org.apache.log4j.Logger	logger Logger object for messaging.
protected String	name Optional, Name of the annotator to be set in the descriptor.
protected long	numberOfCASesProcessed Counter for the number of CASes this annotator has processed.
protected long	numberOfFilteredCASesProcessed Counter for the number of CASes that made it past the filter for processing.
protected int	numInstances Number of replication instances for this annotator.
protected String	outputType The output type that will be created for each matching window.
protected LeoTypeSystemDescription	typeSystemDescription Type system for this annotator, defaults to an empty type system.

Constructor Summary

Constructors

Constructor and Description
LeoBaseAnnotator() Default constructor for initialization by the UIMA Framework.
LeoBaseAnnotator(String outputType, String... inputTypes) Constructor setting the initial values for the inputTypes and outputType parameters.

Method Summary

Modifier and Type	Method and Description
<T extends LeoBaseAnnotator> T	addLeoTypeSystemDescription(LeoTypeSystemDescription typeSystemDescription) Add the type system provided to the type system of the annotator.
protected org.apache.uima.jcas.tcas.Annotation	addOutputAnnotation(String outputType, org.apache.uima.jcas.JCas cas, int begin, int end) Create an output annotation, and add it to the cas.
protected org.apache.uima.jcas.tcas.Annotation	addOutputAnnotation(String outputType, org.apache.uima.jcas.JCas cas, int begin, int end, Map<String,Object> featureNameValues) Create an output annotation, and add it to the cas.
abstract void	annotate(org.apache.uima.jcas.JCas aJCas) This method is called by the LeoBaseAnnotator process method if the CAS meets the filter requirements and either has not input types defined or else contains one or more instances of the input types.
void	collectionProcessComplete()
protected boolean	containsAnnotationInList(org.apache.uima.jcas.JCas jCas, String[] typeList, boolean isEmpty) Checks the CAS for instances of the annotation types in the list.
protected org.apache.uima.cas.FSIterator<org.apache.uima.jcas.tcas.Annotation>	getAnnotationListForType(org.apache.uima.jcas.JCas aJCas, String type) Given a cas and type, return all of the annotations in the cas for that type.
LeoDelegate	getDescriptor() Generate a descriptor from this annotator object.
String[]	getExcludeTypesFilter() Get the exclude types list.
String[]	getIncludeTypesFilter() Return the types filter array of type names.
String[]	getInputTypes() Get the input types list this annotator will use.
LeoAEDescriptor	getLeoAEDescriptor() Generate a descriptor from this annotator object.
LeoTypeSystemDescription	getLeoTypeSystemDescription() Return the type system description for this annotator.
String	getName() Get the name of this annotator.
long	getNumberOfCASesProcessed() Get the number of CASes this annotator has processed.
long	getNumberOfFilteredCASesProcessed() Get the number of CASes that were processed once getting through the filter.
int	getNumInstances() Number of instances of this annotator in the pipeline.
String	getOutputType() Get the output type name this annotator will use.
InputStream	getResourceAsInputStream(String resourcePath) Gets a resource as an input stream.
String	getResourceFileAsString(String resourcePath) Note: Resource paths are specified via file: and classpath: to determine if the resource should be looked up in the file system or in the classpath.
protected boolean	hasFilteredAnnotation(org.apache.uima.jcas.JCas jCas) If includeTypesFilter is not set then return true.
protected boolean	hasInputTypesAnnotation(org.apache.uima.jcas.JCas jCas) If the input types list is empty or one or more of the types are found in the CAS then return true, return false otherwise.
void	initialize(org.apache.uima.UimaContext aContext) Initialize this annotator.
void	process(org.apache.uima.jcas.JCas aJCas) Called once by the UIMA Framework for each document being analyzed (each CAS instance).
<T extends LeoBaseAnnotator> T	resetNumberOfCASesProcessed() Set the number of CASes this annotator has processed.
<T extends LeoBaseAnnotator> T	resetNumberOfFilteredCASesProcessed() Reset the number of filtered CASes processed.
<T extends LeoBaseAnnotator> T	setExcludeTypesFilter(String... excludeTypesFilterNames) Set the list of exclude types.
<T extends LeoBaseAnnotator> T	setIncludeTypesFilter(String... includeTypesFilterNames) Set one or more types to filter on.
<T extends LeoBaseAnnotator> T	setInputTypes(String... inputTypes) Set the input types list.
<T extends LeoBaseAnnotator> T	setLeoTypeSystemDescription(LeoTypeSystemDescription typeSystemDescription) Set the type system for this annotator.
<T extends LeoBaseAnnotator> T	setName(String name) Set the name of this annotator.
<T extends LeoBaseAnnotator> T	setNumInstances(int numInstances) Set the number of instances of this annotator in the pipeline.
<T extends LeoBaseAnnotator> T	setOutputType(String outputType) Set the output type name.

Methods inherited from class org.apache.uima.analysis_component.JCasAnnotator_ImplBase

getRequiredCasInterface, process

Methods inherited from class org.apache.uima.analysis_component.Annotator_ImplBase

getCasInstancesRequired, hasNext, next

Methods inherited from class org.apache.uima.analysis_component.AnalysisComponent_ImplBase

batchProcessComplete, destroy, getContext, getResultSpecification, reconfigure, setResultSpecification

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

logger

protected static org.apache.log4j.Logger logger

Logger object for messaging.

inputTypes

@LeoConfigurationParameter
protected String[] inputTypes

The types of annotations to use as "anchors" or to be processed.

outputType

@LeoConfigurationParameter
protected String outputType

The output type that will be created for each matching window.

numberOfCASesProcessed

protected long numberOfCASesProcessed

Counter for the number of CASes this annotator has processed.

numberOfFilteredCASesProcessed

protected long numberOfFilteredCASesProcessed

Counter for the number of CASes that made it past the filter for processing.

numInstances

protected int numInstances

Number of replication instances for this annotator.

name

protected String name

Optional, Name of the annotator to be set in the descriptor.

typeSystemDescription

protected LeoTypeSystemDescription typeSystemDescription

Type system for this annotator, defaults to an empty type system.

includeTypesFilter

@LeoConfigurationParameter
protected String[] includeTypesFilter

Optional, only process CAS if it includes instances of one of the types in the list.

excludeTypesFilter

@LeoConfigurationParameter
protected String[] excludeTypesFilter

Optional, only process a CAS if it does not include instances of one of the types in this list.

Constructor Detail

LeoBaseAnnotator

public LeoBaseAnnotator()

Default constructor for initialization by the UIMA Framework.

LeoBaseAnnotator

public LeoBaseAnnotator(String outputType,
                        String... inputTypes)

Constructor setting the initial values for the inputTypes and outputType parameters.

Parameters:

outputType - Annotation type to be used as output for this annotator

inputTypes - One or more annotation types on which processing will occur

Method Detail

getInputTypes

public String[] getInputTypes()

Get the input types list this annotator will use.

Returns:

list of input types

setInputTypes

public <T extends LeoBaseAnnotator> T setInputTypes(String... inputTypes)

Set the input types list.

Parameters:

inputTypes - input types list

Returns:

reference to this annotator instance

getOutputType

public String getOutputType()

Get the output type name this annotator will use.

Returns:

output type name

setOutputType

public <T extends LeoBaseAnnotator> T setOutputType(String outputType)

Set the output type name.

Parameters:

outputType - output type name

Returns:

reference to this annotator instance

getNumInstances

public int getNumInstances()

Number of instances of this annotator in the pipeline. Used during asynchronous processing only.

Returns:

Number of instances

setNumInstances

public <T extends LeoBaseAnnotator> T setNumInstances(int numInstances)

Set the number of instances of this annotator in the pipeline. Used during asynchronous processing.

Type Parameters:

T - delegate object reference for extending classes to support the builder pattern.

Parameters:

numInstances - Number of replication instances for this annotator in the pipeline

Returns:

reference to this object instance

getName

public String getName()

Get the name of this annotator.

Returns:

String representation of the annotator name

setName

public <T extends LeoBaseAnnotator> T setName(String name)

Set the name of this annotator.

Type Parameters:

T - delegate object reference for extending classes to support the builder pattern.

Parameters:

name - String representation of the annotator name to set

Returns:

reference to this object instance

getIncludeTypesFilter

public String[] getIncludeTypesFilter()

Return the types filter array of type names. Null if not set.

Returns:

list of type names to filter on

setIncludeTypesFilter

public <T extends LeoBaseAnnotator> T setIncludeTypesFilter(String... includeTypesFilterNames)

Set one or more types to filter on.

Parameters:

includeTypesFilterNames - One or more type names to filter on

Returns:

reference to this annotation instance

getExcludeTypesFilter

public String[] getExcludeTypesFilter()

Get the exclude types list.

Returns:

exclude types list

setExcludeTypesFilter

public <T extends LeoBaseAnnotator> T setExcludeTypesFilter(String... excludeTypesFilterNames)

Set the list of exclude types.

Parameters:

excludeTypesFilterNames - one or more type names to exclude

Returns:

reference to this annotation instance

initialize

public void initialize(org.apache.uima.UimaContext aContext)
                throws org.apache.uima.resource.ResourceInitializationException

Initialize this annotator.

Specified by:

initialize in interface org.apache.uima.analysis_component.AnalysisComponent

Overrides:

initialize in class org.apache.uima.analysis_component.AnalysisComponent_ImplBase

Parameters:

aContext - the UimaContext to initialize with.

Throws:

org.apache.uima.resource.ResourceInitializationException

See Also:

AnalysisComponent_ImplBase.initialize(org.apache.uima.UimaContext)

getResourceAsInputStream

public InputStream getResourceAsInputStream(String resourcePath)
                                     throws IOException

Gets a resource as an input stream.

Note: Resource paths are specified via file: and classpath: to determine if the resource should be looked up in the file system or in the classpath. If file: or classpath: is not specified, file path is assumed.

Parameters:

resourcePath - the path to the resource to get the inputstream for.

Returns:

the input stream for the resource.

Throws:

IOException - if the input stream for the resource throws an exception.

getAnnotationListForType

protected org.apache.uima.cas.FSIterator<org.apache.uima.jcas.tcas.Annotation> getAnnotationListForType(org.apache.uima.jcas.JCas aJCas,
                                                                                                        String type)

Given a cas and type, return all of the annotations in the cas for that type.

Small helper method to make extending annotators more readable.

Parameters:

aJCas - the case

type - the type to get, ie gov.va.vinci.Token

Returns:

a list of annotations in the case matching that type. If none match, this is an empty iterator.

addOutputAnnotation

protected org.apache.uima.jcas.tcas.Annotation addOutputAnnotation(String outputType,
                                                                   org.apache.uima.jcas.JCas cas,
                                                                   int begin,
                                                                   int end)
                                                            throws org.apache.uima.analysis_engine.AnalysisEngineProcessException

Create an output annotation, and add it to the cas.

Parameters:

outputType - The classname of the type. ie- gov.va.vinci.Token

cas - The cas to add the output annotation to.

begin - the start index of the annotation

end - the end index of the annotation

Returns:

the created annotation.

Throws:

org.apache.uima.analysis_engine.AnalysisEngineProcessException - If any exception occurs when getting and instantiating the output annotation type, this exception is thrown with the real exception inside of it. (analysisEngineProcessException.getCause());

addOutputAnnotation

protected org.apache.uima.jcas.tcas.Annotation addOutputAnnotation(String outputType,
                                                                   org.apache.uima.jcas.JCas cas,
                                                                   int begin,
                                                                   int end,
                                                                   Map<String,Object> featureNameValues)
                                                            throws org.apache.uima.analysis_engine.AnalysisEngineProcessException

Create an output annotation, and add it to the cas.

Parameters:

outputType - The classname of the type. ie- gov.va.vinci.Token

cas - The cas to add the output annotation to.

begin - the start index of the annotation

end - the end index of the annotation

featureNameValues - a map of feature names and associated values to set on the annotation.

Returns:

the created annotation.

Throws:

org.apache.uima.analysis_engine.AnalysisEngineProcessException - If any exception occurs when getting and instantiating the output annotation type, this exception is thrown with the real exception inside of it. (analysisEngineProcessException.getCause());

getResourceFileAsString

public String getResourceFileAsString(String resourcePath)
                               throws IOException

Note: Resource paths are specified via file: and classpath: to determine if the resource should be looked up in the file system or in the classpath. If file: or classpath: is not specified, file path is assumed.

The resource is found, and the contents of the resource returned as a string.

Parameters:

resourcePath - the path to the resource to get

Returns:

the resource loaded into a string

Throws:

IOException - if the input stream for the resource throws an exception.

getNumberOfCASesProcessed

public long getNumberOfCASesProcessed()

Get the number of CASes this annotator has processed.

Returns:

the number of CASes processed.

resetNumberOfCASesProcessed

public <T extends LeoBaseAnnotator> T resetNumberOfCASesProcessed()

Set the number of CASes this annotator has processed.

getNumberOfFilteredCASesProcessed

public long getNumberOfFilteredCASesProcessed()

Get the number of CASes that were processed once getting through the filter.

Returns:

number of filtered CASes processed

resetNumberOfFilteredCASesProcessed

public <T extends LeoBaseAnnotator> T resetNumberOfFilteredCASesProcessed()

Reset the number of filtered CASes processed.

Returns:

reference to this

process

public final void process(org.apache.uima.jcas.JCas aJCas)
                   throws org.apache.uima.analysis_engine.AnalysisEngineProcessException

Called once by the UIMA Framework for each document being analyzed (each CAS instance). Acts on the parameters given by method. Main method to implement the annotator logic. In the base class, this simply increments to numberOfCASesProcessed

Specified by:

process in class org.apache.uima.analysis_component.JCasAnnotator_ImplBase

Parameters:

aJCas - the CAS to process

Throws:

org.apache.uima.analysis_engine.AnalysisEngineProcessException - if an exception occurs during processing.

See Also:

JCasAnnotator_ImplBase.process(org.apache.uima.jcas.JCas)

annotate

public abstract void annotate(org.apache.uima.jcas.JCas aJCas)
                       throws org.apache.uima.analysis_engine.AnalysisEngineProcessException

This method is called by the LeoBaseAnnotator process method if the CAS meets the filter requirements and either has not input types defined or else contains one or more instances of the input types.

Parameters:

aJCas - CAS for processing

Throws:

org.apache.uima.analysis_engine.AnalysisEngineProcessException - if there is an error processing the CAS

collectionProcessComplete

public void collectionProcessComplete()
                               throws org.apache.uima.analysis_engine.AnalysisEngineProcessException

Specified by:

collectionProcessComplete in interface org.apache.uima.analysis_component.AnalysisComponent

Overrides:

collectionProcessComplete in class org.apache.uima.analysis_component.AnalysisComponent_ImplBase

Throws:

org.apache.uima.analysis_engine.AnalysisEngineProcessException

hasFilteredAnnotation

protected boolean hasFilteredAnnotation(org.apache.uima.jcas.JCas jCas)
                                 throws org.apache.uima.analysis_engine.AnalysisEngineProcessException

If includeTypesFilter is not set then return true. If there is a includeTypesFilter and includeFilter is true then return true only if one of the includeTypesFilter types have been found and false if not. If includeFilter is false then return true when all of the types in the filter list have not been found or true otherwise.

Parameters:

jCas - CAS to check for filtered types

Returns:

true if the filter is met, false otherwise

Throws:

org.apache.uima.analysis_engine.AnalysisEngineProcessException - if one of the type names in the tyepsFilter is not found in the type system

hasInputTypesAnnotation

protected boolean hasInputTypesAnnotation(org.apache.uima.jcas.JCas jCas)
                                   throws org.apache.uima.analysis_engine.AnalysisEngineProcessException

If the input types list is empty or one or more of the types are found in the CAS then return true, return false otherwise.

Parameters:

jCas - CAS to check

Returns:

true if types are found, false otherwise

Throws:

org.apache.uima.analysis_engine.AnalysisEngineProcessException - If one of the type names in the inputTypes list is not found in the type system

containsAnnotationInList

protected boolean containsAnnotationInList(org.apache.uima.jcas.JCas jCas,
                                           String[] typeList,
                                           boolean isEmpty)
                                    throws org.apache.uima.analysis_engine.AnalysisEngineProcessException

Checks the CAS for instances of the annotation types in the list. If the list is empty return the value of the isEmpty flag.

Parameters:

jCas - CAS to check

typeList - list of types to check for

isEmpty - if this list is empty then return the value of this boolean flag

Returns:

true if a type instance if found, false if not found, isEmpty if the list is empty

Throws:

org.apache.uima.analysis_engine.AnalysisEngineProcessException - If one of the types is not in the type system of the CAS

getDescriptor

public LeoDelegate getDescriptor()
                          throws Exception

Generate a descriptor from this annotator object. Parameters are grabbed from class variables and values with LeoConfigurationParameter annotations.

Specified by:

getDescriptor in interface LeoAnnotator

Returns:

descriptor for this annotator

Throws:

Exception - if there is an error getting the descriptor

getLeoAEDescriptor

public LeoAEDescriptor getLeoAEDescriptor()
                                   throws Exception

Generate a descriptor from this annotator object. Parameters are grabbed from class variables with LeoConfigurationParameter annotations.

Returns:

the descriptor for this annotator

Throws:

Exception - if there is an error getting the descriptor

getLeoTypeSystemDescription

public LeoTypeSystemDescription getLeoTypeSystemDescription()

Return the type system description for this annotator. Extending methods can add or set the variable typeSystemDescription to set a default type system description unique to that annotator.

Returns:

the default type system for this annotator.

addLeoTypeSystemDescription

public <T extends LeoBaseAnnotator> T addLeoTypeSystemDescription(LeoTypeSystemDescription typeSystemDescription)

Add the type system provided to the type system of the annotator.

Type Parameters:

T - delegate object reference for extending classes to support the builder pattern.

Parameters:

typeSystemDescription - LeoTypeSystemDescription to add.

Returns:

Reference to this object instance, supports the builder pattern.

setLeoTypeSystemDescription

public <T extends LeoBaseAnnotator> T setLeoTypeSystemDescription(LeoTypeSystemDescription typeSystemDescription)

Set the type system for this annotator. WARN: Replaces the existing type system without preserving it.

Type Parameters:

T - delegate object reference for extending classes to support the builder pattern.

Parameters:

typeSystemDescription - LeoTypeSystemDescription to use.

Returns:

Reference to this object instance, supports the builder pattern.