edu.illinois.cs.cogcomp.annotation

Class BasicAnnotatorService

java.lang.Object

edu.illinois.cs.cogcomp.annotation.BasicAnnotatorService

All Implemented Interfaces:

AnnotatorService

Direct Known Subclasses:

SentencePipeline

public class BasicAnnotatorService
extends Object
implements AnnotatorService

This class defines the behavior of an annotation service that can be fulfilled by an arbitrary backend, and which will cache the annotations so fulfilled. Sentence and Token views are populated by the TextAnnotationBuilder object passed to the constructor. By default, only Annotators provided as 'viewProviders' will be applied to input text. Their dependencies will be (minimally) checked to make sure a requested view has its required inputs provided. By default, all annotation views are cached. The constructor provides default values for caching behavior (see the default values), but these can be overridden by providing a ResourceManager (and configuration file) that specifies these values.

Many Annotators are likely to be singletons to avoid memory overload. AnnotatorService can be subclassed to provide homespun views without creating Annotator classes, though probably the latter is the better way to go. There is at least one use case that motivates this design -- backward compatibility with Curator to replace CuratorClient/CachingCuratorClient.

Author:

Mark Sammons, Christos Christodoulopoulos, Narender Gupta Created by mssammon on 4/13/15.

Field Summary

Fields

Modifier and Type	Field and Description
protected TextAnnotationCache	annotationCache
protected boolean	disableCache
protected boolean	forceUpdate
protected TextAnnotationBuilder	textAnnotationBuilder provides tokenization and sentence splitting to create a basic TextAnnotation object from plain text String.
protected boolean	throwExceptionIfNotCached used when processing a corpus and then using it in experiments -- if 'true', you will know in the experimental run that a data element is missing.
protected Map<String,Annotator>	viewProviders A way to define externally provided views.

Constructor Summary

Constructors

Constructor and Description
BasicAnnotatorService(TextAnnotationBuilder textAnnotationBuilder, Map<String,Annotator> viewProviders) constructor that uses AnnotatorServiceConfigurator default configuration
BasicAnnotatorService(TextAnnotationBuilder textAnnotationBuilder, Map<String,Annotator> viewProviders, ResourceManager rm) constructor with ResourceManager properties for caching behavior
BasicAnnotatorService(TextAnnotationBuilder textAnnotationBuilder, Map<String,Annotator> viewProviders, String cacheFile, boolean throwExceptionIfNotCached, boolean disableCache, boolean forceUpdate) Populates the AnnotatorService with View providers and initializes cache manager, if caching enabled.

Method Summary

Modifier and Type	Method and Description
void	addAnnotator(Annotator annotator) Add a new Annotator to the service.
boolean	addView(TextAnnotation textAnnotation, String viewName) DOES NOT CACHE THE ADDED VIEW!!!
TextAnnotation	addViewsAndCache(TextAnnotation ta, Set<String> viewsToAnnotate, boolean clientForceUpdate) add all the specified views to the specified TextAnnotation and cache it.
TextAnnotation	annotateTextAnnotation(TextAnnotation ta, boolean replaceExistingViews) Add the specified views to the TextAnnotation argument.
TextAnnotation	createAnnotatedTextAnnotation(String corpusId, String textId, String text) Creates a TextAnnotation with all annotators provided to this AnnotatorService.
TextAnnotation	createAnnotatedTextAnnotation(String corpusId, String textId, String text, Set<String> viewsToAnnotate) An overloaded version of AnnotatorService.createAnnotatedTextAnnotation(String, String, String) that adds only the Views requested.
TextAnnotation	createAnnotatedTextAnnotation(String corpusId, String textId, String text, Tokenizer.Tokenization tokenization) A convenience method for creating a TextAnnotation and adding all the Views supported by this AnnotatorService.
TextAnnotation	createAnnotatedTextAnnotation(String corpusId, String textId, String text, Tokenizer.Tokenization tokenization, Set<String> viewNames) An overloaded version of createAnnotatedTextAnnotation(String, String, String) that adds only the Views requested.
TextAnnotation	createBasicTextAnnotation(String corpusId, String docId, String text) Creates a basic TextAnnotation with sentence and token views with the pre-tokenized text by using the TextAnnotationBuilder.
TextAnnotation	createBasicTextAnnotation(String corpusId, String docId, String text, Tokenizer.Tokenization tokenization) A convenience method for creating a TextAnnotation while respecting the pre-tokenization of text passed in the form of Tokenizer.Tokenization.
Set<String>	getAvailableViews() Return a set containing the names of all Views that this service can provide.
protected void	throwNotCachedException(String corpusId, String docId, String text)

Methods inherited from class java.lang.Object

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

Field Detail

annotationCache

protected TextAnnotationCache annotationCache

disableCache

protected boolean disableCache

throwExceptionIfNotCached

protected boolean throwExceptionIfNotCached

used when processing a corpus and then using it in experiments -- if 'true', you will know in the experimental run that a data element is missing.

textAnnotationBuilder

protected TextAnnotationBuilder textAnnotationBuilder

provides tokenization and sentence splitting to create a basic TextAnnotation object from plain text String.

viewProviders

protected Map<String,Annotator> viewProviders

A way to define externally provided views. Each view provider needs to implement Annotator.

forceUpdate

protected boolean forceUpdate

Constructor Detail

BasicAnnotatorService

public BasicAnnotatorService(TextAnnotationBuilder textAnnotationBuilder,
                             Map<String,Annotator> viewProviders,
                             ResourceManager rm)
                      throws AnnotatorException

constructor with ResourceManager properties for caching behavior

Parameters:

textAnnotationBuilder - tokenizes and sentence splits input text.

viewProviders - Annotators that populate a View with the same name as the corresponding Annotator key.

rm - A ResourceManager containing cache configuration options.

Throws:

AnnotatorException

BasicAnnotatorService

public BasicAnnotatorService(TextAnnotationBuilder textAnnotationBuilder,
                             Map<String,Annotator> viewProviders)
                      throws AnnotatorException

constructor that uses AnnotatorServiceConfigurator default configuration

Parameters:

textAnnotationBuilder - object that will build basic TextAnnotation objects

viewProviders - annotators that will populate views in new TextAnnotation objects

Throws:

AnnotatorException

BasicAnnotatorService

public BasicAnnotatorService(TextAnnotationBuilder textAnnotationBuilder,
                             Map<String,Annotator> viewProviders,
                             String cacheFile,
                             boolean throwExceptionIfNotCached,
                             boolean disableCache,
                             boolean forceUpdate)
                      throws AnnotatorException

Populates the AnnotatorService with View providers and initializes cache manager, if caching enabled.

Parameters:

textAnnotationBuilder - tokenizes and sentence splits input text.

viewProviders - Annotators that populate a View with the same name as the corresponding Annotator key.

cacheFile - Where the AnnotatorService should write the cache. IMPORTANT: multiple VMs may NOT share a single cache location.

throwExceptionIfNotCached - if 'true', throw an exception if no cached value is found.

Throws:

AnnotatorException

Method Detail

createBasicTextAnnotation

public TextAnnotation createBasicTextAnnotation(String corpusId,
                                                String docId,
                                                String text)
                                         throws AnnotatorException

Creates a basic TextAnnotation with sentence and token views with the pre-tokenized text by using the TextAnnotationBuilder. Note that this method works only with BasicTextAnnotationBuilder. DOES NOT CACHE THIS BASIC TEXT ANNOTATION.

Specified by:

createBasicTextAnnotation in interface AnnotatorService

Parameters:

corpusId - The name of the data set to associate with this text

docId - document id to associate with this text

text - The raw text

Throws:

AnnotatorException

createBasicTextAnnotation

public TextAnnotation createBasicTextAnnotation(String corpusId,
                                                String docId,
                                                String text,
                                                Tokenizer.Tokenization tokenization)
                                         throws AnnotatorException

A convenience method for creating a TextAnnotation while respecting the pre-tokenization of text passed in the form of Tokenizer.Tokenization.

Specified by:

createBasicTextAnnotation in interface AnnotatorService

Parameters:

corpusId -

docId -

text - The raw text

tokenization - An instance of Tokenizer.Tokenization which contains tokens, character offsets, and sentence boundaries to be used while constructing the TextAnnotation. @throws AnnotatorException If the service cannot create requested object

Throws:

AnnotatorException - If the service cannot create requested object

createAnnotatedTextAnnotation

public TextAnnotation createAnnotatedTextAnnotation(String corpusId,
                                                    String textId,
                                                    String text)
                                             throws AnnotatorException

Creates a TextAnnotation with all annotators provided to this AnnotatorService.

Specified by:

createAnnotatedTextAnnotation in interface AnnotatorService

Parameters:

corpusId - corpus name to associate with this text/TextAnnotation.

textId - document id to associate with this text/TextAnnotation.

text - The raw text used to build the TextAnnotation where all the Views should be added.

Returns:

a TextAnnotation with all possible Views populated.

Throws:

AnnotatorException

createAnnotatedTextAnnotation

public TextAnnotation createAnnotatedTextAnnotation(String corpusId,
                                                    String textId,
                                                    String text,
                                                    Tokenizer.Tokenization tokenization)
                                             throws AnnotatorException

A convenience method for creating a TextAnnotation and adding all the Views supported by this AnnotatorService. This amounts to calling createBasicTextAnnotation(String, String, String, Tokenizer.Tokenization) and successive calls of addView(edu.illinois.cs.cogcomp.core.datastructures.textannotation.TextAnnotation, String) . Note that this method works only with BasicTextAnnotationBuilder.

Specified by:

createAnnotatedTextAnnotation in interface AnnotatorService

Parameters:

text - The raw text

tokenization - An instance of Tokenizer.Tokenization which contains tokens, character offsets, and sentence boundaries to be used while constructing the TextAnnotation.

Returns:

Throws:

AnnotatorException

createAnnotatedTextAnnotation

public TextAnnotation createAnnotatedTextAnnotation(String corpusId,
                                                    String textId,
                                                    String text,
                                                    Tokenizer.Tokenization tokenization,
                                                    Set<String> viewNames)
                                             throws AnnotatorException

An overloaded version of createAnnotatedTextAnnotation(String, String, String) that adds only the Views requested. Note that this method works only with BasicTextAnnotationBuilder.

Specified by:

createAnnotatedTextAnnotation in interface AnnotatorService

Parameters:

text - The raw text

tokenization - An instance of Tokenizer.Tokenization which contains tokens, character offsets, and sentence boundaries to be used while constructing the TextAnnotation.

viewNames - Views to add

Returns:

Throws:

AnnotatorException

addAnnotator

public void addAnnotator(Annotator annotator)
                  throws AnnotatorException

Add a new Annotator to the service. All prerequisite views must already be provided by other annotators known to this AnnotatorService.

Specified by:

addAnnotator in interface AnnotatorService

Parameters:

annotator - the Annotator to be added.

Throws:

{@link - AnnotatorException} if the annotator requires views that cannot be satisfied.

AnnotatorException

getAvailableViews

public Set<String> getAvailableViews()

Return a set containing the names of all Views that this service can provide.

Specified by:

getAvailableViews in interface AnnotatorService

Returns:

a set of view names corresponding to annotators known to this AnnotatorService

annotateTextAnnotation

public TextAnnotation annotateTextAnnotation(TextAnnotation ta,
                                             boolean replaceExistingViews)
                                      throws AnnotatorException

Add the specified views to the TextAnnotation argument. This is useful when TextAnnotation objects are built independently of the service, perhaps by a different system component (e.g. a corpus reader). If so specified, overwrite existing views.

Specified by:

annotateTextAnnotation in interface AnnotatorService

Parameters:

ta - The TextAnnotation to annotate

replaceExistingViews - if 'true', annotate a View even if it is already present in the ta argument, replacing the original corresponding View.

Returns:

a reference to the updated TextAnnotation

Throws:

AnnotatorException

addView

public boolean addView(TextAnnotation textAnnotation,
                       String viewName)
                throws AnnotatorException

DOES NOT CACHE THE ADDED VIEW!!!

Specified by:

addView in interface AnnotatorService

Parameters:

textAnnotation - textAnnotation to be modified

viewName - name of view to be added

Returns:

'true' if textAnnotation was modified

Throws:

AnnotatorException

throwNotCachedException

protected void throwNotCachedException(String corpusId,
                                       String docId,
                                       String text)
                                throws AnnotatorException

Throws:

AnnotatorException

createAnnotatedTextAnnotation

public TextAnnotation createAnnotatedTextAnnotation(String corpusId,
                                                    String textId,
                                                    String text,
                                                    Set<String> viewsToAnnotate)
                                             throws AnnotatorException

Description copied from interface: AnnotatorService

An overloaded version of AnnotatorService.createAnnotatedTextAnnotation(String, String, String) that adds only the Views requested.

Specified by:

createAnnotatedTextAnnotation in interface AnnotatorService

text - The raw text used to build the TextAnnotation where all the Views should be added.

viewsToAnnotate - Views to add

Throws:

AnnotatorException - If none of the viewProviders supports this viewName

addViewsAndCache

public TextAnnotation addViewsAndCache(TextAnnotation ta,
                                       Set<String> viewsToAnnotate,
                                       boolean clientForceUpdate)
                                throws AnnotatorException

add all the specified views to the specified TextAnnotation and cache it. Will overwrite if so configured. IMPORTANT: if the corresponding TextAnnotation has already been cached, the argument is ignored. The client should ALWAYS use the returned TextAnnotation.

Parameters:

ta -

viewsToAnnotate -

Returns:

Throws:

AnnotatorException