From cb3e8aec5e045b4947373f6556af1316b0511d27 Mon Sep 17 00:00:00 2001
From: droazen <droazen@348d0f76-0448-11de-a6fe-93d51630548a>
Date: Thu, 7 Apr 2011 18:40:53 +0000
Subject: [PATCH] Modified the buildfile and help extractor doclet so that help
 text is only extracted from source files that have been modified since the
 help resource file was last generated. This significantly speeds up builds
 where only a few source files have been modified, at the expense of making
 clean builds take slightly longer. Here's some performance data gathered by
 testing the old and new versions of extracthelp in isolation and averaging
 across 10 runs: old extracthelp, 1 modified source file: 20.1 seconds new
 extracthelp, 1 modified source file: 7.2 seconds <-- woohoo! :) old
 extracthelp, clean build: 17.8 seconds new extracthelp, clean build: 20.5
 seconds

git-svn-id: file:///humgen/gsa-scr1/gsa-engineering/svn_contents/trunk@5590 348d0f76-0448-11de-a6fe-93d51630548a
---
 build.xml                                     | 46 ++++++++++++++-----
 .../help/ResourceBundleExtractorDoclet.java   | 32 +++++++++++--
 2 files changed, 64 insertions(+), 14 deletions(-)

diff --git a/build.xml b/build.xml
index b93b0d200..416fce4bd 100644
--- a/build.xml
+++ b/build.xml
@@ -318,33 +318,57 @@
                 <striplinebreaks/>
             </filterchain>
         </loadfile>
+
+        <!-- This fileset will contain only source files modified since the resource file was last generated,
+             or all source files if the resource file doesn't exist -->
+        <fileset dir="${basedir}" id="modified.source.files">
+            <include name="${java.source.dir}/**/*.java"/>
+            <include name="${external.dir}/**/*.java"/>
+            <depend targetdir="${basedir}">
+                <mapper type="merge" to="${resource.path}"/>
+            </depend>
+        </fileset>
+
+        <!-- Set the sources.modified property only if our fileset of modified source files is non-empty -->
+        <pathconvert refid="modified.source.files" property="sources.modified" setonempty="false"/>
+
+        <!-- Due to a limitation in the doclet API, we always need to pass package-info files to javadoc -->
+        <fileset dir="${basedir}" id="package.info.files">
+            <include name="${java.source.dir}/**/package-info.java"/>
+            <include name="${external.dir}/**/package-info.java"/>
+        </fileset>
+
         <condition property="uptodate.extracthelp">
             <or>
                 <isset property="disable.help"/>
                 <and>
-                    <uptodate targetfile="${basedir}/${resource.path}">
-                        <srcfiles refid="java.class.files"/>
-                    </uptodate>
-                    <equals arg1="${properties.version}" arg2="${build.version}" />
+                    <not>
+                        <isset property="sources.modified"/>
+                    </not>
+                    <equals arg1="${properties.version}" arg2="${build.version}"/>
                 </and>
             </or>
         </condition>
     </target>
 
-    <target name="extracthelp" depends="init.extracthelp"
-	    description="Extract help key/value pair file from the JavaDoc tags."
-	    unless="uptodate.extracthelp">
+    <target name="extracthelp" depends="init.extracthelp" unless="uptodate.extracthelp"
+	        description="Extract help key/value pair file from the JavaDoc tags.">
         <path id="doclet.classpath">
-          <path refid="external.dependencies" />
-          <pathelement location="${java.classes}" />
+            <path refid="external.dependencies" />
+            <pathelement location="${java.classes}" />
         </path>
 
         <javadoc doclet="org.broadinstitute.sting.utils.help.ResourceBundleExtractorDoclet"
                  docletpathref="doclet.classpath"
                  classpathref="external.dependencies"
+                 classpath="${java.classes}"
                  additionalparam="-build-timestamp &quot;${build.timestamp}&quot; -version-suffix .${build.version} -out ${basedir}/${resource.path} -quiet">
-            <sourcepath path="${java.source.dir}"/>
-            <sourcepath path="${external.dir}"/>
+            <sourcefiles>
+                <union>
+                    <fileset refid="modified.source.files"/>
+                    <fileset refid="package.info.files"/>
+                </union>
+            </sourcefiles>
         </javadoc>
     </target>
 
diff --git a/java/src/org/broadinstitute/sting/utils/help/ResourceBundleExtractorDoclet.java b/java/src/org/broadinstitute/sting/utils/help/ResourceBundleExtractorDoclet.java
index 49a93148b..84b0942e5 100644
--- a/java/src/org/broadinstitute/sting/utils/help/ResourceBundleExtractorDoclet.java
+++ b/java/src/org/broadinstitute/sting/utils/help/ResourceBundleExtractorDoclet.java
@@ -27,9 +27,8 @@ package org.broadinstitute.sting.utils.help;
 
 import com.sun.javadoc.*;
 
+import java.io.*;
 import java.util.*;
-import java.io.PrintStream;
-import java.io.IOException;
 
 import org.broadinstitute.sting.utils.exceptions.ReviewedStingException;
 import org.broadinstitute.sting.utils.classloader.JVMUtils;
@@ -70,8 +69,10 @@ public class ResourceBundleExtractorDoclet {
         String buildTimestamp = null, versionPrefix = null, versionSuffix = null;
 
         for(String[] options: rootDoc.options()) {
-            if(options[0].equals("-out"))
+            if(options[0].equals("-out")) {
+                loadExistingResourceFile(options[1], rootDoc);
                 out = new PrintStream(options[1]);
+            }
             if(options[0].equals("-build-timestamp"))
                 buildTimestamp = options[1];
             if(options[0].equals("-version-prefix"))
@@ -122,6 +123,31 @@ public class ResourceBundleExtractorDoclet {
         return 0;
     }
 
+    /**
+     * Attempts to load the contents of the resource file named by resourceFileName into
+     * our in-memory resource collection resourceText. If the resource file doesn't exist,
+     * prints a notice to the user but does not throw an exception back to the calling method,
+     * since we'll just create a new resource file from scratch in that case.
+     * @param  resourceFileName  name of the resource file to attempt to load.
+     * @param  rootDoc           the documentation root.
+     * @throws IOException       if there is an I/O-related error other than FileNotFoundException
+     *                           while attempting to read the resource file.
+     */
+    private static void loadExistingResourceFile( String resourceFileName, RootDoc rootDoc ) throws IOException {
+        try {
+            BufferedReader resourceFile = new BufferedReader(new FileReader(resourceFileName));
+            try {
+                resourceText.load(resourceFile);
+            }
+            finally {
+                resourceFile.close();
+            }
+        }
+        catch ( FileNotFoundException e ) {
+            rootDoc.printNotice("Resource file not found -- generating a new one from scratch.");
+        }
+    }
+
     /**
      * Determine whether a given class is a walker.
      * @param classDoc the type of the given class.