Merge pull request #22 from Siouan/1.1

Releasing version 1.1.1

build.gradle

@@ -41,7 +41,7 @@ dependencies {
 }
 
 group 'org.siouan'
-version '1.1.0'
+version '1.1.1'
 description 'Integrate your frontend NPM/Yarn build into Gradle.'
 
 sourceCompatibility = JavaVersion.VERSION_1_8

sonar-project.properties

@@ -1,6 +1,6 @@
 sonar.projectKey=Siouan_frontend-gradle-plugin
 sonar.projectName=frontend-gradle-plugin
-sonar.projectVersion=1.1.0
+sonar.projectVersion=1.1.1
 
 sonar.links.homepage=https://github.com/Siouan/frontend-gradle-plugin
 sonar.links.ci=https://travis-ci.org/Siouan/frontend-gradle-plugin

src/main/java/org/siouan/frontendgradleplugin/FrontendGradlePlugin.java

@@ -11,20 +11,77 @@
 import org.siouan.frontendgradleplugin.tasks.CleanTask;
 import org.siouan.frontendgradleplugin.tasks.InstallTask;
 import org.siouan.frontendgradleplugin.tasks.NodeInstallTask;
-import org.siouan.frontendgradleplugin.tasks.RunScriptTask;
 import org.siouan.frontendgradleplugin.tasks.YarnInstallTask;
 
 /**
- * Main plugin class which bootstraps the plugin by declaring its DSL and its tasks.
+ * Main plugin class that bootstraps the plugin by declaring its DSL and its tasks.
+ * <ul>
+ * <li>The plugin applies the Gradle Base plugin, to attach its tasks to the Gradle lifecyle task.</li>
+ * <li>Tasks are registered lazily thanks to the use of the configuration avoidance API.</li>
+ * <li>Task properties are mapped the plugin extension (DSL) using the lazy configuration API, allowing there
+ * calculation is delayed until it is required.</li>
+ * </ul>
+ *
+ * @see <a href="https://docs.gradle.org/current/userguide/task_configuration_avoidance.html">Task configuration
+ * avoidance</a>
+ * @see <a href="https://docs.gradle.org/current/userguide/lazy_configuration.html">Lazy configuration</a>
  */
 public class FrontendGradlePlugin implements Plugin<Project> {
 
+    /**
+     * Name of the task that assembles the frontend.
+     */
+    public static final String ASSEMBLE_TASK_NAME = "assembleFrontend";
+
+    /**
+     * Name of the task that checks the frontend.
+     */
+    public static final String CHECK_TASK_NAME = "checkFrontend";
+
+    /**
+     * Name of the task that cleans the frontend.
+     */
+    public static final String CLEAN_TASK_NAME = "cleanFrontend";
+
+    /**
+     * Name of the task that installs a Node distribution.
+     */
     public static final String DEFAULT_NODE_INSTALL_DIRNAME = "node";
 
+    /**
+     * Name of the task that installs a Yarn distribution.
+     */
     public static final String DEFAULT_YARN_INSTALL_DIRNAME = "yarn";
 
+    /**
+     * Name of the task that installs frontend dependencies.
+     */
+    public static final String INSTALL_TASK_NAME = "installFrontend";
+
+    /**
+     * Name of the task that installs a Node distribution.
+     */
+    public static final String NODE_INSTALL_TASK_NAME = "installNode";
+
+    /**
+     * Name of the task that installs a Yarn distribution.
+     */
+    public static final String YARN_INSTALL_TASK_NAME = "installYarn";
+
+    public static final String GRADLE_ASSEMBLE_TASK_NAME = "assemble";
+
+    public static final String GRADLE_CHECK_TASK_NAME = "check";
+
+    public static final String GRADLE_CLEAN_TASK_NAME = "clean";
+
+    /**
+     * Root name of the plugin extension.
+     */
     private static final String EXTENSION_NAME = "frontend";
 
+    /**
+     * The Gradle group in which all this plugin's tasks will be categorized.
+     */
     private static final String TASK_GROUP = "Frontend";
 
     public void apply(final Project project) {
@@ -37,26 +94,28 @@ public void apply(final Project project) {
         extension.getYarnInstallDirectory().convention(new File(project.getProjectDir(), DEFAULT_YARN_INSTALL_DIRNAME));
 
         final TaskContainer projectTasks = project.getTasks();
-        projectTasks
-            .register(NodeInstallTask.DEFAULT_NAME, NodeInstallTask.class, task -> configureTask(task, extension));
-
-        projectTasks
-            .register(YarnInstallTask.DEFAULT_NAME, YarnInstallTask.class, task -> configureTask(task, extension));
+        projectTasks.register(NODE_INSTALL_TASK_NAME, NodeInstallTask.class, task -> configureTask(task, extension));
 
-        projectTasks.register(InstallTask.DEFAULT_NAME, InstallTask.class, task -> configureTask(task, extension));
+        projectTasks.register(YARN_INSTALL_TASK_NAME, YarnInstallTask.class, task -> configureTask(task, extension));
 
-        projectTasks.register(CleanTask.DEFAULT_NAME, CleanTask.class, task -> configureTask(task, extension));
-        projectTasks.named("clean", task -> task.dependsOn(projectTasks.named(CleanTask.DEFAULT_NAME)));
+        projectTasks.register(INSTALL_TASK_NAME, InstallTask.class, task -> configureTask(task, extension));
 
-        projectTasks.register(CheckTask.DEFAULT_NAME, CheckTask.class, task -> configureTask(task, extension));
-        projectTasks.named("check", task -> task.dependsOn(projectTasks.named(CheckTask.DEFAULT_NAME)));
+        projectTasks.register(CLEAN_TASK_NAME, CleanTask.class, task -> configureTask(task, extension));
+        projectTasks.named(GRADLE_CLEAN_TASK_NAME, task -> task.dependsOn(projectTasks.named(CLEAN_TASK_NAME)));
 
-        projectTasks.register(AssembleTask.DEFAULT_NAME, AssembleTask.class, task -> configureTask(task, extension));
-        projectTasks.named("assemble", task -> task.dependsOn(projectTasks.named(AssembleTask.DEFAULT_NAME)));
+        projectTasks.register(CHECK_TASK_NAME, CheckTask.class, task -> configureTask(task, extension));
+        projectTasks.named(GRADLE_CHECK_TASK_NAME, task -> task.dependsOn(projectTasks.named(CHECK_TASK_NAME)));
 
-        projectTasks.register(RunScriptTask.DEFAULT_NAME, RunScriptTask.class, this::configureTask);
+        projectTasks.register(ASSEMBLE_TASK_NAME, AssembleTask.class, task -> configureTask(task, extension));
+        projectTasks.named(GRADLE_ASSEMBLE_TASK_NAME, task -> task.dependsOn(projectTasks.named(ASSEMBLE_TASK_NAME)));
     }
 
+    /**
+     * Configures the given task with the plugin extension.
+     *
+     * @param task Task.
+     * @param extension Plugin extension.
+     */
     private void configureTask(final NodeInstallTask task, final FrontendExtension extension) {
         task.setGroup(TASK_GROUP);
         task.setDescription("Downloads and installs a Node distribution.");
@@ -65,6 +124,12 @@ private void configureTask(final NodeInstallTask task, final FrontendExtension e
         task.getNodeInstallDirectory().set(extension.getNodeInstallDirectory());
     }
 
+    /**
+     * Configures the given task with the plugin extension.
+     *
+     * @param task Task.
+     * @param extension Plugin extension.
+     */
     private void configureTask(final YarnInstallTask task, FrontendExtension extension) {
         task.setGroup(TASK_GROUP);
         task.setDescription("Downloads and installs a Yarn distribution.");
@@ -74,48 +139,66 @@ private void configureTask(final YarnInstallTask task, FrontendExtension extensi
         task.getYarnInstallDirectory().set(extension.getYarnInstallDirectory());
     }
 
+    /**
+     * Configures the given task with the plugin extension.
+     *
+     * @param task Task.
+     * @param extension Plugin extension.
+     */
     private void configureTask(final InstallTask task, FrontendExtension extension) {
         task.setGroup(TASK_GROUP);
         task.setDescription("Installs/updates frontend dependencies.");
         task.getYarnEnabled().set(extension.getYarnEnabled());
         task.getNodeInstallDirectory().set(extension.getNodeInstallDirectory());
         task.getYarnInstallDirectory().set(extension.getYarnInstallDirectory());
-        task.dependsOn(NodeInstallTask.DEFAULT_NAME, YarnInstallTask.DEFAULT_NAME);
+        task.dependsOn(NODE_INSTALL_TASK_NAME, YARN_INSTALL_TASK_NAME);
     }
 
+    /**
+     * Configures the given task with the plugin extension.
+     *
+     * @param task Task.
+     * @param extension Plugin extension.
+     */
     private void configureTask(final CleanTask task, FrontendExtension extension) {
         task.setGroup(TASK_GROUP);
         task.setDescription("Cleans frontend resources outside the build directory by running a specific script.");
         task.getYarnEnabled().set(extension.getYarnEnabled());
         task.getNodeInstallDirectory().set(extension.getNodeInstallDirectory());
         task.getYarnInstallDirectory().set(extension.getYarnInstallDirectory());
         task.getCleanScript().set(extension.getCleanScript());
-        task.dependsOn(InstallTask.DEFAULT_NAME);
+        task.dependsOn(INSTALL_TASK_NAME);
     }
 
+    /**
+     * Configures the given task with the plugin extension.
+     *
+     * @param task Task.
+     * @param extension Plugin extension.
+     */
     private void configureTask(final CheckTask task, FrontendExtension extension) {
         task.setGroup(TASK_GROUP);
         task.setDescription("Checks frontend by running a specific script.");
         task.getYarnEnabled().set(extension.getYarnEnabled());
         task.getNodeInstallDirectory().set(extension.getNodeInstallDirectory());
         task.getYarnInstallDirectory().set(extension.getYarnInstallDirectory());
         task.getCheckScript().set(extension.getCheckScript());
-        task.dependsOn(InstallTask.DEFAULT_NAME);
+        task.dependsOn(INSTALL_TASK_NAME);
     }
 
+    /**
+     * Configures the given task with the plugin extension.
+     *
+     * @param task Task.
+     * @param extension Plugin extension.
+     */
     private void configureTask(final AssembleTask task, FrontendExtension extension) {
         task.setGroup(TASK_GROUP);
         task.setDescription("Assembles the frontend by running a specific script.");
         task.getYarnEnabled().set(extension.getYarnEnabled());
         task.getNodeInstallDirectory().set(extension.getNodeInstallDirectory());
         task.getYarnInstallDirectory().set(extension.getYarnInstallDirectory());
         task.getAssembleScript().set(extension.getAssembleScript());
-        task.dependsOn(InstallTask.DEFAULT_NAME);
-    }
-
-    private void configureTask(final RunScriptTask task) {
-        task.setGroup(TASK_GROUP);
-        task.setDescription("Runs a frontend script.");
-        task.dependsOn(InstallTask.DEFAULT_NAME);
+        task.dependsOn(INSTALL_TASK_NAME);
     }
 }

src/main/java/org/siouan/frontendgradleplugin/core/AbstractJob.java

@@ -9,6 +9,11 @@ abstract class AbstractJob {
 
     protected final Task task;
 
+    /**
+     * Builds a job instance related to the given task.
+     *
+     * @param task Task.
+     */
     protected AbstractJob(final Task task) {
         this.task = task;
     }
@@ -17,18 +22,38 @@ private String formatMessage(final String message) {
         return '[' + task.getName() + "] " + message;
     }
 
+    /**
+     * Shortcut to log a DEBUG message with the task's logger.
+     *
+     * @param message Message.
+     */
     protected void logDebug(final String message) {
         task.getLogger().debug(formatMessage(message));
     }
 
+    /**
+     * Shortcut to log an ERROR message with the task's logger.
+     *
+     * @param message Message.
+     */
     protected void logError(final String message) {
         task.getLogger().error(formatMessage(message));
     }
 
+    /**
+     * Shortcut to log a LIFECYCLE message with the task's logger.
+     *
+     * @param message Message.
+     */
     protected void logLifecycle(final String message) {
         task.getLogger().lifecycle(formatMessage(message));
     }
 
+    /**
+     * Shortcut to log a WARN LIFECYCLE message with the task's logger.
+     *
+     * @param message Message.
+     */
     protected void logWarn(final String message, final Throwable throwable) {
         task.getLogger().warn(formatMessage(message), throwable);
     }

src/main/java/org/siouan/frontendgradleplugin/core/DistributionInstallJob.java

@@ -38,6 +38,24 @@ public DistributionInstallJob(final Task task, final DistributionUrlResolver url
         this.installDirectory = installDirectory;
     }
 
+    /**
+     * Installs a distribution:
+     * <ul>
+     * <li>Empty the install directory.</li>
+     * <li>Resolve the URL to download the distribution.</li>
+     * <li>Download the distribution.</li>
+     * <li>Validate the downloaded distribution.</li>
+     * <li>Explode the distribution archive.</li>
+     * <li>Deletes the distribution archive and all unnecessary files.</li>
+     * </ul>
+     *
+     * @throws InvalidDistributionException If the  distribution is invalid.
+     * @throws IOException If an I/O occurs when accessing the file system.
+     * @throws DistributionUrlResolverException If the URL to download the distribution could not be resolved.
+     * @throws DownloadException If the distribution could not be downloaded.
+     * @throws UnsupportedDistributionArchiveException If the distribution archive is not supported, and could not be
+     * exploded.
+     */
     public void install()
         throws InvalidDistributionException, IOException, DistributionUrlResolverException, DownloadException,
         UnsupportedDistributionArchiveException {

src/main/java/org/siouan/frontendgradleplugin/core/DistributionUrlResolver.java

@@ -6,7 +6,7 @@
  * Interface of a component capable to resolve the URL to download a distribution.
  */
 @FunctionalInterface
-public interface DistributionUrlResolver {
+interface DistributionUrlResolver {
 
     /**
      * Resolves the URL to download the distribution.

src/main/java/org/siouan/frontendgradleplugin/core/DistributionValidator.java

@@ -7,7 +7,7 @@
  * Interface of a component capable to validate a downloaded distribution.
  */
 @FunctionalInterface
-public interface DistributionValidator {
+interface DistributionValidator {
 
     /**
      * Validates the distribution in the given file.

src/main/java/org/siouan/frontendgradleplugin/core/Downloader.java

@@ -7,7 +7,7 @@
  * Functional interface of a component capable to download resources.
  */
 @FunctionalInterface
-public interface Downloader {
+interface Downloader {
 
     /**
      * Downloads a resource at a given URL, and moves it to a destination file once completed. Before calling this

src/main/java/org/siouan/frontendgradleplugin/core/DownloaderImpl.java

@@ -25,6 +25,7 @@ public DownloaderImpl(final File temporaryDirectory) {
         this.temporaryDirectory = temporaryDirectory;
     }
 
+    @Override
     public void download(final URL resourceUrl, final File destinationFile) throws DownloadException {
         final String resourceName = new File(resourceUrl.getPath()).getName();
         final File downloadedFile = new File(temporaryDirectory, resourceName);

src/main/java/org/siouan/frontendgradleplugin/core/FileHasher.java

@@ -6,7 +6,8 @@
 /**
  * Component capable of hashing a file.
  */
-public interface FileHasher {
+@FunctionalInterface
+interface FileHasher {
 
     /**
      * Computes the hash of the file if not already done.

src/main/java/org/siouan/frontendgradleplugin/core/FileHasherImpl.java

@@ -29,6 +29,7 @@ public FileHasherImpl() throws NoSuchAlgorithmException {
         this.digest = MessageDigest.getInstance("SHA-256");
     }
 
+    @Override
     public String hash(final File inputFile) throws IOException {
         final ByteBuffer buffer = ByteBuffer.allocate(BUFFER_CAPACITY);
         try (final FileInputStream inputStream = new FileInputStream(inputFile)) {

src/main/java/org/siouan/frontendgradleplugin/core/NodeDistributionChecksumNotFoundException.java

@@ -1,5 +1,9 @@
 package org.siouan.frontendgradleplugin.core;
 
+/**
+ * Exception thrown when the checksum of a Node distribution could not be found in the file providing checksums for all
+ * packages of a given release.
+ */
 public class NodeDistributionChecksumNotFoundException extends FrontendException {
 
 }

src/main/java/org/siouan/frontendgradleplugin/core/NodeDistributionChecksumReader.java

@@ -7,6 +7,7 @@
  * A checksum reader allows to extract the checksum of a given distribution file, from a Node's file providing all
  * checksums for a given Node version.
  */
+@FunctionalInterface
 interface NodeDistributionChecksumReader {
 
     /**

src/main/java/org/siouan/frontendgradleplugin/core/NodeDistributionChecksumReaderImpl.java

@@ -11,6 +11,7 @@
  */
 public class NodeDistributionChecksumReaderImpl implements NodeDistributionChecksumReader {
 
+    @Override
     public String readHash(final File nodeDistributionChecksumFile, final String distributionFilename)
         throws NodeDistributionChecksumNotFoundException, IOException {
         final String trailingValue = "  " + distributionFilename;

src/main/java/org/siouan/frontendgradleplugin/core/NodeDistributionUrlResolver.java

@@ -50,6 +50,7 @@ public NodeDistributionUrlResolver(final String version, final String distributi
         this.jreArch = jreArch;
     }
 
+    @Override
     public URL resolve() throws DistributionUrlResolverException {
         final String urlAsString;
         if (distributionUrl == null) {