svn commit: r1722873 - /uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/impl/FSsTobeAddedback.java

[sc...@apache.org]

Author: schor
Date: Mon Jan  4 14:05:04 2016
New Revision: 1722873

URL: http://svn.apache.org/viewvc?rev=1722873&view=rev
Log:
no Jira - add comments

Modified:
    uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/impl/FSsTobeAddedback.java

Modified: uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/impl/FSsTobeAddedback.java
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/impl/FSsTobeAddedback.java?rev=1722873&r1=1722872&r2=1722873&view=diff
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/impl/FSsTobeAddedback.java (original)
+++ uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/impl/FSsTobeAddedback.java Mon Jan  4 14:05:04 2016
@@ -104,11 +104,30 @@ abstract class FSsTobeAddedback implemen
     }
   }
   
-  void addback()                         {throw new UnsupportedOperationException();}
-  void addback(TOP fs) {throw new UnsupportedOperationException();}
+  /**
+   * add back all the FSs that were removed in a protect block
+   *   -- for "Multiple" subclass
+   */
+  void addback()       {throw new UnsupportedOperationException();}  // is overridden in one subclass, throws in other
+  
+  /**
+   * add back the single FS that was removed due to 
+   *   -  automatic protection or 
+   *   -  delta deserialization or 
+   *   -  updating document annotation
+   *   -- for "Single" subclass
+   */
+  void addback(TOP fs) {throw new UnsupportedOperationException();}  // is overridden in one subclass, throws in other
   abstract void clear();
 
+  /**
+   * Version of this class for recording 1 FS
+   *
+   */
   static class FSsTobeAddedbackSingle extends FSsTobeAddedback {
+    /**
+     * list of views where the FS was removed; used when adding the fs back
+     */
     final List<FSIndexRepositoryImpl> views = new ArrayList<FSIndexRepositoryImpl>();
     
     @Override
@@ -117,6 +136,9 @@ abstract class FSsTobeAddedback implemen
       views.add(view);
     }
     
+    /**
+     * in single, the fs is ignored
+     */
     @Override
     void recordRemove(TOP fs, FSIndexRepositoryImpl view) {
       recordRemove(view);
@@ -130,12 +152,16 @@ abstract class FSsTobeAddedback implemen
       recordRemove(view);
     }
           
+    
     @Override
     void addback(TOP fs) {
+      /**
+       * add this back only to those views where it was removed
+       */
       for (FSIndexRepositoryImpl ir : views) {
         ir.addback(fs);
       }
-      clear();
+      clear();  // clear the viewlist
     }
     
     @Override
@@ -145,10 +171,21 @@ abstract class FSsTobeAddedback implemen
     }
   }
   
+  /**
+   * Version of this class used for protect blocks - where multiple FSs may be removed.
+   *   - records the fs along with the list of views where it was removed.
+   *
+   */
   static class FSsTobeAddedbackMultiple extends FSsTobeAddedback {
   
+    /**
+     * For each FS, the list of views where it was removed. 
+     */
     final Map<TOP, List<?>> fss2views = new HashMap<TOP, List<?>>();
     
+    /**
+     * An arbitrary cas view or base cas
+     */
     final CASImpl cas;
     
     FSsTobeAddedbackMultiple(CASImpl cas) {
@@ -182,7 +219,7 @@ abstract class FSsTobeAddedback implemen
     
     @Override
     void clear() {
-      fss2views.clear();
+      fss2views.clear(); // clears all the list of views for all feature structures
 //      if (SHOW) removes.set(0);
     }
   }
@@ -194,6 +231,11 @@ abstract class FSsTobeAddedback implemen
     return new FSsTobeAddedbackSingle();
   }
   
+  /**
+   * 
+   * @param cas the view where the protect block was set up
+   * @return an instance for recording removes of multiple FSs
+   */
   public static FSsTobeAddedback createMultiple(CASImpl cas) {
     return new FSsTobeAddedbackMultiple(cas);
   }