FileUtils: add findResources methods

They will be useful for finding scripts inside JARs on the classpath.

These methods were migrated from imagej-ui-swing; see:
https://github.com/imagej/imagej-ui-swing/blob/imagej-ui-swing-0.18.0/src/main/java/net/imagej/ui/swing/script/FileFunctions.java

Author: ctrueden

src/main/java/org/scijava/util/FileUtils.java

@@ -48,7 +48,10 @@
 import java.util.ArrayList;
 import java.util.Calendar;
 import java.util.Collection;
+import java.util.Collections;
 import java.util.Date;
+import java.util.HashMap;
+import java.util.Map;
 import java.util.jar.JarEntry;
 import java.util.jar.JarFile;
 import java.util.regex.Matcher;
@@ -607,6 +610,82 @@ else if (protocol.equals("jar")) {
 		return result;
 	}
 
+	/**
+	 * Finds {@link URL}s of available resources. Both JAR files and files on disk
+	 * are searched, according to the following mechanism:
+	 * <ol>
+	 * <li>Resources at the given {@code pathPrefix} are discovered using
+	 * {@link ClassLoader#getResources(String)} with the current thread's context
+	 * class loader. In particular, this invocation discovers resources in JAR
+	 * files beneath the given {@code pathPrefix}.</li>
+	 * <li>The directory named {@code pathPrefix} beneath the given
+	 * {@code baseDirectory} is scanned last, so that users can more easily
+	 * override resources provided inside JAR files by placing a resource of the
+	 * same name within that directory.</li>
+	 * </ol>
+	 * <p>
+	 * In both cases, resources are then recursively scanned using
+	 * {@link #listContents(URL)}, and anything matching the given {@code regex}
+	 * pattern is added to the output map.
+	 * </p>
+	 *
+	 * @param regex The regex to use when matching resources, or null to match
+	 *          everything.
+	 * @param pathPrefix The path to search for resources.
+	 * @param baseDirectory The {@code baseDirectory/pathPrefix} directory to scan
+	 *          <em>after</em> the URL resources.
+	 * @return A map of URLs referencing the matched resources.
+	 * @see AppUtils#getBaseDirectory
+	 */
+	public static Map<String, URL> findResources(final String regex,
+		final String pathPrefix, final File baseDirectory)
+	{
+		// scan URL resource paths first
+		final ClassLoader loader = Thread.currentThread().getContextClassLoader();
+		final ArrayList<URL> urls = new ArrayList<>();
+		try {
+			urls.addAll(Collections.list(loader.getResources(pathPrefix + "/")));
+		}
+		catch (final IOException exc) {
+			// error loading resources; proceed with an empty list
+		}
+
+		// scan directory second; user can thus override resources from JARs
+		if (baseDirectory != null) {
+			try {
+				urls.add(new File(baseDirectory, pathPrefix).toURI().toURL());
+			}
+			catch (final MalformedURLException exc) {
+				// error adding directory; proceed without it
+			}
+		}
+
+		return findResources(regex, urls);
+	}
+
+	/**
+	 * Finds {@link URL}s of resources known to ImageJ.
+	 * <p>
+	 * Each of the given {@link URL}s is recursively scanned using
+	 * {@link #listContents(URL)}, and anything matching the given {@code regex}
+	 * pattern is added to the output map.</li>
+	 *
+	 * @param regex The regex to use when matching resources, or null to match
+	 *          everything.
+	 * @param urls Paths to search for resources.
+	 * @return A map of URLs referencing the matched resources.
+	 */
+	public static Map<String, URL> findResources(final String regex,
+		final Iterable<URL> urls)
+	{
+		final HashMap<String, URL> result = new HashMap<>();
+		final Pattern pattern = regex == null ? null : Pattern.compile(regex);
+		for (final URL url : urls) {
+			getResources(pattern, result, url);
+		}
+		return result;
+	}
+
 	// -- Helper methods --
 
 	/** Builds the {@link #VERSION_PATTERN} constant. */
@@ -639,6 +718,45 @@ private static String classifiers() {
 		return sb.toString();
 	}
 
+	/** Helper method of {@link #findResources(String, Iterable)}. */
+	private static void getResources(final Pattern pattern,
+		final Map<String, URL> result, final URL base)
+	{
+		final String prefix = urlPath(base);
+		if (prefix == null) return; // unsupported base URL
+
+		for (final URL url : FileUtils.listContents(base)) {
+			final String s = urlPath(url);
+			if (s == null || !s.startsWith(prefix)) continue;
+
+			if (pattern == null || pattern.matcher(s).matches()) {
+				// this resource matches the pattern
+				final String key = urlPath(s.substring(prefix.length()));
+				if (key != null) result.put(key, url);
+			}
+		}
+	}
+
+	/** Helper method of {@link #getResources(Pattern, Map, URL)}. */
+	private static String urlPath(final URL url) {
+		try {
+			return url.toURI().toString();
+		}
+		catch (final URISyntaxException exc) {
+			return null;
+		}
+	}
+
+	/** Helper method of {@link #getResources(Pattern, Map, URL)}. */
+	private static String urlPath(final String path) {
+		try {
+			return new URI(path).getPath();
+		}
+		catch (final URISyntaxException exc) {
+			return null;
+		}
+	}
+
 	// -- Deprecated methods --
 
 	/**