svn commit: r1660703 - /uima/uimaj/trunk/uima-docbook-references/src/docbook/ref.cas.xml

[sc...@apache.org]

Author: schor
Date: Wed Feb 18 19:24:27 2015
New Revision: 1660703

URL: http://svn.apache.org/r1660703
Log:
no Jira - clarify that iterators may get ConcurrentModificationException due to the automatic prevention of index corruption.

Modified:
    uima/uimaj/trunk/uima-docbook-references/src/docbook/ref.cas.xml

Modified: uima/uimaj/trunk/uima-docbook-references/src/docbook/ref.cas.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/trunk/uima-docbook-references/src/docbook/ref.cas.xml?rev=1660703&r1=1660702&r2=1660703&view=diff
==============================================================================
--- uima/uimaj/trunk/uima-docbook-references/src/docbook/ref.cas.xml (original)
+++ uima/uimaj/trunk/uima-docbook-references/src/docbook/ref.cas.xml Wed Feb 18 19:24:27 2015
@@ -840,7 +840,15 @@ aPerson.setStringValue(lastNameFeature,
       <quote>reset</quote> this condition, such as moving to beginning, end, or moving to a
       particular feature structure. So - if you have to modify the index, you can move it back to
       the last FS you had retrieved from the iterator, and then continue, if that makes sense in
-      your application.</para>   
+      your application.</para>
+      
+    <para>Feature structures being iterated over should not have features which are used as the "keys" of an index, updated.
+    If this is done, UIMA, to prevent index corruption, will recover by automatically removing the FS from the indexes, 
+    updating the field, and adding the FS back to the index.  This recovery operation, because it updates the index, 
+    will make the iterator throw a ConcurrentModificationException if the iterator is incremented or decremented;
+    this exception will likely be unexpected because because it is hidden and automatic.  
+    If you must do this kind of operation, consider using Snapshot iterators (see next),
+    which don't throw ConcurrentModificationException.</para>   
       
     <para>As of version 2.7.0, a new method on FSIndex, <code>withSnapshotIterators(),</code> 
     allows creating a light-weight FSIndex based on the original FSIndex