Documented the history package.

git-svn-id: http://google-refine.googlecode.com/svn/trunk@334 7d457c2a-affb-35e4-300a-418c747d4874

src/main/java/com/metaweb/gridworks/history/Change.java

@@ -6,6 +6,13 @@ import java.util.Properties;
 
 import com.metaweb.gridworks.model.Project;
 
+/**
+ * Interface for a concrete change to a project's data. A change should consist
+ * of new values already computed. When apply() is called, the change should not
+ * spend any more time computing anything. It should simply save existing values
+ * and swap in new values. Similarly, when revert() is called, the change
+ * should only swap old values back in.
+ */
 public interface Change {
     public void apply(Project project);
     public void revert(Project project);

src/main/java/com/metaweb/gridworks/history/History.java

@@ -17,6 +17,13 @@ import com.metaweb.gridworks.Jsonizable;
 import com.metaweb.gridworks.ProjectManager;
 import com.metaweb.gridworks.model.Project;
 
+/**
+ * Track done and undone changes. Done changes can be undone; undone changes can be redone.
+ * Each change is actually not tracked directly but through a history entry. The history
+ * entry stores only the metadata, while the change object stores the actual data. Thus
+ * the history entries are much smaller and can be kept in memory, while the change objects
+ * are only loaded into memory on demand.
+ */
 public class History implements Jsonizable {
     static public Change readOneChange(LineNumberReader reader) throws Exception {
         /* String version = */ reader.readLine();
@@ -45,8 +52,8 @@ public class History implements Jsonizable {
     }
     
     protected long               _projectID;
-    protected List<HistoryEntry> _pastEntries;
+    protected List<HistoryEntry> _pastEntries;   // done changes, can be undone
-    protected List<HistoryEntry> _futureEntries;
+    protected List<HistoryEntry> _futureEntries; // undone changes, can be redone
     
     public History(Project project) {
         _projectID = project.id;
@@ -55,15 +62,23 @@ public class History implements Jsonizable {
     }
     
     public void addEntry(HistoryEntry entry) {
-        for (HistoryEntry entry2 : _futureEntries) {
-            entry2.delete();
-        }
-        
         entry.apply(ProjectManager.singleton.getProject(_projectID));
         _pastEntries.add(entry);
-        _futureEntries.clear();
         
         setModified();
+        
+        // Any new change will clear all future entries.
+        List<HistoryEntry> futureEntries = _futureEntries;
+        _futureEntries = new ArrayList<HistoryEntry>();
+        
+        for (HistoryEntry entry2 : futureEntries) {
+            try {
+                // remove residual data on disk
+                entry2.delete();
+            } catch (Exception e) {
+                e.printStackTrace();
+            }
+        }
     }
     
     protected void setModified() {
@@ -80,6 +95,7 @@ public class History implements Jsonizable {
     
     public void undoRedo(long lastDoneEntryID) {
         if (lastDoneEntryID == 0) {
+            // undo all the way back to the start of the project
             undo(_pastEntries.size());
         } else {
             for (int i = 0; i < _pastEntries.size(); i++) {
@@ -121,12 +137,12 @@ public class History implements Jsonizable {
             
             entry.revert(project);
             
+            setModified();
             times--;
             
             _pastEntries.remove(_pastEntries.size() - 1);
             _futureEntries.add(0, entry);
         }
-        setModified();
     }
     
     protected void redo(int times) {
@@ -137,12 +153,12 @@ public class History implements Jsonizable {
             
             entry.apply(project);
             
+            setModified();
             times--;
             
             _pastEntries.add(entry);
             _futureEntries.remove(0);
         }
-        setModified();
     }
     
     public void write(JSONWriter writer, Properties options)

src/main/java/com/metaweb/gridworks/history/HistoryEntry.java

@@ -24,13 +24,20 @@ import com.metaweb.gridworks.model.Project;
 import com.metaweb.gridworks.operations.OperationRegistry;
 import com.metaweb.gridworks.util.ParsingUtilities;
 
+/**
+ * This is the metadata of a Change. It's small, so we can load it in order to
+ * obtain information about a change without actually loading the change.
+ */
 public class HistoryEntry implements Jsonizable {
     final public long   id;
     final public long   projectID;
     final public String description;
-    final public AbstractOperation   operation;
     final public Date   time;
     
+    // the abstract operation, if any, that results in the change
+    final public AbstractOperation operation; 
+    
+    // the actual change, loaded on demand
     transient protected Change _change;
     
     public HistoryEntry(Project project, String description, AbstractOperation operation, Change change) {

src/main/java/com/metaweb/gridworks/history/HistoryProcess.java

@@ -9,6 +9,10 @@ import com.metaweb.gridworks.model.Project;
 import com.metaweb.gridworks.process.Process;
 import com.metaweb.gridworks.process.ProcessManager;
 
+/**
+ * The process for undoing or redoing. This involves calling apply() and revert()
+ * on changes.
+ */
 public class HistoryProcess extends Process {
     final protected Project _project;
     final protected long    _lastDoneID;