Class Subiterator<T extends AnnotationFS>

java.lang.Object
org.apache.uima.cas.impl.Subiterator<T>
All Implemented Interfaces:
Iterator<T>, ListIterator<T>, FSIterator<T>, LowLevelIterator<T>

public class Subiterator<T extends AnnotationFS> extends Object implements LowLevelIterator<T>
Subiterator implementation. There are 2 underlying forms. The 2nd form is produced lazily when needed, and is made by a one-time forward traversal to compute unambiguous subsets and store them into a list. - The 2nd form is needed only for unambiguous style if backwards or moveTo(fs), or moveToLast operations. The 1st form uses the underlying iterator directly, and does skipping as needed, while iterating - going forward: skip if unambiguous (noBound or coveredBy only) and start is within prev span skip if strict (coveredBy only) and end lies outside of scope span - going backward: if unambiguous - convert to form 2 skip if strict (coveredBy only) and end lies outside of scope span - going to particular fs (left most match) if unambiguous - convert to form 2 skip (forward) if strict (coveredBy only) and end lies outside of scope span - going to first: unambiguous - no testing needed, no prior span skip if strict and end lies outside of scope span - going to last: unambiguous - convert to 2nd form skip backwards if strict and end lies outside of scope span There are two styles of the bounding information. - the traditional one uses the standard comparator for annotations: begin (ascending), end (descending) and type priority ordering - the 2nd style uses just a begin value and an end value, no type priority ordering. Interaction with copy-on-write concurrent modification avoidance As with other iterators, the moveToFirst/Last/feature-structure-position "resets" the underlying iterators to match their current indexes. This implementation maintains local data: the list form and the isEmpty flag. These would also need recomputing for the above operations, if isIndexesHaveBeenUpdated() is true.
  • Field Details

    • list

      private ArrayList<Annotation> list
    • pos

      private int pos
    • it

      private final LowLevelIterator<Annotation> it
    • boundingAnnot

      private final Annotation boundingAnnot
      the bounding annotation need not be a subtype of T
    • boundBegin

      private final int boundBegin
    • boundEnd

      private final int boundEnd
    • originalBoundingAnnotation

      private final Annotation originalBoundingAnnotation
    • originalBoundBegin

      private final int originalBoundBegin
    • originalBoundEnd

      private final int originalBoundEnd
    • boundType

      private final TypeImpl boundType
    • coveringStartPos

      private final Annotation coveringStartPos
    • isUnambiguous

      private final boolean isUnambiguous
      true means need to skip until start is past prev end (going forward)
    • isStrict

      private final boolean isStrict
      only true for coveredby; means skip things while iterating where the end is outside the bounds
    • isBounded

      private final boolean isBounded
      true if bounds is one of sameBeginEnd, coveredBy, covering
    • isUseTypePriority

      private final boolean isUseTypePriority
      for moveTo-leftmost, and bounds skipping if isSkipEquals
    • isSkipSameBeginEndType

      private final boolean isSkipSameBeginEndType
      for bounds skipping alternative
    • isDoEqualsTest

      private final boolean isDoEqualsTest
    • boundsUse

      private final Subiterator.BoundsUse boundsUse
      one of notBounded, sameBeginEnd, coveredBy, covering
    • isIncludesAnnotationsStartingAtEndPosition

      private final boolean isIncludesAnnotationsStartingAtEndPosition
    • isIncludeZeroWidthAtBegin

      private final boolean isIncludeZeroWidthAtBegin
    • isIncludeZeroWidthAtEnd

      private final boolean isIncludeZeroWidthAtEnd
    • isEmpty

      private boolean isEmpty
      isEmpty is a potentially expensive calculation, involving potentially traversing all the iterators in a particular type hierarchy It is only done: - at init time - at moveToFirst/last/FS - these can cause regenerating the copy-on-write objects via the getNonNullCow call if no new nonNullCow was obtained, no need to recalculate empty
    • prevBegin

      private int prevBegin
    • prevEnd

      private int prevEnd
    • isListForm

      private boolean isListForm
      list form is recalculated at moveToFirst/last/fs, same as isEmpty
    • startId

      private int startId
      startId is recalculated at moveToFirst/last/fs, same as isEmpty
    • lto

      private final LinearTypeOrder lto
      null if ! isTypePriority
    • comparatorMaybeNoTypeWithoutId

      private final Comparator<TOP> comparatorMaybeNoTypeWithoutId
    • annotationComparator_withId

      private final Comparator<TOP> annotationComparator_withId
    • jcas

      private final JCasImpl jcas
  • Constructor Details

    • Subiterator

      Subiterator(FSIterator<T> it, AnnotationFS boundingAnnot, AnnotationFS originalBoundingAnnotation, boolean ambiguous, boolean strict, Subiterator.BoundsUse boundsUse, boolean isUseTypePriority, boolean isSkipSameBeginEndType, boolean isNonStrictIncludesAnnotationsStartingAtEndPosition, boolean isIncludeZeroWidthAtBegin, boolean isIncludeZeroWidthAtEnd)
      Caller is the implementation of AnnotationIndex, FSIndex_annotation. A normal iterator is passed in, already positioned to where things should start. A bounding FS is passed in (except for unbounded unambiguous iteration.
      Parameters:
      it - the iterator to use, positioned to the correct starting place
      boundingAnnot - null or the bounding annotation
      originalBoundingAnnotation - an original bounding annotation which will not be returned or not depending on the conditions for the bounding annotation to be returned. This can be useful if the original selection was converted to another selection type, e.g. when converting a following-selection to a covered-by selection under the condition that the original boundary of the following-selection (the start position) should be excluded. If set, the bounding type is obtained from this annotation instead of the bounding annotation
      ambiguous - false means to skip annotations whose begin lies between previously returned begin (inclusive) and end (exclusive)
      strict - true means to skip annotations whose end is greater than the bounding end position (ignoring type priorities)
      boundsUse - null if no bounds, boundingAnnot used for start position if non-null
      isUseTypePriority - false to ignore type priorities, and just use begin/end and maybe type
      isSkipSameBeginEndType - used only for coveredBy or covering case, false means to only skip returning an FS if it has the same id() as the bounding fs
      isIncludeZeroWidthAtBegin - for a covered-by selection to tell if a zero-width annotation at the start should be included.
      isIncludeZeroWidthAtEnd - for a covered-by selection to tell if a zero-width annotation at the start should be included.
    • Subiterator

      Subiterator(FSIterator<Annotation> it, Annotation boundingAnnot, Annotation originalBoundingAnnotation, boolean ambiguous, boolean strict, Subiterator.BoundsUse boundsUse, boolean isUseTypePriority, boolean isSkipSameBeginEndType, int startId, boolean isEmpty, Annotation coveringStartPos, boolean isDoEqualsTest, boolean isStrictIncludesAnnotationsStartingAtEndPosition, boolean isIncludeZeroWidthAtBegin, boolean isIncludeZeroWidthAtEnd)
      copy constructor - no move to start
      Parameters:
      it - -
      boundingAnnot - -
      ambiguous - -
      strict - -
      boundsUse - -
      isUseTypePriority - -
      isSkipSameBeginEndType - -
      startId - -
      isEmpty - -
  • Method Details

    • moveToStartSetEmptyAndId

      private void moveToStartSetEmptyAndId()
    • convertToListForm

      private void convertToListForm()
      Converting to list form - called for unambiguous iterator going backwards, unambiguous iterator doing a moveTo(fs) operation unambiguous iterator doing a moveToLast() operation
    • moveToStart

      private void moveToStart()
      Move to the starting position of the sub iterator.
    • isValid

      public boolean isValid()
      Description copied from interface: FSIterator
      Check if this iterator is valid.
      Specified by:
      isValid in interface FSIterator<T extends AnnotationFS>
      Returns:
      true if the iterator is valid.
    • getNvc

      public T getNvc()
      Description copied from interface: FSIterator
      Get the structure the iterator is pointing at. Throws various unchecked exceptions, if the iterator is not valid
      Specified by:
      getNvc in interface FSIterator<T extends AnnotationFS>
      Returns:
      The structure the iterator is pointing at.
    • moveToNextNvc

      public void moveToNextNvc()
      Description copied from interface: FSIterator
      version of moveToNext which bypasses the isValid check - call only if you've just done this check yourself
      Specified by:
      moveToNextNvc in interface FSIterator<T extends AnnotationFS>
    • moveToPreviousNvc

      public void moveToPreviousNvc()
      Description copied from interface: FSIterator
      version of moveToPrevious which bypasses the isValid check - call only if you've just done this check yourself
      Specified by:
      moveToPreviousNvc in interface FSIterator<T extends AnnotationFS>
    • moveToFirstNoReinit

      public void moveToFirstNoReinit()
      Description copied from interface: LowLevelIterator
      Internal use same as moveToFirst, but won't reset to use current contents of index if index has changed
      Specified by:
      moveToFirstNoReinit in interface LowLevelIterator<T extends AnnotationFS>
    • resetList

      private void resetList()
    • moveToLastNoReinit

      public void moveToLastNoReinit()
      Description copied from interface: LowLevelIterator
      Internal use same as moveToLast, but won't reset to use current contents of index if index has changed
      Specified by:
      moveToLastNoReinit in interface LowLevelIterator<T extends AnnotationFS>
    • moveToJustPastBoundsAndBackup

      private void moveToJustPastBoundsAndBackup(int begin, int end, Predicate<Annotation> continue_going_backwards)
      Called by move to Last (only) and only for non-empty iterators, to move to a place just beyond the last spot, and then backup while the goBackwards is true Includes adjustForStrictOrCoveringAndBoundSkip going backwards
      Parameters:
      begin - a position just past the last spot
      end - a position just past the last spot
      continue_going_backwards - when true, continue to backup
    • getAnnotationBeginEndComparator

      static Comparator<AnnotationFS> getAnnotationBeginEndComparator(int boundingBegin, int boundingEnd)
    • moveToNoReinit

      public void moveToNoReinit(FeatureStructure fs)
      Description copied from interface: LowLevelIterator
      Internal use same as moveTo(fs), but won't reset to use current contents of index if index has changed
      Specified by:
      moveToNoReinit in interface LowLevelIterator<T extends AnnotationFS>
      Parameters:
      fs - the fs to use as the template identifying the place to move to
    • moveTo_listForm

      private void moveTo_listForm(FeatureStructure fs)
    • moveTo_iterators

      private void moveTo_iterators(FeatureStructure fs, boolean initialPositioning)
      Move the sub iterator to the given position. isEmpty may not yet be set. Never list form when called. Mimics regular iterators when moveToStart moves the underlying iterator to a valid position in front of a bound which is limiting on the left (coveredBy, sameBeginEnd)
    • is_beyond_bounds_chk_sameBeginEnd

      private boolean is_beyond_bounds_chk_sameBeginEnd()
      Returns:
      true if iterator was outside - beyond, and therefore, made invalid or iterator is invalid to start with
    • is_beyond_bounds_chk_sameBeginEndNvc

      private boolean is_beyond_bounds_chk_sameBeginEndNvc()
    • is_beyond_bounds_chk_coveredByNvc

      private boolean is_beyond_bounds_chk_coveredByNvc()
      Returns:
      true if iterator was outside - beyond, and therefore, made invalid or iterator is invalid to start with
    • is_beyond_bounds_chk_covering

      private boolean is_beyond_bounds_chk_covering()
      Returns:
      true if iterator was outside - beyond, and therefore, made invalid or iterator is invalid to start with For covering case, if the annotation is equal to the bounding one, it's considered outside. Use case: a bunch of same begin / end, one in middle is bounding one, and move To is to left of it, or to right of it , without typePriorities to left: is ok, to right, is outside but without type priorities, all are considered == to the bound
    • is_beyond_bounds_chk_coveringNvc

      private boolean is_beyond_bounds_chk_coveringNvc()
    • maybeAdjustForAmbiguityAndIgnoringTypePriorities_forward

      private void maybeAdjustForAmbiguityAndIgnoringTypePriorities_forward(boolean oneStepOnly)
    • coveredByBounds

      private boolean coveredByBounds(Annotation ann)
    • adjustForStrictOrCoveringAndBoundSkip

      private boolean adjustForStrictOrCoveringAndBoundSkip(boolean oneStepOnly)
      Skip over annotations which are not valid for the given bounds use. This can be used in two cases.
      • Seeking backwards from the current to the first valid annotation relative to the beginning of the index.
      • Seeking backwards from the current position to the first valid annotation relative to the current position.
    • equalToBounds

      private boolean equalToBounds(Annotation fs)
      Special equalToBounds used only for having bounded iterators skip returning the bounding annotation Two styles: uimaFIT style: only skip the exact one (id's the same) uima style: skip all that compare equal using the AnnotationIndex comparator
      Parameters:
      fs - -
      Returns:
      true if should be skipped
    • maybeSetPrevBounds

      private void maybeSetPrevBounds()
    • adjustForStrictNvc_forward

      private boolean adjustForStrictNvc_forward()
      Returns:
      true if iterator still valid, false if not valid
    • adjustForCovering_forward

      private void adjustForCovering_forward()
      Assume: on entry the subiterator might not be in a "valid" position Case: moveToJustPastBoundsAndBackup... Adjust: skip over annotations whose "end" is invalid input: '<' bound end, or whose end is == to bound end and begin == bound begin and linearTypeOrder exists, and annotation lessThan the bound type. Marks iterator invalid if moves beyond bound when covering (which is different from coveredBy and sameBeginEnd, means get all annotations which span the bounds), skip items where the end invalid input: '<' bounds end, because those items don't span the bounding FS Edge case: item with same begin and end is considered "covering" but subject to exclusion based on equalToBounds skipping Cases: position of begin is after span begin - mark "invalid" position of begin is before or == span begin: position of end is == or > span end: OK (except if begin is ==, then do lto check) position of end is invalid input: '<' span end: if backward: moveToPrev until get valid position or run out. if run out, mark invalid if forward: move to next while position of begin is invalid input: '<'= span begin.
    • maybeMoveToPrevBounded

      private void maybeMoveToPrevBounded()
      Assume: iterator is valid
    • copy

      public FSIterator<T> copy()
      Description copied from interface: FSIterator
      Copy this iterator.
      Specified by:
      copy in interface FSIterator<T extends AnnotationFS>
      Returns:
      A copy of this iterator, pointing at the same element.
    • ll_indexSizeMaybeNotCurrent

      public int ll_indexSizeMaybeNotCurrent()
      This is unsupported because its expensive to compute in many cases, and may not be needed.
      Specified by:
      ll_indexSizeMaybeNotCurrent in interface LowLevelIterator<T extends AnnotationFS>
      Returns:
      The size of the index. In case of copy-on-write, this returns the size of the index at the time the iterator was created, or at the last moveTo, moveToFirst, or moveToLast. To get the current index size, use ll_getIndex().getSize()
    • ll_maxAnnotSpan

      public int ll_maxAnnotSpan()
      Specified by:
      ll_maxAnnotSpan in interface LowLevelIterator<T extends AnnotationFS>
      Returns:
      an estimate of the maximum span over all annotations (end - begin)
    • ll_getIndex

      public LowLevelIndex<T> ll_getIndex()
      Description copied from interface: LowLevelIterator
      Get the index for just the top most type of this iterator (excludes subtypes).
      Specified by:
      ll_getIndex in interface LowLevelIterator<T extends AnnotationFS>
      Returns:
      The index.
    • makeInvalid

      private void makeInvalid()
    • isIndexesHaveBeenUpdated

      public boolean isIndexesHaveBeenUpdated()
      Used to determine when some precomputed things (e.g. listform) need to be recalculated
      Specified by:
      isIndexesHaveBeenUpdated in interface LowLevelIterator<T extends AnnotationFS>
      Returns:
      true if one or more of the underlying indexes of the underlying iterator have been updated
    • maybeReinitIterator

      public boolean maybeReinitIterator()
      Description copied from interface: LowLevelIterator
      Internal use
      Specified by:
      maybeReinitIterator in interface LowLevelIterator<T extends AnnotationFS>
      Returns:
      true if the iterator was refreshed to match the current index
    • getComparator

      public Comparator<TOP> getComparator()
      Specified by:
      getComparator in interface LowLevelIterator<T extends AnnotationFS>
      Returns:
      the comparator used by this iterator. It is always a withoutID style, and may be either a withType or NoType style.