Package org.apache.uima.cas.impl
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>
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.
-
Nested Class Summary
Nested Classes -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final Comparator
<TOP> private final int
private final int
private final Annotation
the bounding annotation need not be a subtype of Tprivate final Subiterator.BoundsUse
one of notBounded, sameBeginEnd, coveredBy, coveringprivate final TypeImpl
private final Comparator
<TOP> private final Annotation
private final boolean
true if bounds is one of sameBeginEnd, coveredBy, coveringprivate final boolean
private boolean
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 emptyprivate final boolean
private final boolean
private final boolean
private boolean
list form is recalculated at moveToFirst/last/fs, same as isEmptyprivate final boolean
for bounds skipping alternativeprivate final boolean
only true for coveredby; means skip things while iterating where the end is outside the boundsprivate final boolean
true means need to skip until start is past prev end (going forward)private final boolean
for moveTo-leftmost, and bounds skipping if isSkipEqualsprivate final LowLevelIterator
<Annotation> private final JCasImpl
private ArrayList
<Annotation> private final LinearTypeOrder
null if ! isTypePriorityprivate final int
private final int
private final Annotation
private int
private int
private int
private int
startId is recalculated at moveToFirst/last/fs, same as isEmptyFields inherited from interface org.apache.uima.cas.impl.LowLevelIterator
FS_ITERATOR_LOW_LEVEL_EMPTY, IS_ORDERED
-
Constructor Summary
ConstructorsConstructorDescriptionSubiterator
(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 startSubiterator
(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. -
Method Summary
Modifier and TypeMethodDescriptionprivate void
Assume: on entry the subiterator might not be in a "valid" position Case: moveToJustPastBoundsAndBackup...private boolean
private boolean
adjustForStrictOrCoveringAndBoundSkip
(boolean oneStepOnly) Skip over annotations which are not valid for the given bounds use.private void
Converting to list form - called for unambiguous iterator going backwards, unambiguous iterator doing a moveTo(fs) operation unambiguous iterator doing a moveToLast() operationcopy()
Copy this iterator.private boolean
private boolean
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(package private) static Comparator
<AnnotationFS> getAnnotationBeginEndComparator
(int boundingBegin, int boundingEnd) getNvc()
Get the structure the iterator is pointing at.private boolean
private boolean
private boolean
private boolean
private boolean
boolean
Used to determine when some precomputed things (e.g.boolean
isValid()
Check if this iterator is valid.Get the index for just the top most type of this iterator (excludes subtypes).int
This is unsupported because its expensive to compute in many cases, and may not be needed.int
private void
private void
maybeAdjustForAmbiguityAndIgnoringTypePriorities_forward
(boolean oneStepOnly) private void
Assume: iterator is validboolean
Internal useprivate void
private void
moveTo_iterators
(FeatureStructure fs, boolean initialPositioning) Move the sub iterator to the given position.private void
void
Internal use same as moveToFirst, but won't reset to use current contents of index if index has changedprivate 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 backwardsvoid
Internal use same as moveToLast, but won't reset to use current contents of index if index has changedvoid
version of moveToNext which bypasses the isValid check - call only if you've just done this check yourselfvoid
Internal use same as moveTo(fs), but won't reset to use current contents of index if index has changedvoid
version of moveToPrevious which bypasses the isValid check - call only if you've just done this check yourselfprivate void
Move to the starting position of the sub iterator.private void
private void
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface org.apache.uima.cas.FSIterator
add, get, getType, hasNext, hasPrevious, moveToNext, moveToPrevious, next, nextIndex, nextNvc, previous, previousIndex, previousNvc, remove, set, size, spliterator, stream
Methods inherited from interface java.util.Iterator
forEachRemaining
Methods inherited from interface org.apache.uima.cas.impl.LowLevelIterator
getArrayList, isMoveToSupported, ll_get, ll_remove, moveTo, moveTo, moveToFirst, moveToLast
-
Field Details
-
list
-
pos
private int pos -
it
-
boundingAnnot
the bounding annotation need not be a subtype of T -
boundBegin
private final int boundBegin -
boundEnd
private final int boundEnd -
originalBoundingAnnotation
-
originalBoundBegin
private final int originalBoundBegin -
originalBoundEnd
private final int originalBoundEnd -
boundType
-
coveringStartPos
-
isUnambiguous
private final boolean isUnambiguoustrue means need to skip until start is past prev end (going forward) -
isStrict
private final boolean isStrictonly true for coveredby; means skip things while iterating where the end is outside the bounds -
isBounded
private final boolean isBoundedtrue if bounds is one of sameBeginEnd, coveredBy, covering -
isUseTypePriority
private final boolean isUseTypePriorityfor moveTo-leftmost, and bounds skipping if isSkipEquals -
isSkipSameBeginEndType
private final boolean isSkipSameBeginEndTypefor bounds skipping alternative -
isDoEqualsTest
private final boolean isDoEqualsTest -
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 isEmptyisEmpty 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 isListFormlist form is recalculated at moveToFirst/last/fs, same as isEmpty -
startId
private int startIdstartId is recalculated at moveToFirst/last/fs, same as isEmpty -
lto
null if ! isTypePriority -
comparatorMaybeNoTypeWithoutId
-
annotationComparator_withId
-
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 placeboundingAnnot
- null or the bounding annotationoriginalBoundingAnnotation
- 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 annotationambiguous
- 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-nullisUseTypePriority
- false to ignore type priorities, and just use begin/end and maybe typeisSkipSameBeginEndType
- used only for coveredBy or covering case, false means to only skip returning an FS if it has the same id() as the bounding fsisIncludeZeroWidthAtBegin
- 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 interfaceFSIterator<T extends AnnotationFS>
- Returns:
true
if the iterator is valid.
-
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 interfaceFSIterator<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 interfaceFSIterator<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 interfaceFSIterator<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 interfaceLowLevelIterator<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 interfaceLowLevelIterator<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 spotend
- a position just past the last spotcontinue_going_backwards
- when true, continue to backup
-
getAnnotationBeginEndComparator
-
moveToNoReinit
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 interfaceLowLevelIterator<T extends AnnotationFS>
- Parameters:
fs
- the fs to use as the template identifying the place to move to
-
moveTo_listForm
-
moveTo_iterators
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
-
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
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
Description copied from interface:FSIterator
Copy this iterator.- Specified by:
copy
in interfaceFSIterator<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 interfaceLowLevelIterator<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 interfaceLowLevelIterator<T extends AnnotationFS>
- Returns:
- an estimate of the maximum span over all annotations (end - begin)
-
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 interfaceLowLevelIterator<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 interfaceLowLevelIterator<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 interfaceLowLevelIterator<T extends AnnotationFS>
- Returns:
- true if the iterator was refreshed to match the current index
-
getComparator
- Specified by:
getComparator
in interfaceLowLevelIterator<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.
-