gate.mimir

Interface SemanticAnnotationHelper

All Superinterfaces:

Serializable

All Known Implementing Classes:

AbstractSemanticAnnotationHelper, DelegatingSemanticAnnotationHelper

public interface SemanticAnnotationHelper
extends Serializable

Interface for classes that convert annotations into semantic metadata. At indexing time, for each annotation to be indexed, the helper produces a set of mentions URIs (obtained by calling #getMentionUris(Annotation, int, Indexer)). At search time, given a set of constraints, the helper produces set of <mention URIs, mention length> pairs (obtained by calling on of the getMentions(String, List, QueryEngine), getMentions(String, Map, QueryEngine) methods).
Each helper can function in annotation mode (the default) or in document mode. The current functioning mode can be obtained by calling #isInDocumentMode(). When in document mode, the helper should behave as if a single annotation covering the whole document span is being indexed (or searched for). In this mode, document features are used instead of annotation features. This has efficiency advantages over actually creating a document-spanning annotation, as the implementations can avoid actually storing the annotation length in the index (as it is always the same as the document length).

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	SemanticAnnotationHelper.Mode Functioning mode for the annotation helper.

Method Summary

Modifier and Type	Method and Description
void	close(AtomicAnnotationIndex index) Closes this annotation helper.
void	close(QueryEngine qEngine) Closes this annotation helper.
String	describeMention(String mentionUri) Provides a human-friendly representation of a mention, specified by the given URI.
void	documentEnd() Notifies this helper that the current document has finished.
void	documentStart(gate.Document document) Prepares this helper for running on a new document.
List<Mention>	getMentions(String annotationType, List<Constraint> constraints, QueryEngine engine) This method supports searching for annotation mentions.
List<Mention>	getMentions(String annotationType, Map<String,String> constraints, QueryEngine engine) Convenience method: variant of getMentions(String, List, QueryEngine), where all constraints are of type ConstraintType.EQ.
String[]	getMentionUris(gate.Annotation annotation, int length, AtomicAnnotationIndex indexer) This method converts an annotation into the corresponding semantic metadata and returns the mention URIs corresponding to the original annotation.
SemanticAnnotationHelper.Mode	getMode() Checks whether this helper is configured to work in SemanticAnnotationHelper.Mode.ANNOTATION or SemanticAnnotationHelper.Mode.DOCUMENT mode.
void	init(AtomicAnnotationIndex index) Called by the containing MimirIndex when this helper is first created.
boolean	isMentionUri(String mentionUri) Checks whether the supplied string looks like a valid mention URI that may have been returned by a call to getMentions(String, List, QueryEngine) or getMentions(String, Map, QueryEngine).

Method Detail

init

void init(AtomicAnnotationIndex index)

Called by the containing MimirIndex when this helper is first created.

Parameters:

index - the AtomicAnnotationIndex this helpers is used by.

getMentionUris

String[] getMentionUris(gate.Annotation annotation,
                        int length,
                        AtomicAnnotationIndex indexer)

This method converts an annotation into the corresponding semantic metadata and returns the mention URIs corresponding to the original annotation.

Parameters:

annotation - the input annotation.

length - the length of the annotation (given as number of tokens).

Returns:

the URIs for the mention (created in the triple store) that are associated with the input annotation.

documentStart

void documentStart(gate.Document document)

Prepares this helper for running on a new document.

Parameters:

document - the new document.

documentEnd

void documentEnd()

Notifies this helper that the current document has finished.

getMentions

List<Mention> getMentions(String annotationType,
                          Map<String,String> constraints,
                          QueryEngine engine)

Convenience method: variant of getMentions(String, List, QueryEngine), where all constraints are of type ConstraintType.EQ.

Parameters:

annotationType - the annotation type.

constraints - constraints on the annotation's feature values.

engine - the QueryEngine in which this query will be running.

Returns:

the list of URIs for mentions that match the provided constraints.

getMentions

List<Mention> getMentions(String annotationType,
                          List<Constraint> constraints,
                          QueryEngine engine)

This method supports searching for annotation mentions. It is used to obtain all the mentions of the given annotation type that match the given constraints.

Parameters:

annotationType - the type of annotation required.

constraints - a list of constraints that the sough annotation should satisfy.

engine - the QueryEngine in which this query will be running.

Returns:

the list of URIs for mentions that match the provided constraints.

describeMention

String describeMention(String mentionUri)

Provides a human-friendly representation of a mention, specified by the given URI.

Parameters:

mentionUri - the mention URI, a string identical to the one that would be returned by one of the getMentions() methods. There is no requirement that the actual string value was previously obtained from a getMentions() call.

Returns:

a textual representation of the specified mention.

isMentionUri

boolean isMentionUri(String mentionUri)

Checks whether the supplied string looks like a valid mention URI that may have been returned by a call to getMentions(String, List, QueryEngine) or getMentions(String, Map, QueryEngine). Note that this is a superficial test that may be able to distinguish a URI produced by this helper from one produced by another. It will not actually access any data structure to check that the URI really is valid. The main use case for this call is to distinguish different URIs indexed in the same annotations index, but produced by different helpers.

Parameters:

mentionUri - the URI to test.

Returns:

true if this URI looks like an URI produced by this helper.

close

void close(AtomicAnnotationIndex index)

Closes this annotation helper. Implementers should perform maintenance operations (such as closing connections to ORDI, etc) on this call.

close

void close(QueryEngine qEngine)

Closes this annotation helper. Implementers should perform maintenance operations (such as closing connections to ORDI, etc) on this call.

getMode

SemanticAnnotationHelper.Mode getMode()

Checks whether this helper is configured to work in SemanticAnnotationHelper.Mode.ANNOTATION or SemanticAnnotationHelper.Mode.DOCUMENT mode.