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/09/04 16:52:54 UTC
svn commit: r1807255 -
/uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/
Author: schor
Date: Mon Sep 4 16:52:53 2017
New Revision: 1807255
URL: http://svn.apache.org/viewvc?rev=1807255&view=rev
Log:
[UIMA-5548] array creation comments, add default method for CAS for getEmpty xxx Array/list
Modified:
uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/ArrayFS.java
uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/BooleanArrayFS.java
uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/ByteArrayFS.java
uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/CAS.java
uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/FSIterator.java
uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/FloatArrayFS.java
uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/IntArrayFS.java
uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/LongArrayFS.java
uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/ShortArrayFS.java
uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/StringArrayFS.java
Modified: uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/ArrayFS.java
URL: http://svn.apache.org/viewvc/uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/ArrayFS.java?rev=1807255&r1=1807254&r2=1807255&view=diff
==============================================================================
--- uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/ArrayFS.java (original)
+++ uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/ArrayFS.java Mon Sep 4 16:52:53 2017
@@ -21,9 +21,8 @@ package org.apache.uima.cas;
/**
* Feature structure array interface. To create a FS array object, use
- * {@link org.apache.uima.cas.CAS#createArrayFS CAS.createArrayFS()}.
- *
- *
+ * {@link org.apache.uima.cas.CAS#createArrayFS(int length)} or
+ * new FSArray(aJCas, length)
*/
public interface ArrayFS extends CommonArrayFS {
Modified: uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/BooleanArrayFS.java
URL: http://svn.apache.org/viewvc/uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/BooleanArrayFS.java?rev=1807255&r1=1807254&r2=1807255&view=diff
==============================================================================
--- uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/BooleanArrayFS.java (original)
+++ uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/BooleanArrayFS.java Mon Sep 4 16:52:53 2017
@@ -21,9 +21,8 @@ package org.apache.uima.cas;
/**
* Boolean array interface. To create a boolean array object, use
- * {@link org.apache.uima.cas.CAS#createBooleanArrayFS CAS.createBooleanArrayFS()}.
- *
- *
+ * {@link org.apache.uima.cas.CAS#createBooleanArrayFS CAS.createBooleanArrayFS(int)} or
+ * new BooleanArray(aJCas, length)
*/
public interface BooleanArrayFS extends CommonArrayFS {
Modified: uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/ByteArrayFS.java
URL: http://svn.apache.org/viewvc/uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/ByteArrayFS.java?rev=1807255&r1=1807254&r2=1807255&view=diff
==============================================================================
--- uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/ByteArrayFS.java (original)
+++ uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/ByteArrayFS.java Mon Sep 4 16:52:53 2017
@@ -21,9 +21,8 @@ package org.apache.uima.cas;
/**
* Byte array interface. To create a byte array object, use
- * {@link org.apache.uima.cas.CAS#createByteArrayFS CAS.createByteArrayFS()}.
- *
- *
+ * {@link org.apache.uima.cas.CAS#createByteArrayFS CAS.createByteArrayFS(int)}
+ * or new ByteArray(aJCas, length)
*/
public interface ByteArrayFS extends CommonArrayFS {
Modified: uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/CAS.java
URL: http://svn.apache.org/viewvc/uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/CAS.java?rev=1807255&r1=1807254&r2=1807255&view=diff
==============================================================================
--- uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/CAS.java (original)
+++ uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/CAS.java Mon Sep 4 16:52:53 2017
@@ -30,10 +30,19 @@ import org.apache.uima.cas.impl.SelectFS
import org.apache.uima.cas.text.AnnotationFS;
import org.apache.uima.cas.text.AnnotationIndex;
import org.apache.uima.jcas.JCas;
+import org.apache.uima.jcas.cas.BooleanArray;
+import org.apache.uima.jcas.cas.ByteArray;
+import org.apache.uima.jcas.cas.DoubleArray;
import org.apache.uima.jcas.cas.EmptyFSList;
import org.apache.uima.jcas.cas.EmptyFloatList;
import org.apache.uima.jcas.cas.EmptyIntegerList;
import org.apache.uima.jcas.cas.EmptyStringList;
+import org.apache.uima.jcas.cas.FSArray;
+import org.apache.uima.jcas.cas.FloatArray;
+import org.apache.uima.jcas.cas.IntegerArray;
+import org.apache.uima.jcas.cas.LongArray;
+import org.apache.uima.jcas.cas.ShortArray;
+import org.apache.uima.jcas.cas.StringArray;
import org.apache.uima.jcas.impl.JCasImpl;
/**
@@ -519,6 +528,12 @@ public interface CAS extends AbstractCas
*/
<T extends FeatureStructure> T createFS(Type type) throws CASRuntimeException;
+ /*
+ * =============== These next methods might be deprecated in favor of
+ * =============== new FSArray(jcas, length) etc.
+ * =============== except that these run with the CAS, not JCas
+ */
+
/**
* Create a new feature structure array.
*
@@ -802,7 +817,7 @@ public interface CAS extends AbstractCas
<T extends AnnotationFS> AnnotationFS createAnnotation(Type type, int begin, int end);
/**
- * Get the document annotation. The document has a string-valued feature called "language" where
+ * Get the Document Annotation. The Document Annotation has a string-valued feature called "language" where
* the document language is specified.
*
* @param <T> the Java class for the document annotation. Could be the JCas cover class or FeatureStructure
@@ -1170,20 +1185,95 @@ public interface CAS extends AbstractCas
return new SelectFSs_impl<>(this).type(fullyQualifiedTypeName);
}
+ /**
+ * @return a lazily created shared (for this CAS) empty list
+ */
default EmptyFloatList getEmptyFloatList() {
- return ((CASImpl)this).getEmptyFloatListImpl();
- }
+ return ((CASImpl)getLowLevelCAS()).getEmptyFloatList();
+ };
+ /**
+ * @return a lazily created shared (for this CAS) empty list
+ */
default EmptyFSList getEmptyFSList() {
- return ((CASImpl)this).getEmptyFSListImpl();
- }
+ return ((CASImpl)getLowLevelCAS()).getEmptyFSList();
+ };
+ /**
+ * @return a lazily created shared (for this CAS) empty list
+ */
default EmptyIntegerList getEmptyIntegerList() {
- return ((CASImpl)this).getEmptyIntegerListImpl();
- }
+ return ((CASImpl)getLowLevelCAS()).getEmptyIntegerList();
+ };
+ /**
+ * @return a lazily created shared (for this CAS) empty list
+ */
default EmptyStringList getEmptyStringList() {
- return ((CASImpl)this).getEmptyStringListImpl();
- }
+ return ((CASImpl)getLowLevelCAS()).getEmptyStringList();
+ };
+
+ /**
+ * @return a lazily created shared (for this CAS) 0-length array
+ */
+ default FloatArray getEmptyFloatArray() {
+ return ((CASImpl)getLowLevelCAS()).getEmptyFloatArray();
+ };
+
+ /**
+ * @return a lazily created shared (for this CAS) 0-length array
+ */
+ default FSArray getEmptyFSArray() {
+ return ((CASImpl)getLowLevelCAS()).getEmptyFSArray();
+ };
+
+ /**
+ * @return a lazily created shared (for this CAS) 0-length array
+ */
+ default IntegerArray getEmptyIntegerArray() {
+ return ((CASImpl)getLowLevelCAS()).getEmptyIntegerArray();
+ };
+
+ /**
+ * @return a lazily created shared (for this CAS) 0-length array
+ */
+ default StringArray getEmptyStringArray() {
+ return ((CASImpl)getLowLevelCAS()).getEmptyStringArray();
+ };
+
+ /**
+ * @return a lazily created shared (for this CAS) 0-length array
+ */
+ default DoubleArray getEmptyDoubleArray() {
+ return ((CASImpl)getLowLevelCAS()).getEmptyDoubleArray();
+ };
+
+ /**
+ * @return a lazily created shared (for this CAS) 0-length array
+ */
+ default LongArray getEmptyLongArray() {
+ return ((CASImpl)getLowLevelCAS()).getEmptyLongArray();
+ };
+
+ /**
+ * @return a lazily created shared (for this CAS) 0-length array
+ */
+ default ShortArray getEmptyShortArray() {
+ return ((CASImpl)getLowLevelCAS()).getEmptyShortArray();
+ };
+
+ /**
+ * @return a lazily created shared (for this CAS) 0-length array
+ */
+ default ByteArray getEmptyByteArray() {
+ return ((CASImpl)getLowLevelCAS()).getEmptyByteArray();
+ };
+
+ /**
+ * @return a lazily created shared (for this CAS) 0-length array
+ */
+ default BooleanArray getEmptyBooleanArray() {
+ return ((CASImpl)getLowLevelCAS()).getEmptyBooleanArray();
+ };
}
Modified: uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/FSIterator.java
URL: http://svn.apache.org/viewvc/uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/FSIterator.java?rev=1807255&r1=1807254&r2=1807255&view=diff
==============================================================================
--- uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/FSIterator.java (original)
+++ uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/FSIterator.java Mon Sep 4 16:52:53 2017
@@ -33,9 +33,11 @@ import org.apache.uima.cas.impl.LowLevel
* Iterator over feature structures.
*
* <p>
- * This iterator interface extends {@link java.util.Iterator}, and supports the
- * standard <code>hasNext</code> and <code>next</code> methods. If finer control, including
- * reverse iteration, is needed, see below.
+ * This iterator interface extends {@link java.util.ListIterator} which, in turn,
+ * extends {@link java.util.Iterator}. It supports all the methods of those APIs
+ * except nextIndex, previousIndex, set, and add. remove meaning is changed to mean
+ * remove the item obtained by a get() from all the indexes in this view.
+ * If finer control, including reverse iteration, is needed, see below.
*
* <p>Note: do not use the APIs described below *together* with the standard Java iterator methods
* <code>next()</code> and <code>hasNext()</code>. On any given iterator, use either the one or the
@@ -54,10 +56,9 @@ import org.apache.uima.cas.impl.LowLevel
* <code>next()</code> would return, but does not advance the iterator.
*
* <p>
- * Implementations of this interface are not required to be fail-fast. That is, if the iterator's
- * collection is modified, the effects on the iterator are in general undefined. Some collections
- * may handle this more gracefully than others, but in general, concurrent modification of the
- * collection you're iterating over is a bad idea.
+ * If the iterator's underlying UIMA Indexes are modified, the iterator continues as if
+ * it doesn't see these modifications. Three operations cause the iterator to "see" any modifications:
+ * moveToFirst, moveToLast, and moveTo(featureStructure).
*
* <p>
* If the iterator is moved past the boundaries of the collection, the behavior of subsequent calls
@@ -68,8 +69,6 @@ import org.apache.uima.cas.impl.LowLevel
* the iterator back to the last element in the collection. Always use
* {@link FSIterator#moveToLast() moveToLast()} in such cases.
*
- *
- *
*/
public interface FSIterator<T extends FeatureStructure> extends ListIterator<T> {
@@ -138,13 +137,13 @@ public interface FSIterator<T extends Fe
* collection is non-empty. Allowed even if the underlying indexes being iterated over were modified.
*/
void moveToFirst();
-
+
/**
* Move the iterator to the last element. The iterator will be valid iff the underlying collection
* is non-empty. Allowed even if the underlying indexes being iterated over were modified.
*/
void moveToLast();
-
+
/**
* Move the iterator to the first Feature Structure that matches the <code>fs</code>.
* First means the earliest one occurring in the index, in case multiple FSs matching the fs
@@ -165,14 +164,27 @@ public interface FSIterator<T extends Fe
* if one exists. The match is done using the index's comparator.
* If none exist, the index is left if possible in some valid (but non-matching) position.
*
+ * <p>When the iterator is over a sorted index whose keys include the typeOrder key, this can cause
+ * unexpected operation, depending on type priorities. For example, consider the Annotation Index,
+ * which includes this key. If there are many indexed instances of the type "Foo" with the same begin and end,
+ * and a moveTo operation is specified using an Annotation instance with the same begin and end,
+ * then the Foo elements might or might not be seen going forwards, depending on the relative type
+ * priorities of "Foo" and "Annotation".
+ *
+ * <p>If you are not making use of typeOrdering, the "select" APIs can create iterators which will
+ * ignore the typeOrdering key when doing the moveTo operation, which will result in all the instances
+ * of type "Foo" being seen going forwards, independent of the type priorities. See the
+ * select documentation in the version 3 users guide.
+ *
* @param fs
* The feature structure the iterator that supplies the
- * comparison information. It can be a supertype of T as long as it can supply the keys needed.
+ * comparison information. It doesn't need to be in the index; it is just being
+ * used as a comparison template. It can be a supertype of T as long as it can supply the keys needed.
* A typical example is a subtype of Annotation, and using an annotation instance to specify
* the begin / end.
*/
void moveTo(FeatureStructure fs);
-
+
/**
* Copy this iterator.
*
Modified: uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/FloatArrayFS.java
URL: http://svn.apache.org/viewvc/uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/FloatArrayFS.java?rev=1807255&r1=1807254&r2=1807255&view=diff
==============================================================================
--- uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/FloatArrayFS.java (original)
+++ uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/FloatArrayFS.java Mon Sep 4 16:52:53 2017
@@ -21,7 +21,8 @@ package org.apache.uima.cas;
/**
* Interface for CAS float arrays. To create a float array object, use
- * {@link org.apache.uima.cas.CAS#createFloatArrayFS CAS.createFloatArrayFS()}.
+ * {@link org.apache.uima.cas.CAS#createFloatArrayFS CAS.createFloatArrayFS()}
+ * or new FloatArray(aJCas, length)
*
*
*/
Modified: uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/IntArrayFS.java
URL: http://svn.apache.org/viewvc/uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/IntArrayFS.java?rev=1807255&r1=1807254&r2=1807255&view=diff
==============================================================================
--- uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/IntArrayFS.java (original)
+++ uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/IntArrayFS.java Mon Sep 4 16:52:53 2017
@@ -21,9 +21,8 @@ package org.apache.uima.cas;
/**
* Interface for CAS int arrays. To create an int array object, use
- * {@link org.apache.uima.cas.CAS#createIntArrayFS CAS.createIntArrayFS()}.
- *
- *
+ * {@link org.apache.uima.cas.CAS#createIntArrayFS CAS.createIntArrayFS(int)} or
+ * new IntegerArray(aJCas, length)
*/
public interface IntArrayFS extends CommonArrayFS {
Modified: uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/LongArrayFS.java
URL: http://svn.apache.org/viewvc/uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/LongArrayFS.java?rev=1807255&r1=1807254&r2=1807255&view=diff
==============================================================================
--- uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/LongArrayFS.java (original)
+++ uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/LongArrayFS.java Mon Sep 4 16:52:53 2017
@@ -21,9 +21,8 @@ package org.apache.uima.cas;
/**
* Long array interface. To create a long array object, use
- * {@link org.apache.uima.cas.CAS#createLongArrayFS CAS.createLongArrayFS()}.
- *
- *
+ * {@link org.apache.uima.cas.CAS#createLongArrayFS CAS.createLongArrayFS(int)}
+ * or new LongArray(aJCas, length)
*/
public interface LongArrayFS extends CommonArrayFS {
Modified: uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/ShortArrayFS.java
URL: http://svn.apache.org/viewvc/uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/ShortArrayFS.java?rev=1807255&r1=1807254&r2=1807255&view=diff
==============================================================================
--- uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/ShortArrayFS.java (original)
+++ uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/ShortArrayFS.java Mon Sep 4 16:52:53 2017
@@ -21,9 +21,8 @@ package org.apache.uima.cas;
/**
* Short array interface. To create a short array object, use
- * {@link org.apache.uima.cas.CAS#createShortArrayFS CAS.createShortArrayFS()}.
- *
- *
+ * {@link org.apache.uima.cas.CAS#createShortArrayFS CAS.createShortArrayFS(int)} or
+ * new ShortArray(aJCas, length)
*/
public interface ShortArrayFS extends CommonArrayFS {
Modified: uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/StringArrayFS.java
URL: http://svn.apache.org/viewvc/uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/StringArrayFS.java?rev=1807255&r1=1807254&r2=1807255&view=diff
==============================================================================
--- uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/StringArrayFS.java (original)
+++ uima/uv3/uimaj-v3/trunk/uimaj-core/src/main/java/org/apache/uima/cas/StringArrayFS.java Mon Sep 4 16:52:53 2017
@@ -21,9 +21,8 @@ package org.apache.uima.cas;
/**
* String array interface. To create a string array object, use
- * {@link org.apache.uima.cas.CAS#createStringArrayFS CAS.createStringArrayFS()}.
- *
- *
+ * {@link org.apache.uima.cas.CAS#createStringArrayFS CAS.createStringArrayFS(int)}
+ * or new StringArray(aJCas, length)
*/
public interface StringArrayFS extends CommonArrayFS {