This is an automated email from the ASF dual-hosted git repository. schor pushed a commit to branch UIMA-6159_selectFS_allow_AnnotationFS_in_addition_to_TOP in repository https://gitbox.apache.org/repos/asf/uima-uimaj.git
commit 9d1ad830fb50738cc75ceb64b85876fdd260a61b Author: Marshall Schor <m...@schor.com> AuthorDate: Tue Jan 7 08:49:39 2020 -0500 [UIMA-6159] add method signatures for FeatureStructure which is a super of AnnotationFS. Do this in a way to preserve binary compatibility, as reported by the japicmp tool. --- .../main/java/org/apache/uima/cas/SelectFSs.java | 105 ++++++++++++++++++++- .../org/apache/uima/cas/impl/SelectFSs_impl.java | 60 +++++++++++- uimaj-parent/pom.xml | 2 +- 3 files changed, 158 insertions(+), 9 deletions(-) diff --git a/uimaj-core/src/main/java/org/apache/uima/cas/SelectFSs.java b/uimaj-core/src/main/java/org/apache/uima/cas/SelectFSs.java index ccf2cbc..e2f6096 100644 --- a/uimaj-core/src/main/java/org/apache/uima/cas/SelectFSs.java +++ b/uimaj-core/src/main/java/org/apache/uima/cas/SelectFSs.java @@ -217,9 +217,16 @@ public interface SelectFSs<T extends FeatureStructure> extends Iterable<T>, Stre * @param fs a Feature Structure specifying a starting position. * @return the updated SelectFSs object */ - SelectFSs<T> startAt(TOP fs); // an ordered index not necessarily AnnotationIndex, not necessarily sorted + SelectFSs<T> startAt(TOP fs); // an ordered index not necessarily AnnotationIndex, not necessarily sorted /** + * Starting Position specification - For ordered sources, specifies which FS to start at. + * Requires an ordered index not necessarily AnnotationIndex, not necessarily sorted + * @param fs a Feature Structure specifying a starting position. + * @return the updated SelectFSs object + */ + SelectFSs<T> startAt(FeatureStructure fs); + /** * Starting Position specification - For Annotation Indexes, specifies which FS to start at. * @param begin the begin bound * @param end the end bound @@ -236,7 +243,20 @@ public interface SelectFSs<T extends FeatureStructure> extends Iterable<T>, Stre * normally would be returned are instead skipped. * @return the updated SelectFSs object */ - SelectFSs<T> startAt(TOP fs, int shift); // an ordered index not necessarily AnnotationIndex, not necessarily sorted + SelectFSs<T> startAt(TOP fs, int shift); // an ordered index not necessarily AnnotationIndex, not necessarily sorted + + /** + * Starting Position specification - A combination of startAt followed by a shift + * + * Requires an ordered index not necessarily AnnotationIndex, not necessarily sorted + * This versions avoids a runtime cast check. + * @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(FeatureStructure fs, int shift); // an ordered index not necessarily AnnotationIndex, not necessarily sorted /** * Starting Position specification - A combination of startAt followed by a shift @@ -518,16 +538,28 @@ public interface SelectFSs<T extends FeatureStructure> extends Iterable<T>, Stre /** * 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. + * if nullOK is false, then throws CASRuntimeException if null would have been returned. + * This versions avoids a runtime cast check. * @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 + 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 (conditioned on nullOK == false) null being returned or the selection is empty. + */ + T get(FeatureStructure 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. + * This versions avoids a runtime cast check. * @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 @@ -537,15 +569,35 @@ public interface SelectFSs<T extends FeatureStructure> extends Iterable<T>, Stre /** * 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(FeatureStructure 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. + * This versions avoids a runtime cast check. * @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). + * 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(FeatureStructure 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. + * This versions avoids a runtime cast check. * @param fs where to move to * @param offset the offset move after positioning to fs, may be 0 or positive or negative * @return the selected element or null if empty @@ -554,6 +606,16 @@ public interface SelectFSs<T extends FeatureStructure> extends Iterable<T>, Stre 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. + * if nullOK is false, then throws CASRuntimeException if null would have been returned. + * @param fs where to move to + * @param offset the offset move after positioning to fs, may be 0 or positive or negative + * @return the selected element or null if empty + * @throws CASRuntimeException (conditioned on nullOK == false) null being returned or the selection is empty. + */ + T get(FeatureStructure 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 @@ -561,13 +623,14 @@ public interface SelectFSs<T extends FeatureStructure> extends Iterable<T>, Stre * then throw an exception. * <p> * If nullOK is false, then throws CASRuntimeException if null would have been returned. + * This versions avoids a runtime cast check. * @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 + 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. @@ -576,6 +639,23 @@ public interface SelectFSs<T extends FeatureStructure> extends Iterable<T>, Stre * (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(FeatureStructure 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> + * This versions avoids a runtime cast check. * @param fs the positioning Feature Structure * @param offset the offset adjustment, positive or negative. * @return the selected element or null if empty @@ -583,9 +663,24 @@ public interface SelectFSs<T extends FeatureStructure> extends Iterable<T>, Stre */ T singleOrNull(TOP fs, int offset); // 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. + * <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(FeatureStructure 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. + * This versions avoids a runtime cast check. * @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 diff --git a/uimaj-core/src/main/java/org/apache/uima/cas/impl/SelectFSs_impl.java b/uimaj-core/src/main/java/org/apache/uima/cas/impl/SelectFSs_impl.java index f5a580c..36accf2 100644 --- a/uimaj-core/src/main/java/org/apache/uima/cas/impl/SelectFSs_impl.java +++ b/uimaj-core/src/main/java/org/apache/uima/cas/impl/SelectFSs_impl.java @@ -20,7 +20,6 @@ package org.apache.uima.cas.impl; import java.lang.reflect.Array; -import java.util.AbstractList; import java.util.ArrayList; import java.util.Comparator; import java.util.Iterator; @@ -363,13 +362,26 @@ public class SelectFSs_impl <T extends FeatureStructure> implements SelectFSs<T> this.shift = shiftAmount; return this; } - + + @Override + public SelectFSs_impl<T> startAt(FeatureStructure fs) { + this.startingFs = (TOP) fs; + return this; + } @Override public SelectFSs_impl<T> startAt(TOP fs) { // Ordered this.startingFs = fs; return this; } - +// @Override +// public SelectFSs_impl<T> startAt(AnnotationFS fs) { +// return (startAt((TOP)fs)); +// } +// @Override +// public SelectFSs_impl<T> startAt(Annotation fs) { +// return (startAt((TOP)fs)); +// } + @Override public SelectFSs_impl<T> startAt(int begin, int end) { // AI this.startingFs = makePosAnnot(begin, end); @@ -383,6 +395,12 @@ public class SelectFSs_impl <T extends FeatureStructure> implements SelectFSs<T> return this; } @Override + public SelectFSs_impl<T> startAt(FeatureStructure fs, int offset) { // Ordered + this.startingFs = (TOP)fs; + this.shift = offset; + return this; + } + @Override public SelectFSs_impl<T> startAt(int begin, int end, int offset) { // AI this.startingFs = makePosAnnot(begin, end); this.shift = offset; @@ -1083,36 +1101,72 @@ public class SelectFSs_impl <T extends FeatureStructure> implements SelectFSs<T> } @Override + public T get(FeatureStructure fs) { + startAt(fs); + return getNullChk(); + } + + @Override public T single(TOP fs) { startAt(fs); return single(); } @Override + public T single(FeatureStructure fs) { + startAt(fs); + return single(); + } + + @Override public T singleOrNull(TOP fs) { startAt(fs); return singleOrNull(); } @Override + public T singleOrNull(FeatureStructure fs) { + startAt(fs); + return singleOrNull(); + } + + @Override public T get(TOP fs, int offset) { startAt(fs, offset); return getNullChk(); } @Override + public T get(FeatureStructure fs, int offset) { + startAt(fs, offset); + return getNullChk(); + } + + @Override public T single(TOP fs, int offset) { startAt(fs, offset); return single(); } @Override + public T single(FeatureStructure fs, int offset) { + startAt(fs, offset); + return single(); + } + + @Override public T singleOrNull(TOP fs, int offset) { startAt(fs, offset); return singleOrNull(); } @Override + public T singleOrNull(FeatureStructure fs, int offset) { + startAt(fs, offset); + return singleOrNull(); + } + + @Override public T get(int begin, int end) { startAt(begin, end); return getNullChk(); diff --git a/uimaj-parent/pom.xml b/uimaj-parent/pom.xml index e585666..37effd8 100644 --- a/uimaj-parent/pom.xml +++ b/uimaj-parent/pom.xml @@ -157,7 +157,7 @@ <maven.surefire.java9 /> <jacoco.argLine /> - <api_check_oldVersion>3.1.0</api_check_oldVersion> + <api_check_oldVersion>3.1.1</api_check_oldVersion> </properties> <dependencyManagement>