Class Subiterator<T extends AnnotationFS>

  • All Implemented Interfaces:
    java.util.Iterator<T>, java.util.ListIterator<T>, FSIterator<T>, LowLevelIterator<T>

    public class Subiterator<T extends AnnotationFS>
    extends java.lang.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 Detail

      • list

        private java.util.ArrayList<Annotation> list
      • pos

        private int pos
      • 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
      • comparatorMaybeNoTypeWithoutId

        private final java.util.Comparator<TOP> comparatorMaybeNoTypeWithoutId
      • annotationComparator_withId

        private final java.util.Comparator<TOP> annotationComparator_withId
    • Constructor Detail

      • 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 Detail

      • 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>
      • resetList

        private void resetList()
      • moveToJustPastBoundsAndBackup

        private void moveToJustPastBoundsAndBackup​(int begin,
                                                   int end,
                                                   java.util.function.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 java.util.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_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 < 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 < 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 < 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 <= span begin.
      • maybeMoveToPrevBounded

        private void maybeMoveToPrevBounded()
        Assume: iterator is valid
      • 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()
      • 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
      • getComparator

        public java.util.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.