You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by sc...@apache.org on 2017/02/07 16:22:47 UTC
svn commit: r1782025 - in
/uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas:
SelectFSs.java impl/SelectFSs_impl.java
Author: schor
Date: Tue Feb 7 16:22:47 2017
New Revision: 1782025
URL: http://svn.apache.org/viewvc?rev=1782025&view=rev
Log:
[UIMA-5304] SelectFSs API updates
Modified:
uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/SelectFSs.java
uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/impl/SelectFSs_impl.java
Modified: uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/SelectFSs.java
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/SelectFSs.java?rev=1782025&r1=1782024&r2=1782025&view=diff
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/SelectFSs.java (original)
+++ uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/SelectFSs.java Tue Feb 7 16:22:47 2017
@@ -26,6 +26,7 @@ import java.util.stream.Stream;
import org.apache.uima.cas.text.AnnotationFS;
import org.apache.uima.jcas.cas.TOP;
+import org.apache.uima.jcas.tcas.Annotation;
/**
* Collection of builder style methods to specify selection of FSs from indexes
@@ -68,33 +69,174 @@ public interface SelectFSs<T extends Fea
// SelectFSs<T> matchType(boolean matchType); // exact type match (no subtypes)
// only for AnnotationIndex
+ /**
+ * Specify that type priority should be included when comparing two Feature Structures while positioning an iterator
+ * <p>
+ * Default is to not include type priority.
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> typePriority();
+
+ /**
+ * Specify that type priority should or should not be included when comparing two Feature Structures while positioning an iterator
+ * <p>
+ * Default is to not include type priority.
+ * @param typePriority if true says to include the type priority
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> typePriority(boolean typePriority);
+ /**
+ * Only used when typePriority false, and only for Annotation Indexes
+ * <p>
+ * For annotation index, specifies that after a moveTo(FeatureStructure) operation has
+ * found a feature structure that compares equal with the argument,
+ * the position is adjusted downwards while the element at the position is equal to the argument,
+ * where the equal includes the type.
+ * <p>
+ * Default is to not include the type.
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> positionUsesType(); // ignored if not ordered index
+
+ /**
+ * Only used when typePriority false, and only for Annotation Indexes
+ * <p>
+ * For annotation index, specifies that after a moveTo(FeatureStructure) operation has
+ * found a feature structure that compares equal with the argument,
+ * the position is adjusted downwards while the element at the position is equal to the argument,
+ * where the equal includes or doesn't include the type.
+ * <p>
+ * Default is to not include the type.
+ * @param true if the adjustment should require the types be the same.
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> positionUsesType(boolean positionUsesType); // ignored if not ordered index
// Filters while iterating over Annotations
+
+ /**
+ * Meaningful only for Annotation Indexes, specifies that iteration should return
+ * only annotations which don't overlap with each other. Also known as "unambiguous".
+ * <p>
+ * Default is to not have this filter.
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> nonOverlapping(); // AI known as unambiguous
+ /**
+ * Meaningful only for Annotation Indexes, specifies that iteration should or should not return
+ * only annotations which don't overlap with each other. Also known as "unambiguous".
+ * <p>
+ * Default is to not have this filter.
+ * @param nonOverlapping true to specify filtering for only non-overlapping annotations.
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> nonOverlapping(boolean nonOverlapping); // AI
+ /**
+ * Meaningful only for coveredBy, includes annotations where the end exceeds the bounding annotation's end.
+ * <p>
+ * Default is to NOT include annotations whose end exceeds the bounding annotation's end.
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> includeAnnotationsWithEndBeyondBounds(); // AI known as "strict"
- SelectFSs<T> includeAnnotationsWithEndBeyondBounds(boolean endWithinBounds); // AI
+ /**
+ * Meaningful only for coveredBy, includes or filters out annotations where the end exceeds the bounding annotation's end.
+ * <p>
+ * Default is to NOT include annotations whose end exceeds the bounding annotation's end.
+ * @param includeAnnotationsWithEndBeyondBounds false to filter out annotations whose end exceeds the bounding annotation's end
+ * @return the updated SelectFSs object
+ */
+ SelectFSs<T> includeAnnotationsWithEndBeyondBounds(boolean includeAnnotationsWithEndBeyondBounds); // AI
+ /**
+ * Meaningful only for coveredBy: if true, then returned annotations are compared equal to
+ * the bounding annotation, and if equal, they are skipped.
+ * <p>
+ * Default is to use feature structure identity comparison (same id()s), not equals, when
+ * doing the test to see if an annotation should be skipped.
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> useAnnotationEquals();
+ /**
+ * Meaningful only for coveredBy: if true, then returned annotations are compared
+ * to the bounding annotation
+ * using the specified kind of equal comparison,
+ * and if equal, they are skipped.
+ * <p>
+ * Default is to use feature structure identity comparison (same id()s), not equals, when
+ * doing the test to see if an annotation should be skipped.
+ * @param if true, use equals, if false, use id() ==.
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> useAnnotationEquals(boolean useAnnotationEquals);
// Miscellaneous
+ /**
+ * Extend the selection to be over all the CAS views, not just a single view.
+ * <p>
+ * Default is that the selection is just for one CAS view
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> allViews();
+ /**
+ * Extend or not extend the selection to be over all the CAS views, not just a single view.
+ * <p>
+ * Default is that the selection is just for one CAS view
+ * @param true to extend the selection.
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> allViews(boolean allViews);
- SelectFSs<T> nullOK(); // applies to get()
+ /**
+ * Applies to the various argument forms of the get method.
+ * Indicates that a null value should not throw an exception.
+ * <p>
+ * Default: null is not OK as a value
+ * @return the updated SelectFSs object
+ */
+ SelectFSs<T> nullOK();
+ /**
+ * Applies to the various argument forms of the get method.
+ * Indicates that a null value should or should not throw an exception.
+ * <p>
+ * Default: null is not OK as a value
+ * @param true if null is an ok value.
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> nullOK(boolean nullOk); // applies to get()
+ /**
+ * Specifies that order is not required while iterating over an otherwise ordered index.
+ * This can be a performance boost for hierarchically nested types.
+ * <p>
+ * Default: order is required by default, when iterating over an ordered index.
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> orderNotNeeded(); // ignored if not ordered index
+ /**
+ * Specifies that order is or is not required while iterating over an otherwise ordered index.
+ * This can be a performance boost for hierarchically nested types.
+ * <p>
+ * Default: order is required by default, when iterating over an ordered index.
+ * @param true means order is not needed.
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> orderNotNeeded(boolean unordered); // ignored if not ordered index
+ /**
+ * Specifies that the iteration should run in reverse order from normal.
+ * Note that this does not compose;
+ * two calls to this will still result in the iteration running in reverse order.
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> backwards(); // ignored if not ordered index
+ /**
+ * Specifies that the iteration should run in the normal or reverse order.
+ * Note that this does not compose.
+ * @param true to run in reverse order
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> backwards(boolean backwards); // ignored if not ordered index
// SelectFSs<T> noSubtypes();
@@ -117,31 +259,122 @@ public interface SelectFSs<T extends Fea
// shifts, if any, occur afterwards
// - can be positive or negative
// ---------------------------------
+ /**
+ * Starting Position specification - Shifts the normal start position by the shiftAmount, which may be negative.
+ * Repeated calls to this just replaces the requested shift amount; a single shift only occurs when a
+ * result is obtained.
+ * @param shiftAmount the amount to shift; this many Feature Structures which
+ * normally would be returned are instead skipped.
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> shifted(int shiftAmount);
+ /**
+ * Starting Position specification - For ordered sources, specifies which FS to start at.
+ * @param fs a Feature Structure specifying a starting position.
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> startAt(TOP fs); // Ordered
+ /**
+ * Starting Position specification - For Annotation Indexes, specifies which FS to start at.
+ * @param begin the begin bound
+ * @param end the end bound
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> startAt(int begin, int end); // AI
-
+ /**
+ * Starting Position specification - A combination of startAt followed by a shift
+ * @param fs a Feature Structure specifying a starting position.
+ * @param shift the amount to shift; this many Feature Structures which
+ * normally would be returned are instead skipped.
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> startAt(TOP fs, int shift); // Ordered
+ /**
+ * Starting Position specification - A combination of startAt followed by a shift
+ * @param begin the begin bound
+ * @param end the end bound
+ * @param shift the amount to shift; this many Feature Structures which
+ * normally would be returned are instead skipped.
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> startAt(int begin, int end, int shift); // AI
+ /**
+ * Limits the number of Feature Structures returned by this select
+ * @param n the maximum number of feature structures returned.
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> limit(int n);
// ---------------------------------
// subselection based on bounds
// - uses
// -- typePriority,
// -- positionUsesType,
- // -- skipEquals
+ // -- useAnnotationEquals
// ---------------------------------
+ /**
+ * Subselection - specifies selecting Feature Structures having the same begin and end
+ * - influenced by typePriority, positionUsesType, and useAnnotationEquals
+ * @param fs specifies the bounds.
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> at(AnnotationFS fs); // AI
+ /**
+ * Subselection - specifies selecting Feature Structures having the same begin and end
+ * @param begin the begin bound
+ * @param end the end bound
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> at(int begin, int end); // AI
-
+ /**
+ * Subselection - specifies selecting Feature Structures
+ * starting (and maybe ending) within a bounding Feature Structure
+ * - influenced by typePriority, positionUsesType, useAnnotationEquals,
+ * includeAnnotationsWithEndBeyondBounds
+ * @param fs specifies the bounds.
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> coveredBy(AnnotationFS fs); // AI
+ /**
+ * Subselection - specifies selecting Feature Structures
+ * starting (and maybe ending) within a bounding Feature Structure
+ * @param begin the begin bound
+ * @param end the end bound
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> coveredBy(int begin, int end); // AI
-
+ /**
+ * Subselection - specifies selecting Feature Structures
+ * starting before or equal to bounding Feature Structure
+ * and ending at or beyond the bounding Feature Structure
+ * - influenced by typePriority, positionUsesType, useAnnotationEquals
+ * @param fs specifies the bounds.
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> covering(AnnotationFS fs); // AI
+ /**
+ * Subselection - specifies selecting Feature Structures
+ * starting before or equal to bounding Feature Structure's begin
+ * and ending at or beyond the bounding Feature Structure's end
+ * @param begin the begin bound
+ * @param end the end bound
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> covering(int begin, int end); // AI
+ /**
+ * Subselection - specifies selecting Feature Structures
+ * which lie between two annotations.
+ * A bounding Annotation is constructed whose begin
+ * is the end of fs1, and whose end is the begin of fs2.
+ * <p>
+ * If fs1 > fs2, they are swapped, and the selected values are returned in reverse order.
+ *
+ * @param fs1 the beginning bound
+ * @param fs2 the ending bound
+ * @return the updated SelectFSs object
+ */
SelectFSs<T> between(AnnotationFS fs1, AnnotationFS fs2); // AI implies a coveredBy style
/* ---------------------------------
@@ -155,47 +388,308 @@ public interface SelectFSs<T extends Fea
* - for preceding, return in forward order (unless backward is specified)
* - for preceding, skips FSs whose end >= begin (adjusted by offset)
* ---------------------------------*/
- SelectFSs<T> following(TOP fs);
- SelectFSs<T> following(int begin, int end);
- SelectFSs<T> following(TOP fs, int offset);
- SelectFSs<T> following(int begin, int end, int offset);
-
- SelectFSs<T> preceding(TOP fs);
- SelectFSs<T> preceding(int begin, int end);
- SelectFSs<T> preceding(TOP fs, int offset);
- SelectFSs<T> preceding(int begin, int end, int offset);
+ /**
+ * For AnnotationIndex, position to first Annotation
+ * whose begin > fs.getEnd();
+ * @param annotation the Annotation to follow
+ * @return the updated SelectFSs object
+ */
+ SelectFSs<T> following(Annotation annotation);
+ /**
+ * For AnnotationIndex, position to first Annotation whose begin > fs.getEnd();
+ * @param position start following this position
+ * @return the updated SelectFSs object
+ */
+ SelectFSs<T> following(int position);
+ /**
+ * For AnnotationIndex, position to first Annotation whose begin > fs.getEnd()
+ * and then adjust position by the offset
+ * @param annotation start following this Annotation, adjusted for the offset
+ * @param offset positive or negative shift amount to adjust starting position
+ * @return the updated SelectFSs object
+ */
+ SelectFSs<T> following(Annotation annotation, int offset);
+ /**
+ * For AnnotationIndex, position to first Annotation whose begin > position
+ * and then adjust position by the offset.
+ * @param position start following this position, adjusted for the offset
+ * @param offset positive or negative shift amount to adjust starting position
+ * @return the updated SelectFSs object
+ */
+ SelectFSs<T> following(int position, int offset);
+
+ /**
+ * For AnnotationIndex, set up a selection that will proceed backwards,
+ * starting at the first Annotation whose end <= fs.getBegin().
+ * Annotations whose end > fs.getBegin() are skipped.
+ * @param annotation the Annotation to use as the position to start before.
+ * @return the updated SelectFSs object
+ */
+ SelectFSs<T> preceding(Annotation annotation);
+ /**
+ * For AnnotationIndex, set up a selection that will proceed backwards,
+ * starting at the first Annotation whose end <= position.
+ * Annotations whose end > position are skipped.
+ * @param position the position to start before.
+ * @return the updated SelectFSs object
+ */
+ SelectFSs<T> preceding(int position);
+ /**
+ * For AnnotationIndex, set up a selection that will proceed backwards,
+ * starting at the first Annotation whose end <= fs.getBegin(),
+ * after adjusting by offset items.
+ * Annotations whose end > fs.getBegin() are skipped (including during the offset positioning)
+ * @param annotation the Annotation to use as the position to start before.
+ * @param offset the offset adjustment, positive or negative. Positive moves backwards.
+ * @return the updated SelectFSs object
+ */
+ SelectFSs<T> preceding(Annotation annotation, int offset);
+ /**
+ * For AnnotationIndex, set up a selection that will proceed backwards,
+ * starting at the first Annotation whose end <= position.
+ * after adjusting by offset items.
+ * Annotations whose end > fs.getBegin() are skipped (including during the offset positioning)
+ * @param position the position to start before.
+ * @param offset the offset adjustment, positive or negative. Positive moves backwards.
+ * @return the updated SelectFSs object
+ */
+ SelectFSs<T> preceding(int position, int offset);
// ---------------------------------
// terminal operations
// returning other than SelectFSs
//
// ---------------------------------
+ /**
+ * @return an FSIterator over the selection. The iterator is set up depending on
+ * preceding configuration calls to this SelectFSs instance.
+ */
FSIterator<T> fsIterator();
// Iterator<T> iterator(); // inherited, not needed here
+ /**
+ * @param <N> the generic type argument of the elements of the list
+ * @return a List object whose elements represent the selection.
+ */
<N extends T> List<N> asList();
+ /**
+ * @param <N> the generic type argument of the elements of the array
+ * @return a Array object representation of the elements of the selection.
+ */
<N extends T> N[] asArray(Class<N> clazz);
// Spliterator<T> spliterator(); // inherited, not needed here
// returning one item
+ /**
+ * Get the first element or null if empty or the element at the first position is null.
+ * if nullOK is false, then throws CASRuntimeException if null would have been returned.
+ * @return first element or null if empty
+ * @throws CASRuntimeException conditioned on nullOK == false, and null being returned or the selection is empty.
+ */
T get(); // returns first element or null if empty (unless nullOK(false) specified)
+ /**
+ * @return first element, which must be not null
+ * @throws CASRuntimeException if element is null or
+ * if there is more than 1 element in the selection,
+ * or if the selection is empty
+ */
T single(); // throws if not exactly 1 element, throws if null
+ /**
+ * @return first element, which may be null, or null if selection is empty.
+ * @throws CASRuntimeException if there is more than 1 element in the selection.
+ */
T singleOrNull(); // throws if more than 1 element, returns single or null
// next are positioning alternatives
// get(...) throws if null (unless nullOK specified)
+ /**
+ * Get the offset element or null if empty or the offset went outside the
+ * the selected elements.
+ * <p>
+ * If nullOK is false, then throws CASRuntimeException if null would have been returned, or
+ * the selection is empty, or doesn't have enough elements to satisfy the positioning.
+ * @param offset the offset adjustment, positive or negative.
+ * @return the selected element or null
+ * @throws CASRuntimeException conditioned on nullOK == false, and null being returned
+ * or the selection is empty,
+ * or the offset positioning going outside the elements in the selection.
+ */
T get(int offset); // returns first element or null if empty after positioning
+ /**
+ * Get the offset element or null if empty or the offset went outside the
+ * the selected elements.
+ * <p>
+ * If, after positioning, there is another element next to the one being returned
+ * (in the forward direction if offset is positive, reverse direction if offset is negative)
+ * then throw an exception.
+ * <p>
+ * If nullOK is false, then throws CASRuntimeException if null would have been returned, or
+ * the selection is empty, or doesn't have enough elements to satisfy the positioning.
+ * @param offset the offset adjustment, positive or negative.
+ * @return the selected element or null
+ * @throws CASRuntimeException if, after positioning, there is another element next to the one being returned
+ * (in the forward direction if offset is positive, reverse direction if offset is negative)
+ * or (conditioned on nullOK == false) null being returned
+ * or the selection is empty,
+ * or the offset positioning going outside the elements in the selection.
+ */
T single(int offset); // throws if not exactly 1 element
+ /**
+ * Get the offset element or null if empty or the offset went outside the
+ * the selected elements.
+ * <p>
+ * If, after positioning, there is another element next to the one being returned
+ * (in the forward direction if offset is positive, reverse direction if offset is negative)
+ * then throw an exception.
+ * <p>
+ * @param offset the offset adjustment, positive or negative.
+ * @return the selected element or null
+ * @throws CASRuntimeException if, after positioning, there is another element next to the one being returned
+ * (in the forward direction if offset is positive, reverse direction if offset is negative)
+ */
T singleOrNull(int offset); // throws if more than 1 element, returns single or null
+ /**
+ * Positions to the fs using moveTo(fs).
+ * Get the element at that position or null if empty or the element at that position is null.
+ * if nullOK is false, then throws CASRuntimeException if null would have been returned.
+ * @param fs the positioning Feature Structure
+ * @return first element or null if empty
+ * @throws CASRuntimeException (conditioned on nullOK == false) null being returned or the selection is empty.
+ */
T get(TOP fs); // returns first element or null if empty after positioning
+ /**
+ * Positions to the fs using moveTo(fs).
+ * Get the element at that position or null if empty or the element at that position is null.
+ * if nullOK is false, then throws CASRuntimeException if null would have been returned.
+ * @param fs the positioning Feature Structure
+ * @return first element or null if empty
+ * @throws CASRuntimeException if, after positioning, there is another element following the one being returned
+ * or (conditioned on nullOK == false) and null being returned or the selection is empty.
+ */
T single(TOP fs); // throws if not exactly 1 element
+ /**
+ * Positions to the fs using moveTo(fs).
+ * Get the element at that position or null if empty or the element at that position is null.
+ * @param fs the positioning Feature Structure
+ * @return first element or null if empty
+ * @throws CASRuntimeException if, after positioning, there is another element following the one being returned
+ */
T singleOrNull(TOP fs); // throws if more than 1 element, returns single or null
+ /**
+ * Positions to the fs using moveTo(fs), followed by a shifted(offset).
+ * Gets the element at that position or null if empty or the element at that position is null.
+ * if nullOK is false, then throws CASRuntimeException if null would have been returned.
+ * @return the selected element or null if empty
+ * @throws CASRuntimeException (conditioned on nullOK == false) null being returned or the selection is empty.
+ */
T get(TOP fs, int offset); // returns first element or null if empty
+ /**
+ * Positions to the fs using moveTo(fs), followed by a shifted(offset).
+ * Gets the element at that position or null if empty or the element at that position is null.
+ * <p>
+ * If, after positioning, there is another element next to the one being returned
+ * (in the forward direction if offset is positive or 0, reverse direction if offset is negative)
+ * then throw an exception.
+ * <p>
+ * If nullOK is false, then throws CASRuntimeException if null would have been returned.
+ * @param fs the positioning Feature Structure
+ * @param offset the offset adjustment, positive or negative.
+ * @return the selected element or null if empty
+ * @throws CASRuntimeException if, after positioning, there is another element following the one being returned
+ * or (conditioned on nullOK == false) null being returned or the selection is empty.
+ */
T single(TOP fs, int offset); // throws if not exactly 1 element
+ /**
+ * Positions to the fs using moveTo(fs), followed by a shifted(offset).
+ * Gets the element at that position or null if empty or the element at that position is null.
+ * <p>
+ * If, after positioning, there is another element next to the one being returned
+ * (in the forward direction if offset is positive or 0, reverse direction if offset is negative)
+ * then throw an exception.
+ * <p>
+ * @param fs the positioning Feature Structure
+ * @param offset the offset adjustment, positive or negative.
+ * @return the selected element or null if empty
+ * @throws CASRuntimeException if, after positioning, there is another element next to the one being returned
+ */
T singleOrNull(TOP fs, int offset); // throws if more than 1 element, returns single or null
+ /**
+ * Position using a temporary Annotation with its begin and end set to the arguments.
+ * Gets the element at that position or null if empty or the element at that position is null.
+ * if nullOK is false, then throws CASRuntimeException if null would have been returned.
+ * @param begin the begin position of the temporary Annotation
+ * @param end the end position of the temporary Annotation
+ * @return the selected element or null if empty
+ * @throws CASRuntimeException conditioned on nullOK == false, and null being returned or the selection is empty.
+ */
T get(int begin, int end); // returns first element or null if empty
+ /**
+ * Position using a temporary Annotation with its begin and end set to the arguments.
+ * Gets the element at that position or null if empty or the element at that position is null.
+ * <p>
+ * If, after positioning, there is another element following the one being returned
+ * then throw an exception.
+ * <p>
+ * if nullOK is false, then throws CASRuntimeException if null would have been returned.
+ * @param begin the begin position of the temporary Annotation
+ * @param end the end position of the temporary Annotation
+ * @return the selected element or null if empty
+ * @throws CASRuntimeException if, after positioning, there is another element following the one being returned
+ * or (conditioned on nullOK == false) null being returned or the selection is empty.
+ */
T single(int begin, int end); // throws if not exactly 1 element
+ /**
+ * Position using a temporary Annotation with its begin and end set to the arguments.
+ * Gets the element at that position or null if empty or the element at that position is null.
+ * <p>
+ * If, after positioning, there is another element following the one being returned
+ * then throw an exception.
+ * @param begin the begin position of the temporary Annotation
+ * @param end the end position of the temporary Annotation
+ * @return the selected element or null if empty
+ * @throws CASRuntimeException if, after positioning, there is another element following the one being returned
+ */
T singleOrNull(int begin, int end); // throws if more than 1 element, returns single or null
+ /**
+ * Position using a temporary Annotation with its begin and end set to the arguments,
+ * followed by shifted(offset).
+ * Gets the element at that position or null if empty or the element at that position is null.
+ * <p>
+ * @param begin the begin position of the temporary Annotation
+ * @param end the end position of the temporary Annotation
+ * @param offset the amount (positive or negative or 0) passed as an argument to shifted(int)
+ * @return the selected element or null if empty
+ * @throws CASRuntimeException (conditioned on nullOK == false) if null being returned or the selection is empty.
+ */
T get(int begin, int end, int offset); // returns first element or null if empty
+ /**
+ * Position using a temporary Annotation with its begin and end set to the arguments,
+ * followed by shifted(offset).
+ * Gets the element at that position or null if empty or the element at that position is null.
+ * <p>
+ * If, after positioning, there is another element next to the one being returned
+ * (in the forward direction if offset is positive or 0, reverse direction if offset is negative)
+ * then throw an exception.
+ * @param begin the begin position of the temporary Annotation
+ * @param end the end position of the temporary Annotation
+ * @param offset the amount (positive or negative or 0) passed as an argument to shifted(int)
+ * @return the selected element or null if empty
+ * @throws CASRuntimeException if, after positioning, there is another element next to the one being returned
+ * or (conditioned on nullOK == false) if null being returned or the selection is empty.
+ */
T single(int begin, int end, int offset); // throws if not exactly 1 element
+ /**
+ * Position using a temporary Annotation with its begin and end set to the arguments,
+ * followed by shifted(offset).
+ * Gets the element at that position or null if empty or the element at that position is null.
+ * <p>
+ * If, after positioning, there is another element next to the one being returned
+ * (in the forward direction if offset is positive or 0, reverse direction if offset is negative)
+ * then throw an exception.
+ * @param begin the begin position of the temporary Annotation
+ * @param end the end position of the temporary Annotation
+ * @param offset the amount (positive or negative or 0) passed as an argument to shifted(int)
+ * @return the selected element or null if empty
+ * @throws CASRuntimeException if, after positioning, there is another element next to the one being returned
+ */
T singleOrNull(int begin, int end, int offset); // throws if more than 1 element, returns single or null
@@ -208,12 +702,13 @@ public interface SelectFSs<T extends Fea
/**
- * static methods that more effectively capture the generic argument
- * @param index -
+ * Use this static method to capture the generic argument
+ * @param index - the index to select over as a source
* @param <U> generic type of index
* @param <V> generic type of returned select
- * @return -
+ * @return - a SelectFSs instance
*/
+
static <U extends FeatureStructure, V extends U> SelectFSs<V> select(FSIndex<U> index) {
return index.select();
}
Modified: uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/impl/SelectFSs_impl.java
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/impl/SelectFSs_impl.java?rev=1782025&r1=1782024&r2=1782025&view=diff
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/impl/SelectFSs_impl.java (original)
+++ uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/impl/SelectFSs_impl.java Tue Feb 7 16:22:47 2017
@@ -99,7 +99,7 @@ public class SelectFSs_impl <T extends F
private BoundsUse boundsUse = null;
- private TOP startingFs = null;
+ private TOP startingFs = null; // this is used for non-annotation positioning too
private AnnotationFS boundingFs = null;
@@ -914,7 +914,11 @@ public class SelectFSs_impl <T extends F
FSIterator<T> it = fsIterator();
if (it.isValid()) {
T v = it.getNvc();
- it.moveToNext();
+ if (shift >= 0) {
+ it.moveToNext();
+ } else {
+ it.moveToPrevious();
+ }
if (it.isValid()) {
throw new CASRuntimeException(CASRuntimeException.SELECT_GET_TOO_MANY_INSTANCES, ti.getName(), maybeMsgPosition());
}
@@ -1096,7 +1100,7 @@ public class SelectFSs_impl <T extends F
* @see org.apache.uima.cas.SelectFSs#following(org.apache.uima.jcas.cas.TOP)
*/
@Override
- public SelectFSs<T> following(TOP fs) {
+ public SelectFSs<T> following(Annotation fs) {
return commonFollowing(fs, 0);
}
@@ -1104,15 +1108,15 @@ public class SelectFSs_impl <T extends F
* @see org.apache.uima.cas.SelectFSs#following(int, int)
*/
@Override
- public SelectFSs<T> following(int begin, int end) {
- return commonFollowing(makePosAnnot(begin, end), 0);
+ public SelectFSs<T> following(int position) {
+ return commonFollowing(makePosAnnot(0, position), 0);
}
/* (non-Javadoc)
* @see org.apache.uima.cas.SelectFSs#following(org.apache.uima.jcas.cas.TOP, int)
*/
@Override
- public SelectFSs<T> following(TOP fs, int offset) {
+ public SelectFSs<T> following(Annotation fs, int offset) {
return commonFollowing(fs, offset);
}
@@ -1120,15 +1124,15 @@ public class SelectFSs_impl <T extends F
* @see org.apache.uima.cas.SelectFSs#following(int, int, int)
*/
@Override
- public SelectFSs<T> following(int begin, int end, int offset) {
- return commonFollowing(makePosAnnot(begin, end), offset);
+ public SelectFSs<T> following(int position, int offset) {
+ return commonFollowing(makePosAnnot(0, position), offset);
}
/* (non-Javadoc)
* @see org.apache.uima.cas.SelectFSs#preceding(org.apache.uima.jcas.cas.TOP)
*/
@Override
- public SelectFSs<T> preceding(TOP fs) {
+ public SelectFSs<T> preceding(Annotation fs) {
return commonPreceding(fs, 0);
}
@@ -1136,24 +1140,24 @@ public class SelectFSs_impl <T extends F
* @see org.apache.uima.cas.SelectFSs#preceding(int, int)
*/
@Override
- public SelectFSs<T> preceding(int begin, int end) {
- return commonPreceding(makePosAnnot(begin, end), 0);
+ public SelectFSs<T> preceding(int position) {
+ return commonPreceding(makePosAnnot(position, Integer.MAX_VALUE), 0);
}
/* (non-Javadoc)
* @see org.apache.uima.cas.SelectFSs#preceding(org.apache.uima.jcas.cas.TOP, int)
*/
@Override
- public SelectFSs<T> preceding(TOP fs, int offset) {
- return commonPreceding(fs, offset);
+ public SelectFSs<T> preceding(Annotation annotation, int offset) {
+ return commonPreceding(annotation, offset);
}
/* (non-Javadoc)
* @see org.apache.uima.cas.SelectFSs#preceding(int, int, int)
*/
@Override
- public SelectFSs<T> preceding(int begin, int end, int offset) {
- return commonPreceding(makePosAnnot(begin, end), offset);
+ public SelectFSs<T> preceding(int position, int offset) {
+ return commonPreceding(makePosAnnot(position, Integer.MAX_VALUE), offset);
}
@@ -1190,16 +1194,16 @@ public class SelectFSs_impl <T extends F
// }
// }
- private SelectFSs<T> commonFollowing(TOP fs, int offset) {
- this.startingFs = fs;
+ private SelectFSs<T> commonFollowing(Annotation annotation, int offset) {
+ this.startingFs = annotation;
this.shift = offset;
isFollowing = true;
return this;
}
- private SelectFSs<T> commonPreceding(TOP fs, int offset) {
+ private SelectFSs<T> commonPreceding(Annotation annotation, int offset) {
// validateSinglePosition(fs, offset);
- this.startingFs = fs;
+ this.startingFs = annotation;
this.shift = offset;
isPreceding = true;
isBackwards = true; // always iterate backwards