Interface Document

public interface Document
An offset-anchored annotation container: the original text of one document plus any number of typed annotation layers over it.

A layer is a list of annotations identified by a LayerKey. The container itself knows nothing about specific layers; every analysis capability contributes its results as one more layer without any change to this interface, which is what keeps new capabilities additive. All spans refer to text() as supplied, never to a derived form. A document-scoped layer carries whole-document values without spans, for example a language id.

A document is never modified in place: with(LayerKey, List) leaves its receiver untouched and returns a new document. Thread safety is implementation specific.

Three invariants make index-based references sound. A layer preserves its insertion order, and the container never sorts or reorders it. A layer is immutable once added: the returned lists reject modification and are detached from the caller's input list. Providing a layer that already exists is rejected loudly: the add is once-only, and the exception names the offending key. An annotation that references another annotation by its index within a layer, for example a dependency arc naming its head token, therefore stays valid for the lifetime of the document.

Since:
3.0.0

  • Method Details

    • of

      static Document of(CharSequence text)
      Creates an empty Document over a text. The returned document is immutable and safe to share between threads: it captures the text's content at construction, so later changes to a mutable CharSequence do not reach the document.
      Parameters:
      text - The original document text. Must not be null.
      Returns:
      A Document without any layers. Never null.
      Throws:
      IllegalArgumentException - Thrown if text is null.

    • text

      CharSequence text()
      Returns:
      The original text of the document. Never null.

    • get

      <T> List<Annotation<T>> get(LayerKey<T> layer)
      Retrieves the annotations of one layer.
      Type Parameters:
      T - The type of the layer's annotation values.
      Parameters:
      layer - The layer to read. Must not be null.
      Returns:
      The layer's annotations in their layer order, or an empty list when the layer is absent. Never null; the list is unmodifiable.
      Throws:
      IllegalArgumentException - Thrown if layer is null.

    • layers

      Set<LayerKey<?>> layers()
      Returns:
      The keys of all layers present on the document. Never null; the set is unmodifiable.

    • with

      <T> Document with(LayerKey<T> layer, List<Annotation<T>> annotations)
      Returns a new document with one layer added.
      Type Parameters:
      T - The type of the layer's annotation values.
      Parameters:
      layer - The key of the layer to add. Must not be null and must not already be present.
      annotations - The annotations of the layer. Must not be null, must not contain null, and every value must be assignable to the layer's type. Under a positional key every annotation must carry a span within the text bounds; under a document-scoped key no annotation may carry a span.
      Returns:
      A new Document sharing this document's text and existing layers. Never null.
      Throws:
      IllegalArgumentException - Thrown if any of the above constraints is violated.

    • merge

      default Document merge(Document other)
      Returns a new document combining this document's layers with another document's layers over the same text, joining documents grown independently, for example by pipelines that ran in parallel.
      Parameters:
      other - The document whose layers are added on top of this document's layers. Must not be null, must carry the same text content, and must not provide a layer this document already has.
      Returns:
      A new Document carrying the layers of both documents. Never null; both source documents are left untouched.
      Throws:
      IllegalArgumentException - Thrown if other is null, if its text content differs, or if a layer key is present on both documents; the exception names the offending key.

    • merge

      default Document merge(Document other, Document.DuplicateLayerPolicy duplicateLayers)
      Returns a new document combining this document's layers with another document's layers over the same text, resolving duplicate layer keys with duplicateLayers.
      Parameters:
      other - The document whose layers are added on top of this document's layers. Must not be null and must carry the same text content.
      duplicateLayers - How to treat a layer key present on both documents. Must not be null.
      Returns:
      A new Document carrying the layers of both documents. Never null; both source documents are left untouched.
      Throws:
      IllegalArgumentException - Thrown if either argument is null, if the text content differs, or if a layer key is present on both documents and the policy does not keep it; the exception names the offending key.