Author: rec
Date: Sat May 4 12:52:39 2013
New Revision: 1479093
URL: http://svn.apache.org/r1479093
Log:
[UIMA-2813] Document in which order annotations are returned by the "select*"
methods
- Added explanatory statement at package level
- Linked to statement from relevant methods
Modified:
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/util/CasUtil.java
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/util/FSCollectionFactory.java
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/util/JCasUtil.java
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/util/package-info.java
Modified:
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/util/CasUtil.java
URL:
http://svn.apache.org/viewvc/uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/util/CasUtil.java?rev=1479093&r1=1479092&r2=1479093&view=diff
==============================================================================
---
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/util/CasUtil.java
(original)
+++
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/util/CasUtil.java
Sat May 4 12:52:39 2013
@@ -71,6 +71,7 @@ public final class CasUtil {
* @param type
* a type.
* @return a return value.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
@SuppressWarnings("unchecked")
public static <T extends FeatureStructure> Iterator<T> iteratorFS(CAS cas,
Type type) {
@@ -87,6 +88,7 @@ public final class CasUtil {
* @param type
* a type.
* @return a return value.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
@SuppressWarnings("unchecked")
public static <T extends AnnotationFS> Iterator<T> iterator(CAS cas, Type
type) {
@@ -171,6 +173,7 @@ public final class CasUtil {
* @param type
* the type.
* @return A collection of the selected type.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static Collection<FeatureStructure> selectFS(ArrayFS array, Type
type) {
return FSCollectionFactory.create(array, type);
@@ -184,6 +187,7 @@ public final class CasUtil {
* @param type
* the type.
* @return A collection of the selected type.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
@SuppressWarnings({ "unchecked", "rawtypes" })
public static Collection<AnnotationFS> select(ArrayFS array, Type type) {
@@ -200,6 +204,7 @@ public final class CasUtil {
* @param aCas
* the CAS hosting the type system.
* @return A collection of the selected type.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static Collection<FeatureStructure> selectAllFS(final CAS aCas) {
return selectFS(aCas, getType(aCas, CAS.TYPE_NAME_TOP));
@@ -213,6 +218,7 @@ public final class CasUtil {
* @param type
* the type.
* @return A collection of the selected type.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static Collection<FeatureStructure> selectFS(final CAS cas, final
Type type) {
return FSCollectionFactory.create(cas, type);
@@ -224,6 +230,7 @@ public final class CasUtil {
* @param aCas
* the CAS hosting the type system.
* @return A collection of the selected type.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static Collection<AnnotationFS> selectAll(final CAS aCas) {
return select(aCas, getType(aCas, CAS.TYPE_NAME_ANNOTATION));
@@ -237,6 +244,7 @@ public final class CasUtil {
* @param type
* the type.
* @return A collection of the selected type.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
@SuppressWarnings({ "unchecked", "rawtypes" })
public static Collection<AnnotationFS> select(final CAS cas, final Type
type) {
@@ -262,6 +270,7 @@ public final class CasUtil {
* the second boundary annotation.
* @return a return value.
* @see Subiterator
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static List<AnnotationFS> selectBetween(final Type type, final
AnnotationFS ann1,
final AnnotationFS ann2) {
@@ -286,6 +295,7 @@ public final class CasUtil {
* the second boundary annotation.
* @return a return value.
* @see Subiterator
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static List<AnnotationFS> selectBetween(final CAS cas, final Type
type,
final AnnotationFS ann1, final AnnotationFS ann2) {
@@ -377,6 +387,7 @@ public final class CasUtil {
* the covering annotation.
* @return a return value.
* @see Subiterator
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static List<AnnotationFS> selectCovered(Type type, AnnotationFS
coveringAnnotation) {
return selectCovered(coveringAnnotation.getView(), type,
coveringAnnotation);
@@ -396,6 +407,7 @@ public final class CasUtil {
* the covering annotation.
* @return a return value.
* @see Subiterator
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static List<AnnotationFS> selectCovered(CAS cas, Type type,
AnnotationFS coveringAnnotation) {
int begin = coveringAnnotation.getBegin();
@@ -485,6 +497,7 @@ public final class CasUtil {
* end offset.
* @return a return value.
* @see Subiterator
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static List<AnnotationFS> selectCovered(CAS cas, Type type, int
begin, int end) {
@@ -532,6 +545,7 @@ public final class CasUtil {
* the covered annotation.
*
* @return a return value.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static List<AnnotationFS> selectCovering(Type type, AnnotationFS
coveredAnnotation) {
@@ -554,6 +568,7 @@ public final class CasUtil {
* @param coveredAnnotation
* the covered annotation.
* @return a return value.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static List<AnnotationFS> selectCovering(CAS cas, Type type,
AnnotationFS coveredAnnotation) {
@@ -577,6 +592,7 @@ public final class CasUtil {
* @param end
* end offset.
* @return a return value.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static List<AnnotationFS> selectCovering(CAS cas, Type type, int
begin, int end) {
@@ -605,6 +621,7 @@ public final class CasUtil {
* @param coveringType
* type of covering annotations.
* @return the index.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static Map<AnnotationFS, Collection<AnnotationFS>> indexCovering(CAS
cas, Type type,
Type coveringType) {
@@ -646,6 +663,7 @@ public final class CasUtil {
* @param coveredType
* type of covering annotations.
* @return the index.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static Map<AnnotationFS, Collection<AnnotationFS>> indexCovered(CAS
cas, Type type,
Type coveredType) {
@@ -687,6 +705,7 @@ public final class CasUtil {
* this can be either positive (0 corresponds to the first
annotation of a type) or
* negative (-1 corresponds to the last annotation of a type.)
* @return an annotation of the given type
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static AnnotationFS selectByIndex(CAS cas, Type type, int index) {
if (!cas.getTypeSystem().subsumes(cas.getAnnotationType(), type)) {
@@ -749,6 +768,7 @@ public final class CasUtil {
* relative position to access. A negative value selects a
preceding annotation while a
* positive number selects a following annotation.
* @return the addressed annotation.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static AnnotationFS selectSingleRelative(Type type, AnnotationFS
annotation, int index) {
return selectSingleRelative(annotation.getView(), type, annotation, index);
@@ -769,6 +789,7 @@ public final class CasUtil {
* @return the addressed annotation.
* @throws IndexOutOfBoundsException
* if the relative index points beyond the type index bounds.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static AnnotationFS selectSingleRelative(CAS cas, Type type,
AnnotationFS annotation,
int index) {
@@ -827,6 +848,7 @@ public final class CasUtil {
* @param count
* number of annotations to collect
* @return List of aType annotations preceding anchor annotation
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static List<AnnotationFS> selectPreceding(CAS cas, Type type,
AnnotationFS annotation,
int count) {
@@ -866,6 +888,7 @@ public final class CasUtil {
* @param count
* number of annotations to collect
* @return List of aType annotations following anchor annotation
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static List<AnnotationFS> selectFollowing(CAS cas, Type type,
AnnotationFS annotation,
int count) {
Modified:
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/util/FSCollectionFactory.java
URL:
http://svn.apache.org/viewvc/uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/util/FSCollectionFactory.java?rev=1479093&r1=1479092&r2=1479093&view=diff
==============================================================================
---
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/util/FSCollectionFactory.java
(original)
+++
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/util/FSCollectionFactory.java
Sat May 4 12:52:39 2013
@@ -34,6 +34,7 @@ import org.apache.uima.cas.BooleanArrayF
import org.apache.uima.cas.ByteArrayFS;
import org.apache.uima.cas.CAS;
import org.apache.uima.cas.DoubleArrayFS;
+import org.apache.uima.cas.FSIndexRepository;
import org.apache.uima.cas.FSIterator;
import org.apache.uima.cas.FeatureStructure;
import org.apache.uima.cas.FloatArrayFS;
@@ -82,6 +83,18 @@ public abstract class FSCollectionFactor
// No instances.
}
+ /**
+ * Create a {@link Collection} of the given type of feature structures. This
collection is backed
+ * by the CAS, either via an {@link CAS#getAnnotationIndex(Type)} or
+ * {@link FSIndexRepository#getAllIndexedFS(Type)}.
+ *
+ * @param cas
+ * the CAS to select from.
+ * @param type
+ * the type of feature structures to select. All sub-types are
returned as well.
+ * @return a {@link Collection} of the given type of feature structures
backed live by the CAS.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
+ */
@SuppressWarnings({ "unchecked", "rawtypes" })
public static Collection<FeatureStructure> create(CAS cas, Type type) {
// If the type is an annotation type, we can use the annotation index,
which directly
@@ -95,14 +108,38 @@ public abstract class FSCollectionFactor
}
}
+ /**
+ * Convert an {@link FSIterator} to a {@link Collection}.
+ *
+ * @param aIterator
+ * the iterator to convert.
+ * @return the wrapped iterator.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
+ */
public static <T extends FeatureStructure> Collection<T>
create(FSIterator<T> aIterator) {
return new FSIteratorAdapter<T>(aIterator);
}
+ /**
+ * Convert an {@link AnnotationIndex} to a {@link Collection}.
+ *
+ * @param aIndex
+ * the index to convert.
+ * @return the wrapped index.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
+ */
public static <T extends AnnotationFS> Collection<T>
create(AnnotationIndex<T> aIndex) {
return new AnnotationIndexAdapter<T>(aIndex);
}
+ /**
+ * Convert an {@link ArrayFS} to a {@link Collection}.
+ *
+ * @param aArray
+ * the array to convert.
+ * @return a new collection containing the same feature structures as the
provided array.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
+ */
public static Collection<FeatureStructure> create(ArrayFS aArray) {
return create(aArray, (Type) null);
}
@@ -116,7 +153,7 @@ public abstract class FSCollectionFactor
* the FS array
* @param aType
* the JCas wrapper class.
- * @return a collection of all annotations of the given type.
+ * @return a new collection of all feature structures of the given type.
*/
@SuppressWarnings({ "unchecked", "rawtypes" })
public static <T extends TOP> Collection<T> create(ArrayFS aArray, Class<T>
aType) {
@@ -130,7 +167,7 @@ public abstract class FSCollectionFactor
* the FS array
* @param aType
* the CAS type.
- * @return a collection of all annotations of the given type.
+ * @return a new collection of all feature structures of the given type.
*/
public static Collection<FeatureStructure> create(ArrayFS aArray, Type
aType) {
TypeSystem ts = aArray.getCAS().getTypeSystem();
@@ -429,7 +466,7 @@ public abstract class FSCollectionFactor
* the FS list
* @param aType
* the JCas wrapper class.
- * @return a collection of all annotations of the given type.
+ * @return a new collection of all feature structures of the given type.
*/
@SuppressWarnings("unchecked")
public static <T extends TOP> Collection<T> create(FSList aList, Class<T>
aType) {
Modified:
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/util/JCasUtil.java
URL:
http://svn.apache.org/viewvc/uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/util/JCasUtil.java?rev=1479093&r1=1479092&r2=1479093&view=diff
==============================================================================
---
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/util/JCasUtil.java
(original)
+++
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/util/JCasUtil.java
Sat May 4 12:52:39 2013
@@ -43,7 +43,7 @@ public final class JCasUtil {
private JCasUtil() {
// No instances
}
-
+
/**
* Convenience method to iterator over all annotations of a given type
occurring within the scope
* of a provided annotation (sub-iteration).
@@ -62,6 +62,7 @@ public final class JCasUtil {
* Controls if annotations that overlap to the right are considered
in or out.
* @return A sub-iterator iterable.
* @see AnnotationIndex#subiterator(AnnotationFS, boolean, boolean)
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static <T extends Annotation> Iterable<T> subiterate(final JCas jCas,
final Class<T> type,
final AnnotationFS container, final boolean ambiguous, final boolean
strict) {
@@ -82,6 +83,7 @@ public final class JCasUtil {
* @param type
* a type.
* @return a return value.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
@SuppressWarnings({ "unchecked", "rawtypes" })
public static <T extends TOP> Iterator<T> iterator(JCas jCas, Class<T> type)
{
@@ -102,6 +104,7 @@ public final class JCasUtil {
* @param strict
* Controls if annotations that overlap to the right are considered
in or out.
* @return A sub-iterator.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
@SuppressWarnings("unchecked")
public static <T extends AnnotationFS> Iterator<T> iterator(AnnotationFS
container,
@@ -148,7 +151,7 @@ public final class JCasUtil {
* @param type
* the type.
* @return A collection of the selected type.
- * @see #selectCovered(Class, AnnotationFS)
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static <T extends TOP> Collection<T> select(final FSArray array,
final Class<T> type) {
return cast(CasUtil.selectFS(array, CasUtil.getType(array.getCAS(),
type.getName())));
@@ -164,7 +167,7 @@ public final class JCasUtil {
* @param type
* the type.
* @return A collection of the selected type.
- * @see #selectCovered(Class, AnnotationFS)
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static <T extends TOP> Collection<T> select(final FSList list, final
Class<T> type) {
return cast(FSCollectionFactory.create(list,
CasUtil.getType(list.getCAS(), type.getName())));
@@ -180,6 +183,7 @@ public final class JCasUtil {
* @param type
* the type.
* @return A collection of the selected type.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static <T extends TOP> Collection<T> select(final JCas jCas, final
Class<T> type) {
return cast(CasUtil.selectFS(jCas.getCas(), getType(jCas, type)));
@@ -191,6 +195,7 @@ public final class JCasUtil {
* @param jCas
* the JCas containing the type system. the type.
* @return A collection of the selected type.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static Collection<TOP> selectAll(final JCas jCas) {
return select(jCas, TOP.class);
@@ -212,6 +217,7 @@ public final class JCasUtil {
* the second boundary annotation.
* @return a return value.
* @see Subiterator
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static <T extends Annotation> List<T> selectBetween(final Class<T>
type,
AnnotationFS ann1, AnnotationFS ann2) {
@@ -236,6 +242,7 @@ public final class JCasUtil {
* the second boundary annotation.
* @return a return value.
* @see Subiterator
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static <T extends Annotation> List<T> selectBetween(JCas jCas, final
Class<T> type,
AnnotationFS ann1, AnnotationFS ann2) {
@@ -255,6 +262,7 @@ public final class JCasUtil {
* the covering annotation.
* @return a return value.
* @see Subiterator
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static <T extends AnnotationFS> List<T> selectCovered(Class<T> type,
AnnotationFS coveringAnnotation) {
@@ -277,6 +285,7 @@ public final class JCasUtil {
* the covering annotation.
* @return a return value.
* @see Subiterator
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static <T extends Annotation> List<T> selectCovered(JCas jCas, final
Class<T> type,
AnnotationFS coveringAnnotation) {
@@ -304,6 +313,7 @@ public final class JCasUtil {
* @param end
* end offset.
* @return a return value.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static <T extends Annotation> List<T> selectCovered(JCas jCas, final
Class<T> type,
int begin, int end) {
@@ -325,6 +335,7 @@ public final class JCasUtil {
* @param coveredAnnotation
* the covered annotation.
* @return a return value.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static <T extends Annotation> List<T> selectCovering(Class<T> type,
AnnotationFS coveredAnnotation) {
@@ -332,7 +343,7 @@ public final class JCasUtil {
return
cast(CasUtil.selectCovering(CasUtil.getType(coveredAnnotation.getCAS(), type),
coveredAnnotation));
}
-
+
/**
* Get a list of annotations of the given annotation type constraint by a
certain annotation.
* Iterates over all annotations to find the covering annotations.
@@ -350,13 +361,14 @@ public final class JCasUtil {
* @param coveredAnnotation
* the covered annotation.
* @return a return value.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static <T extends Annotation> List<T> selectCovering(JCas jCas,
Class<T> type,
AnnotationFS coveredAnnotation) {
return cast(CasUtil.selectCovering(jCas.getCas(), getType(jCas, type),
coveredAnnotation));
}
-
+
/**
* Get a list of annotations of the given annotation type constraint by a
certain annotation.
* Iterates over all annotations to find the covering annotations.
@@ -376,6 +388,7 @@ public final class JCasUtil {
* @param end
* end offset.
* @return a return value.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static <T extends Annotation> List<T> selectCovering(JCas jCas,
Class<T> type, int begin,
int end) {
@@ -397,6 +410,7 @@ public final class JCasUtil {
* @param coveringType
* type of covering annotations.
* @return the index.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static <T extends Annotation, S extends Annotation> Map<T,
Collection<S>> indexCovering(
JCas jCas, Class<T> type, Class<S> coveringType) {
@@ -418,6 +432,7 @@ public final class JCasUtil {
* @param coveredType
* type of covered annotations.
* @return the index.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static <T extends Annotation, S extends Annotation> Map<T,
Collection<S>> indexCovered(
JCas jCas, Class<T> type, Class<S> coveredType) {
@@ -435,6 +450,7 @@ public final class JCasUtil {
* @param type
* a UIMA type.
* @return if an annotation of the given type is present.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static boolean contains(JCas jCas, AnnotationFS coveringAnnotation,
Class<? extends Annotation> type) {
@@ -459,6 +475,7 @@ public final class JCasUtil {
* this can be either positive (0 corresponds to the first
annotation of a type) or
* negative (-1 corresponds to the last annotation of a type.)
* @return an annotation of the given type
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
@SuppressWarnings("unchecked")
public static <T extends Annotation> T selectByIndex(JCas jCas, Class<T>
cls, int index) {
@@ -497,6 +514,7 @@ public final class JCasUtil {
* @return the addressed annotation.
* @throws IndexOutOfBoundsException
* if the relative index points beyond the type index bounds.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
@SuppressWarnings("unchecked")
public static <T extends Annotation> T selectSingleRelative(Class<T> aType,
@@ -523,6 +541,7 @@ public final class JCasUtil {
* @return the addressed annotation.
* @throws IndexOutOfBoundsException
* if the relative index points beyond the type index bounds.
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
@SuppressWarnings("unchecked")
public static <T extends Annotation> T selectSingleRelative(JCas aJCas,
Class<T> aType,
@@ -543,6 +562,7 @@ public final class JCasUtil {
* @param count
* number of annotations to collect
* @return List of aType annotations preceding anchor annotation
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static <T extends Annotation> List<T> selectPreceding(Class<T> aType,
AnnotationFS annotation, int count) {
@@ -564,6 +584,7 @@ public final class JCasUtil {
* @param count
* number of annotations to collect
* @return List of aType annotations preceding anchor annotation
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static <T extends Annotation> List<T> selectPreceding(JCas aJCas,
Class<T> aType,
AnnotationFS annotation, int count) {
@@ -583,6 +604,7 @@ public final class JCasUtil {
* @param count
* number of annotations to collect
* @return List of aType annotations following anchor annotation
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static <T extends Annotation> List<T> selectFollowing(Class<T> aType,
AnnotationFS annotation, int count) {
@@ -604,6 +626,7 @@ public final class JCasUtil {
* @param count
* number of annotations to collect
* @return List of aType annotations following anchor annotation
+ * @see <a href="package-summary.html#SortOrder">Order of selected feature
structures</a>
*/
public static <T extends Annotation> List<T> selectFollowing(JCas aJCas,
Class<T> aType,
AnnotationFS annotation, int count) {
Modified:
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/util/package-info.java
URL:
http://svn.apache.org/viewvc/uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/util/package-info.java?rev=1479093&r1=1479092&r2=1479093&view=diff
==============================================================================
---
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/util/package-info.java
(original)
+++
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/util/package-info.java
Sat May 4 12:52:39 2013
@@ -18,6 +18,32 @@
*/
/**
* Utility classes like {@link org.apache.uima.fit.util.CasUtil} and {@link
org.apache.uima.fit.util.JCasUtil}.
+ *
+ * <h3><a name="SortOrder">Sort order</a></h3>
+ *
+ * The various <em>select</em> methods in {@link
org.apache.uima.fit.util.CasUtil} and
+ * {@link org.apache.uima.fit.util.JCasUtil} rely on the UIMA feature
structure indexes. Their
+ * behaviour differs depending on the type of feature structure being selected
and where they are
+ * selected from:
+ *
+ * <h4>Selecting from a {@link org.apache.uima.cas.CAS}/{@link
org.apache.uima.jcas.JCas}</h4>
+ * <ol>
+ * <li><b>Annotations</b> - if the type being selected is {@link
org.apache.uima.jcas.tcas.Annotation}
+ * or a sub-type thereof, the built-in annotation index is used. This index
has the keys
+ * <em>begin</em> (Ascending), <em>end</em> (Descending) and
<em>TYPE_PRIORITY</em>. There are no
+ * built-in type priorities, so this last sort item does not play a role in
the index unless
+ * type priorities are specified. uimaFIT uses {@link
org.apache.uima.cas.CAS#getAnnotationIndex(org.apache.uima.cas.Type)}
+ * to access annotation feature structures.</li>
+ * <li><b>Other feature structures</b> - if feature structures are selected
that are not
+ * {@link org.apache.uima.jcas.tcas.Annotation annotations}, the order should
be considered
+ * undefined. uimaFIT uses {@link
org.apache.uima.cas.FSIndexRepository#getAllIndexedFS(org.apache.uima.cas.Type)}
+ * to access these feature structures.</li>
+ * </ol>
+ *
+ * <h4>Selecting from a {@link org.apache.uima.cas.ArrayFS
ArrayFS/FSArray}/{@link FSList}</h4>
+ *
+ * When selecting from a feature structure list or array, the order is
determined by the order of
+ * the annotations inside the list/array.
*/
package org.apache.uima.fit.util;
