style (line wraps), add explanatory comments

Author: vladak

src/org/opensolaris/opengrok/history/FileHistoryCache.java

@@ -46,14 +46,18 @@
 import org.opensolaris.opengrok.OpenGrokLogger;
 import org.opensolaris.opengrok.configuration.RuntimeEnvironment;
 
+/*
+ * Class representing file based storage of per source file history.
+ */
 class FileHistoryCache implements HistoryCache {
     private final Object lock = new Object();
 
     static class FilePersistenceDelegate extends PersistenceDelegate {
         @Override
         protected Expression instantiate(Object oldInstance, Encoder out) {
             File f = (File)oldInstance;
-            return new Expression(oldInstance, f.getClass(), "new", new Object[] {f.toString()});
+            return new Expression(oldInstance, f.getClass(), "new",
+                new Object[] {f.toString()});
         }
     }
 
@@ -95,7 +99,8 @@ private static File getCachedFile(File file) throws HistoryException {
             sb.append(add);
             sb.append(".gz");
         } catch (IOException e) {
-            throw new HistoryException("Failed to get path relative to source root for " + file, e);
+            throw new HistoryException("Failed to get path relative to " +
+                 "source root for " + file, e);
         }
 
         return new File(sb.toString());
@@ -112,6 +117,13 @@ private static History readCache(File file) throws IOException {
         }
     }
 
+    /**
+     * Store history object (encoded as XML and compressed with gzip) in a file.
+     *
+     * @param history history object to store
+     * @param file file to store the history object into
+     * @throws HistoryException
+     */
     private void storeFile(History history, File file) throws HistoryException {
 
         File cache = getCachedFile(file);
@@ -135,8 +147,10 @@ private void storeFile(History history, File file) throws HistoryException {
             output = File.createTempFile("oghist", null, dir);
             try (FileOutputStream out = new FileOutputStream(output);
                     XMLEncoder e = new XMLEncoder(
-                            new BufferedOutputStream(new GZIPOutputStream(out)))) {
-                e.setPersistenceDelegate(File.class, new FilePersistenceDelegate());
+                            new BufferedOutputStream(
+                            new GZIPOutputStream(out)))) {
+                e.setPersistenceDelegate(File.class,
+                    new FilePersistenceDelegate());
                 e.writeObject(history);
             }
         } catch (IOException ioe) {
@@ -145,20 +159,32 @@ private void storeFile(History history, File file) throws HistoryException {
         synchronized (lock) {
             if (!cache.delete() && cache.exists()) {
                 if (!output.delete()) {
-                    OpenGrokLogger.getLogger().log(Level.WARNING, "Failed to remove temporary history cache file");
+                    OpenGrokLogger.getLogger().log(Level.WARNING,
+                        "Failed to remove temporary history cache file");
                 }
                 throw new HistoryException(
                         "Cachefile exists, and I could not delete it.");
             }
             if (!output.renameTo(cache)) {
                 if (!output.delete()) {
-                    OpenGrokLogger.getLogger().log(Level.WARNING, "Failed to remove temporary history cache file");
+                    OpenGrokLogger.getLogger().log(Level.WARNING,
+                        "Failed to remove temporary history cache file");
                 }
                 throw new HistoryException("Failed to rename cache tmpfile.");
             }
         }
     }
 
+    /**
+     * Store history for the whole repository in directory hierarchy resembling
+     * the original repository structure. History of individual files will be
+     * stored under this hierarchy, each file containing history of
+     * corresponding source file.
+     *
+     * @param history history object to process into per-file histories
+     * @param repository repository object
+     * @throws HistoryException
+     */
     @Override
     public void store(History history, Repository repository)
             throws HistoryException {
@@ -171,14 +197,24 @@ public void store(History history, Repository repository)
         HashMap<String, List<HistoryEntry>> map =
                 new HashMap<String, List<HistoryEntry>>();
 
+        /*
+         * Go through all history entries for this repository (acquired through
+         * history/log command executed for top-level directory of the repo
+         * and parsed into HistoryEntry structures) and create hash map which
+         * maps file names into list of HistoryEntry structures corresponding
+         * to changesets in which the file was modified.
+         */
         for (HistoryEntry e : history.getHistoryEntries()) {
             for (String s : e.getFiles()) {
                 List<HistoryEntry> list = map.get(s);
                 if (list == null) {
                     list = new ArrayList<HistoryEntry>();
                     map.put(s, list);
                 }
-                // We need to do deep copy in order to have different tags per each commit
+                /*
+                 * We need to do deep copy in order to have different tags
+                 * per each commit.
+                 */
                 if (env.isTagsEnabled() && repository.hasFileBasedTags()) {
                     list.add(new HistoryEntry(e));
                 } else {
@@ -187,6 +223,11 @@ public void store(History history, Repository repository)
             }
         }
 
+        /*
+         * Now traverse the list of files from the hash map built above
+         * and for each file store its history (saved in the value of the
+         * hash map entry for the file) in a file.
+         */
         File root = RuntimeEnvironment.getInstance().getSourceRootFile();
         for (Map.Entry<String, List<HistoryEntry>> e : map.entrySet()) {
             for (HistoryEntry ent : e.getValue()) {
@@ -279,9 +320,11 @@ public boolean hasCacheForDirectory(File directory, Repository repository)
         File dir = env.getDataRootFile();
         dir = new File(dir, "historycache");
         try {
-            dir = new File(dir, env.getPathRelativeToSourceRoot(new File(repos.getDirectoryName()), 0));
+            dir = new File(dir, env.getPathRelativeToSourceRoot(
+                 new File(repos.getDirectoryName()), 0));
         } catch (IOException e) {
-            throw new HistoryException("Could not resolve "+repos.getDirectoryName()+" relative to source root", e);
+            throw new HistoryException("Could not resolve " +
+                 repos.getDirectoryName()+" relative to source root", e);
         }
         return dir.exists();
     }