Class DocumentAnnotators
DocumentAnnotator implementations: the
required-layer and layer-alignment checks, the per-sentence walk over the token
layer, and the mapping of sentence-relative token spans onto character spans.
These helpers keep the annotators' shared behavior identical across implementations: an absent required layer is always rejected with the same message naming the layer, and every per-sentence adapter applies the same sentence-to-token mapping, including the loud rejection of a token lying outside every sentence.
- Since:
- 3.0.0
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interfaceReceives one sentence's contiguous token run duringforEachSentence(List, List, SentenceTokenConsumer). -
Method Summary
Modifier and TypeMethodDescriptionstatic voidforEachSentence(List<Annotation<String>> sentences, List<Annotation<String>> tokens, DocumentAnnotators.SentenceTokenConsumer consumer) Walks the token layer sentence by sentence and hands each sentence's contiguous token run to the consumer.static voidrequireAligned(Document document, LayerKey<?> layer, LayerKey<?> aligned) Verifies that two layers of a document hold the same number of annotations, so the annotation at each position of one belongs to the annotation at the same position of the other.static voidrequireLayers(Document document, LayerKey<?>... layers) Verifies that a document is present and carries every given layer.static SpantoCharacterSpan(List<Annotation<String>> tokens, int first, int count, Span span, String source) Maps a span over one sentence's tokens onto the character span those tokens cover.static String[]values(List<Annotation<String>> layer, int first, int count) Collects the values of a contiguous run of annotations, for example the tags of one sentence's tokens duringforEachSentence(List, List, SentenceTokenConsumer).
-
Method Details
-
requireLayers
Verifies that a document is present and carries every given layer.- Parameters:
document- The document to check.layers- The required layers, in the order they are to be reported.- Throws:
IllegalArgumentException- Thrown ifdocumentisnull, or if a layer is absent; the message names the first absent layer.
-
forEachSentence
public static void forEachSentence(List<Annotation<String>> sentences, List<Annotation<String>> tokens, DocumentAnnotators.SentenceTokenConsumer consumer) Walks the token layer sentence by sentence and hands each sentence's contiguous token run to the consumer.Both layers must be in text order. Each sentence consumes the contiguous run of tokens whose spans it encloses; a sentence without tokens is skipped. Every token must belong to a sentence: a token lying outside every sentence is rejected loudly after the walk, so it can never be silently dropped.
- Parameters:
sentences- The sentence layer, in text order. Must not benull.tokens- The token layer, in text order. Must not benull.consumer- Receives each token-carrying sentence's run. Must not benull.- Throws:
IllegalArgumentException- Thrown ifsentences,tokensorconsumerisnull, or if a token lies outside every sentence.
-
requireAligned
Verifies that two layers of a document hold the same number of annotations, so the annotation at each position of one belongs to the annotation at the same position of the other.- Parameters:
document- The document to check. Must not benull.layer- The first layer, for exampleLayers.TOKENS.aligned- The layer that must be aligned withlayer, for exampleLayers.POS_TAGS.- Throws:
IllegalArgumentException- Thrown ifdocumentisnull, if a layer is absent, or if the two layers differ in size; the message names the absent layer, or both layers.
-
values
Collects the values of a contiguous run of annotations, for example the tags of one sentence's tokens duringforEachSentence(List, List, SentenceTokenConsumer).- Parameters:
layer- The layer to read. Must not benull.first- The position of the run's first annotation inlayer.count- The number of annotations in the run.- Returns:
- The values at the layer positions
[first, first + count), in layer order. Nevernull. - Throws:
IllegalArgumentException- Thrown iflayerisnull, or if the run does not lie inside the layer.
-
toCharacterSpan
public static Span toCharacterSpan(List<Annotation<String>> tokens, int first, int count, Span span, String source) Maps a span over one sentence's tokens onto the character span those tokens cover.A sentence-level component such as a chunker or a name finder indexes the tokens within the sentence. The span is shifted by the sentence's first token position and resolved through the token layer, whose spans already refer to the original text, so the result runs from the start of the span's first token to the end of its last token. An empty span covers no token and therefore has no character span; it is rejected together with the out-of-bounds ones.
- Parameters:
tokens- The token layer. Must not benull.first- The position of the sentence's first token intokens.count- The number of tokens in the sentence.span- The span over the sentence's tokens, with an exclusive end. Must not benull.source- How the rejection message introducesspan, for example"chunker returned chunk". Must not benull.- Returns:
- The character span covered by the tokens, without a type. Never
null. - Throws:
IllegalArgumentException- Thrown if an argument isnull, if the sentence does not lie insidetokens, or ifspanis empty or reaches outside the sentence'scounttokens; the message for a rejected span starts withsource.
-