Class DocumentAnnotators

java.lang.Object
opennlp.tools.document.DocumentAnnotators

public final class DocumentAnnotators extends Object
Support methods shared by 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
  • Method Details

    • requireLayers

      public static void requireLayers(Document document, LayerKey<?>... layers)
      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 if document is null, 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 be null.
      tokens - The token layer, in text order. Must not be null.
      consumer - Receives each token-carrying sentence's run. Must not be null.
      Throws:
      IllegalArgumentException - Thrown if sentences, tokens or consumer is null, or if a token lies outside every sentence.
    • requireAligned

      public static void requireAligned(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.
      Parameters:
      document - The document to check. Must not be null.
      layer - The first layer, for example Layers.TOKENS.
      aligned - The layer that must be aligned with layer, for example Layers.POS_TAGS.
      Throws:
      IllegalArgumentException - Thrown if document is null, if a layer is absent, or if the two layers differ in size; the message names the absent layer, or both layers.
    • values

      public 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 during forEachSentence(List, List, SentenceTokenConsumer).
      Parameters:
      layer - The layer to read. Must not be null.
      first - The position of the run's first annotation in layer.
      count - The number of annotations in the run.
      Returns:
      The values at the layer positions [first, first + count), in layer order. Never null.
      Throws:
      IllegalArgumentException - Thrown if layer is null, 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 be null.
      first - The position of the sentence's first token in tokens.
      count - The number of tokens in the sentence.
      span - The span over the sentence's tokens, with an exclusive end. Must not be null.
      source - How the rejection message introduces span, for example "chunker returned chunk". Must not be null.
      Returns:
      The character span covered by the tokens, without a type. Never null.
      Throws:
      IllegalArgumentException - Thrown if an argument is null, if the sentence does not lie inside tokens, or if span is empty or reaches outside the sentence's count tokens; the message for a rejected span starts with source.