AnnotationComboIterator (Apache OpenNLP UIMA Annotators 2.5.9 API)
Description: declaration: package: opennlp.uima.util, class: AnnotationComboIterator

# Class AnnotationComboIterator

java.lang.Object
opennlp.uima.util.AnnotationComboIterator

All Implemented Interfaces:
  `Iterable<AnnotationIteratorPair>, Iterator<AnnotationIteratorPair>`

public class AnnotationComboIterator extends Object implements Iterable<AnnotationIteratorPair>, Iterator<AnnotationIteratorPair>
UIMA Annotation iterator combination of super- and subiterator.

This class supports a common idiom in UIMA annotation iteration, where you need to iterate over two kinds of annotations in lock-step. For example, you often want to iterate over all sentences, then do something on each sentence and all tokens in that sentence. Here's how to do this with this class.

    CAS cas = ...
    Type sentenceType = ..., tokenType = ...
    // Init with CAS, upper and lower type.
    AnnotationComboIterator it = new AnnotationComboIterator(cas, sentenceType, tokenType);
    // Iterate over sentences
    for (AnnotationIteratorPair aiPair : it) {
      // Obtain sentence annotation
      AnnotationFS sentence = aiPair.getAnnotation();
      // Do something with sentence...

      // Iterate over tokens
      for (AnnotationFS token : aiPair.getSubIterator()) {
        // Do something with tokens...
      }
    }

The combo iterator returns in its `next()` method a pair of an annotation of the upper type (e.g., sentence), and an iterator over annotations of the lower type (e.g., tokens). Note that both the upper and lower iterator also implement the Iterable interface and can be use directly in for-loops.

Note that only this usage is safe. To keep the implementation efficient, the combo iterator keeps two iterators internally that it increments in lock-step. Do not attempt, for example, to collect more than one of the subiterators (token iterator in our example). Do not use this class if your intended usage does not fall into this pattern.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AnnotationComboIterator(org.apache.uima.cas.CAS cas, org.apache.uima.cas.Type upper, org.apache.uima.cas.Type lower)`
  Create a new combo iterator.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `hasNext()`
  `Iterator<AnnotationIteratorPair>`
  `iterator()`
  `AnnotationIteratorPair`
  `next()`
  `void`
  `remove()`
  Not supported.

  ### Methods inherited from class Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface Iterable

  `forEach, spliterator`

  ### Methods inherited from interface Iterator

  `forEachRemaining`

- ## Constructor Details

  - ### AnnotationComboIterator

    public AnnotationComboIterator(org.apache.uima.cas.CAS cas, org.apache.uima.cas.Type upper, org.apache.uima.cas.Type lower)
    Create a new combo iterator.
    Parameters:
      `cas` - The `CAS` we're operating on.
      `upper` - The `Type` of the upper iterator, e.g., sentence.
      `lower` - The `Type` of the lower iterator, e.g., token.

- ## Method Details

  - ### hasNext

    public boolean hasNext()
    Specified by:
      `hasNext` in interface `Iterator<AnnotationIteratorPair>`

  - ### next

    public AnnotationIteratorPair next()
    Specified by:
      `next` in interface `Iterator<AnnotationIteratorPair>`

  - ### iterator

    public Iterator<AnnotationIteratorPair> iterator()
    Specified by:
      `iterator` in interface `Iterable<AnnotationIteratorPair>`

  - ### remove

    public void remove()
    Not supported.
    Specified by:
      `remove` in interface `Iterator<AnnotationIteratorPair>`