From e0a4485c92ac75030d09f9dae93a601619b71f1e Mon Sep 17 00:00:00 2001 From: Rodrigo Alves Vieira Date: Sat, 4 May 2013 17:16:51 -0300 Subject: [PATCH] Finishing writing Javadocs for the br.ufpe.cin.groundhog.main package. Related to #20. --- .../br/ufpe/cin/groundhog/main/CmdMain.java | 39 ++++++++++-- .../br/ufpe/cin/groundhog/main/Options.java | 62 ++++++++++++++++--- .../br/ufpe/cin/groundhog/main/TestMain.java | 18 ++++++ 3 files changed, 106 insertions(+), 13 deletions(-) diff --git a/src/java/main/br/ufpe/cin/groundhog/main/CmdMain.java b/src/java/main/br/ufpe/cin/groundhog/main/CmdMain.java index 967b97a..a9fd5f0 100644 --- a/src/java/main/br/ufpe/cin/groundhog/main/CmdMain.java +++ b/src/java/main/br/ufpe/cin/groundhog/main/CmdMain.java @@ -79,8 +79,7 @@ public static ForgeSearch defineForgeSearch(SupportedForge f) { break; } return search; - } - + } /** * Defines the forge crawler - that is - how the search will actually be performed on the chosen forge @@ -108,6 +107,13 @@ public static ForgeCrawler defineForgeCrawler(SupportedForge f, File destination return crawler; } + /** + * Defines the code history analysis mechanism according to the way it can be done for + * the searched projects. Git, SourceForge or SVN. + * @param scm + * @return a {@link CodeHistory} object + * @throws UnsupportedSCMException throw if the given SCM mechanism is not supported by Groundhog + */ public static CodeHistory defineCodeHistory(SCM scm) throws UnsupportedSCMException { Injector injector = Guice.createInjector(new CodeHistoryModule()); CodeHistory codehistory = null; @@ -127,6 +133,16 @@ public static CodeHistory defineCodeHistory(SCM scm) throws UnsupportedSCMExcept return codehistory; } + /** + * Performs the download and checkout of the given project + * @param project the project to be downloaded and have its source code checked out + * @param datetime the informed {@link Datetime} + * @param repositoryFolderFuture + * @return the checked out repository + * @throws InterruptedException + * @throws ExecutionException + * @throws CheckoutException + */ public static File downloadAndCheckoutProject(Project project, Date datetime, Future repositoryFolderFuture) throws InterruptedException, ExecutionException, CheckoutException { // Wait for project download @@ -160,6 +176,15 @@ public static File downloadAndCheckoutProject(Project project, Date datetime, Fu return checkedOutRepository; } + /** + * Analyzes the project's source code via a {@link JavaParser} and parses the result into JSON format + * @param project the project to be analyzed + * @param projectFolder the project folder where the source code to be analyzed is located + * @param datetime + * @param metricsFolder the directory where the JSON metrics output will be stored + * @throws IOException + * @throws JSONException + */ public static void analyzeProject(Project project, File projectFolder, Date datetime, File metricsFolder) throws IOException, JSONException { String name = project.getName(); @@ -183,12 +208,17 @@ public static void analyzeProject(Project project, File projectFolder, Date date } } + /** + * Deletes the temporary directories and closes the log streams + * @param crawler the {@link ForgeCrawler) object to have its resources emptied + * @param errorStream the error stream to be closed + */ public static void freeResources(ForgeCrawler crawler, OutputStream errorStream) { crawler.shutdown(); try { FileUtil.getInstance().deleteTempDirs(); } catch (IOException e) { - logger.warn("Could not delete temp folders (but they will be eventually deleted)"); + logger.warn("Could not delete temporary folders (but they will eventually be deleted)"); } try { @@ -296,6 +326,7 @@ public void run() { })); } ex.shutdown(); + for (int i = 0; i < analysisFutures.size(); i++) { try { analysisFutures.get(i).get(); @@ -306,7 +337,7 @@ public void run() { } } - // Free resources and delete temp directories + // Free resources and delete temporary directories logger.info("Disposing resources..."); freeResources(crawler, errorStream); logger.info("Done!"); diff --git a/src/java/main/br/ufpe/cin/groundhog/main/Options.java b/src/java/main/br/ufpe/cin/groundhog/main/Options.java index 6ca1106..c3e44fe 100644 --- a/src/java/main/br/ufpe/cin/groundhog/main/Options.java +++ b/src/java/main/br/ufpe/cin/groundhog/main/Options.java @@ -14,6 +14,10 @@ enum SupportedForge { GITHUB, SOURCEFORGE, GOOGLECODE } +/** + * The command-line options parsing class + * @author fjsj, gustavopinto, rodrigoalvesvieira + */ public class Options { private static SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd_HH_mm"); @@ -38,59 +42,99 @@ public class Options { @Argument private List arguments = new ArrayList(); + /** + * Informs the code forge where the project search will be performed + * @return + */ public SupportedForge getForge() { - return forge; + return this.forge; } + /** + * Returns the destination folder into which projects will be downloaded + * @return + */ public File getDestinationFolder() { - return destinationFolder; + return this.destinationFolder; } - + + /** + * Sets the destination folder into which projects will be downloaded + * @param destinationFolder + */ public void setDestinationFolder(File destinationFolder) { this.destinationFolder = destinationFolder; } + /** + * Informs the location of the folder where the metrics will be stored + * @return A {@link File} object correspondent to the metrics folder + */ public File getMetricsFolder() { - return metricsFolder; + return this.metricsFolder; } + /** + * Sets the location of the folder where the metrics will be stored + * @param metricsFolder + */ public void setMetricsFolder(File metricsFolder) { this.metricsFolder = metricsFolder; } public Date getDatetime() throws ParseException { - return dateFormat.parse(datetime); + return dateFormat.parse(this.datetime); } public void setDatetime(String datetime) { this.datetime = datetime; - } + /** + * Informs the maximum number of projects to be downloaded and processed + * @return + */ public int getnProjects() { - return nProjects; + return this.nProjects; } + /** + * Sets the maximum number of projects to be downloaded and processed + * @param nProjects + */ public void setnProjects(int nProjects) { this.nProjects = nProjects; } + /** + * Informs the maximum number of concurrent threads to be ran + * @return + */ public int getnThreads() { - return nThreads; + return this.nThreads; } + /** + * Sets the maximum number of concurrent threads to be ran + * @param nThreads + */ public void setnThreads(int nThreads) { this.nThreads = nThreads; } public List getArguments() { - return arguments; + return this.arguments; } public void setArguments(List arguments) { this.arguments = arguments; } + /** + * Sets the forge where the search for projects will be performed + * Valid options are those specified in the {@link SupportedForge} enumerator + * @param forge + */ public void setForge(SupportedForge forge) { this.forge = forge; } diff --git a/src/java/main/br/ufpe/cin/groundhog/main/TestMain.java b/src/java/main/br/ufpe/cin/groundhog/main/TestMain.java index 4dbd940..2fd3b71 100644 --- a/src/java/main/br/ufpe/cin/groundhog/main/TestMain.java +++ b/src/java/main/br/ufpe/cin/groundhog/main/TestMain.java @@ -37,9 +37,18 @@ import com.google.inject.Guice; import com.google.inject.Injector; +/** + * The main test class + * @author fjsj, gustavopinto, rodrigoalvesvieira + */ public class TestMain { private static Logger logger = LoggerFactory.getLogger(TestMain.class); + /** + * Test method for search the GitHub forge + * @param term the search term (project name) + * @throws Exception + */ public static void gitHubExample(String term) throws Exception { File downloadFolder = FileUtil.getInstance().createTempDir(); @@ -77,6 +86,10 @@ public static void gitHubExample(String term) throws Exception { } } + /** + * Test method for search the SourceForge forge + * @throws Exception + */ public static void sourceForgeExample() throws Exception { File downloadFolder = FileUtil.getInstance().createTempDir(); @@ -120,6 +133,11 @@ public static void sourceForgeExample() throws Exception { } } + /** + * Test method for search the Google Code forge + * @param term the search term (project name) + * @throws Exception + */ public static void googleCodeExample(String term) throws Exception { File downloadFolder = FileUtil.getInstance().createTempDir();