Added tests and javadoc for new non-composite classpath strategies.

Added tests and javadoc for classpath and module path formulation logic related to processing#5753 / processing#5750 including support for jmod (Jigsaw) and OpenJFX. This only includes non-composite strategies (not RuntimePathFactoryStrategyCollection) which will be addressed in a later commit.

java/build.xml

@@ -105,6 +105,7 @@
 
   <path id="classpath.test">
     <pathelement location="../core/library-test/junit-4.8.1.jar" />
+    <pathelement location="../core/library-test/mockito-all-1.10.19.jar" />
     <pathelement location = "bin-test" />
     <path refid="classpath.base" />
   </path>
@@ -157,6 +158,11 @@
     <junit haltonfailure="true">
       <classpath refid="classpath.test" />
       <formatter type="brief" usefile="false" />
+      <batchtest>
+        <fileset dir="test">
+          <include name="**/*Test.java" />
+        </fileset>
+      </batchtest>
     </junit>
   </target>
 

java/src/processing/mode/java/pdex/PreprocessingService.java

@@ -2,7 +2,7 @@
 
 /*
 Part of the Processing project - http://processing.org
-Copyright (c) 2012-15 The Processing Foundation
+Copyright (c) 2012-19 The Processing Foundation
 
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License version 2

java/src/processing/mode/java/pdex/util/runtime/RuntimePathBuilder.java

@@ -1,3 +1,23 @@
+/* -*- mode: java; c-basic-offset: 2; indent-tabs-mode: nil -*- */
+
+/*
+Part of the Processing project - http://processing.org
+Copyright (c) 2012-19 The Processing Foundation
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License version 2
+as published by the Free Software Foundation.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software Foundation, Inc.
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+*/
+
 package processing.mode.java.pdex.util.runtime;
 
 import com.google.classpath.ClassPathFactory;
@@ -19,6 +39,14 @@
 import java.util.stream.Stream;
 
 
+/**
+ * Builder which generates runtime paths using a series of caches.
+ *
+ * <p>
+ * Builder which helps generate classpath (and module path) entries for sketches using stateful
+ * and individually invalidate-able caches to prevent duplicate work.
+ * </p>
+ */
 public class RuntimePathBuilder {
   private final List<CachedRuntimePathFactory> libraryDependentCaches;
   private final List<CachedRuntimePathFactory> libraryImportsDependentCaches;
@@ -29,6 +57,9 @@ public class RuntimePathBuilder {
 
   private final ClassPathFactory classPathFactory;
 
+  /**
+   * Create a new runtime path builder with empty caches.
+   */
   public RuntimePathBuilder() {
     classPathFactory  = new ClassPathFactory();
 
@@ -88,18 +119,33 @@ public RuntimePathBuilder() {
     codeFolderDependentCaches.add(codeFolderPathFactory);
   }
 
+  /**
+   * Invalidate all of the runtime path caches associated with sketch libraries.
+   */
   public void markLibrariesChanged() {
     invalidateAll(libraryDependentCaches);
   }
 
+  /**
+   * Invalidate all of the runtime path caches associated with sketch library imports.
+   */
   public void markLibraryImportsChanged() {
     invalidateAll(libraryImportsDependentCaches);
   }
 
+  /**
+   * Invalidate all of the runtime path caches associated with the code folder having changed.
+   */
   public void markCodeFolderChanged() {
     invalidateAll(codeFolderDependentCaches);
   }
 
+  /**
+   * Generate a classpath and inject it into a {PreprocessedSketch.Builder}.
+   *
+   * @param result The {PreprocessedSketch.Builder} into which the classpath should be inserted.
+   * @param mode The {JavaMode} for which the classpath should be generated.
+   */
   public void prepareClassPath(PreprocessedSketch.Builder result, JavaMode mode) {
     List<ImportStatement> programImports = result.programImports;
     Sketch sketch = result.sketch;
@@ -108,12 +154,27 @@ public void prepareClassPath(PreprocessedSketch.Builder result, JavaMode mode) {
     prepareSearchClassPath(result, mode, programImports, sketch);
   }
 
+  /**
+   * Invalidate all of the caches in a provided collection.
+   *
+   * @param caches The caches to invalidate so that, when their value is requested again, the value
+   *    is generated again.
+   */
   private void invalidateAll(List<CachedRuntimePathFactory> caches) {
     for (CachedRuntimePathFactory cache : caches) {
       cache.invalidateCache();
     }
   }
 
+  /**
+   * Prepare the classpath required for the sketch's execution.
+   *
+   * @param result The PreprocessedSketch builder into which the classpath and class loader should
+   *    be injected.
+   * @param mode The JavaMode for which a sketch classpath should be generated.
+   * @param programImports The imports listed by the sketch (user imports).
+   * @param sketch The sketch for which the classpath is being generated.
+   */
   private void prepareSketchClassPath(PreprocessedSketch.Builder result, JavaMode mode,
         List<ImportStatement> programImports, Sketch sketch) {
 
@@ -138,6 +199,15 @@ private void prepareSketchClassPath(PreprocessedSketch.Builder result, JavaMode
     result.classPathArray = classPathArray;
   }
 
+  /**
+   * Prepare the classpath for searching in case of import suggestions.
+   *
+   * @param result The PreprocessedSketch builder into which the search classpath should be
+   *    injected.
+   * @param mode The JavaMode for which a sketch classpath should be generated.
+   * @param programImports The imports listed by the sketch (user imports).
+   * @param sketch The sketch for which the classpath is being generated.
+   */
   private void prepareSearchClassPath(PreprocessedSketch.Builder result, JavaMode mode,
         List<ImportStatement> programImports, Sketch sketch) {
 

java/src/processing/mode/java/pdex/util/runtime/RuntimePathUtil.java

@@ -1,12 +1,42 @@
+/* -*- mode: java; c-basic-offset: 2; indent-tabs-mode: nil -*- */
+
+/*
+Part of the Processing project - http://processing.org
+Copyright (c) 2012-19 The Processing Foundation
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License version 2
+as published by the Free Software Foundation.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software Foundation, Inc.
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+*/
+
 package processing.mode.java.pdex.util.runtime;
 
 import java.io.File;
 import java.util.Arrays;
 import java.util.List;
 import java.util.stream.Collectors;
 
+
+/**
+ * Common convenience functions for runtime path formulation.
+ */
 public class RuntimePathUtil {
 
+  /**
+   * Remove invalid entries in a classpath string.
+   *
+   * @param classPathString The classpath to clean.
+   * @return The cleaned classpath entries without invalid entries.
+   */
   public static List<String> sanitizeClassPath(String classPathString) {
     // Make sure class path does not contain empty string (home dir)
     return Arrays.stream(classPathString.split(File.pathSeparator))

java/src/processing/mode/java/pdex/util/runtime/strategy/CachedRuntimePathFactory.java

@@ -1,3 +1,23 @@
+/* -*- mode: java; c-basic-offset: 2; indent-tabs-mode: nil -*- */
+
+/*
+Part of the Processing project - http://processing.org
+Copyright (c) 2012-19 The Processing Foundation
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License version 2
+as published by the Free Software Foundation.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software Foundation, Inc.
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+*/
+
 package processing.mode.java.pdex.util.runtime.strategy;
 
 import processing.app.Sketch;
@@ -7,20 +27,53 @@
 import java.util.List;
 import java.util.concurrent.atomic.AtomicReference;
 
+
+/**
+ * Runtime path factory which caches the results of another runtime path factory.
+ *
+ * <p>
+ * Runtime path factory which decorates another {RuntimePathFactoryStrategy} that caches the
+ * results of another runtime path factory. This is a lazy cached getter so the value will not be
+ * resolved until it is requested.
+ * </p>
+ */
 public class CachedRuntimePathFactory implements RuntimePathFactoryStrategy {
 
   private AtomicReference<List<String>> cachedResult;
   private RuntimePathFactoryStrategy innerStrategy;
 
+  /**
+   * Create a new cache around {RuntimePathFactoryStrategy}.
+   *
+   * @param newInnerStrategy The strategy to cache.
+   */
   public CachedRuntimePathFactory(RuntimePathFactoryStrategy newInnerStrategy) {
     cachedResult = new AtomicReference<>(null);
     innerStrategy = newInnerStrategy;
   }
 
+  /**
+   * Invalidate the cached path so that, when requested next time, it will be rebuilt from scratch.
+   */
   public void invalidateCache() {
     cachedResult.set(null);
   }
 
+  /**
+   * Return the cached classpath or, if not cached, build a classpath using the inner strategy.
+   *
+   * <p>
+   * Return the cached classpath or, if not cached, build a classpath using the inner strategy.
+   * Note that this getter will not check to see if mode, imports, or sketch have changed. If a
+   * cached value is available, it will be returned without examining the identity of the
+   * parameters.
+   * </p>
+   *
+   * @param mode The {JavaMode} for which the classpath should be built.
+   * @param imports The sketch (user) imports.
+   * @param sketch The sketch for which a classpath is to be returned.
+   * @return Newly generated classpath.
+   */
   @Override
   public List<String> buildClasspath(JavaMode mode, List<ImportStatement> imports, Sketch sketch) {
     return cachedResult.updateAndGet((cachedValue) ->

java/src/processing/mode/java/pdex/util/runtime/strategy/CodeFolderRuntimePathFactory.java

@@ -1,3 +1,23 @@
+/* -*- mode: java; c-basic-offset: 2; indent-tabs-mode: nil -*- */
+
+/*
+Part of the Processing project - http://processing.org
+Copyright (c) 2012-19 The Processing Foundation
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License version 2
+as published by the Free Software Foundation.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software Foundation, Inc.
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+*/
+
 package processing.mode.java.pdex.util.runtime.strategy;
 
 import processing.app.Sketch;
@@ -10,7 +30,11 @@
 import java.util.List;
 
 
+/**
+ * Path factory which includes resources like jars within the sketch code folder.
+ */
 public class CodeFolderRuntimePathFactory implements RuntimePathFactoryStrategy {
+
   @Override
   public List<String> buildClasspath(JavaMode mode, List<ImportStatement> imports, Sketch sketch) {
     StringBuilder classPath = new StringBuilder();
@@ -24,4 +48,5 @@ public List<String> buildClasspath(JavaMode mode, List<ImportStatement> imports,
 
     return RuntimePathUtil.sanitizeClassPath(classPath.toString());
   }
+
 }

java/src/processing/mode/java/pdex/util/runtime/strategy/CoreLibraryRuntimePathFactory.java

@@ -1,3 +1,23 @@
+/* -*- mode: java; c-basic-offset: 2; indent-tabs-mode: nil -*- */
+
+/*
+Part of the Processing project - http://processing.org
+Copyright (c) 2012-19 The Processing Foundation
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License version 2
+as published by the Free Software Foundation.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software Foundation, Inc.
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+*/
+
 package processing.mode.java.pdex.util.runtime.strategy;
 
 import processing.app.Library;
@@ -10,6 +30,9 @@
 import java.util.List;
 
 
+/**
+ * Runtime path factory for libraries part of the processing mode (like {JavaMode}).
+ */
 public class CoreLibraryRuntimePathFactory implements RuntimePathFactoryStrategy {
 
   @Override