Merge branch 'poms'

This branch adds a getAllPOMs() utility method to org.scijava.util.POM
which searches JARs on the classpath for Maven POM metadata.

It also improves the POM class in various other ways, including the
addition of a constructor that takes a URL, more accessor methods, and
making POMs naturally comparable by GAV.

Author: ctrueden

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

@@ -35,6 +35,10 @@
 import java.io.IOException;
 import java.io.InputStream;
 import java.net.URL;
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.Enumeration;
+import java.util.List;
 
 import javax.xml.parsers.ParserConfigurationException;
 
@@ -45,7 +49,7 @@
  * 
  * @author Curtis Rueden
  */
-public class POM extends XML {
+public class POM extends XML implements Comparable<POM> {
 
 	/** Parses a POM from the given file. */
 	public POM(final File file) throws ParserConfigurationException,
@@ -54,6 +58,13 @@ public POM(final File file) throws ParserConfigurationException,
 		super(file);
 	}
 
+	/** Parses a POM from the given URL. */
+	public POM(final URL url) throws ParserConfigurationException, SAXException,
+		IOException
+	{
+		super(url);
+	}
+
 	/** Parses a POM from the given input stream. */
 	public POM(final InputStream in) throws ParserConfigurationException,
 		SAXException, IOException
@@ -62,8 +73,8 @@ public POM(final InputStream in) throws ParserConfigurationException,
 	}
 
 	/** Parses a POM from the given string. */
-	public POM(final String s) throws ParserConfigurationException,
-		SAXException, IOException
+	public POM(final String s) throws ParserConfigurationException, SAXException,
+		IOException
 	{
 		super(s);
 	}
@@ -89,6 +100,52 @@ public String getVersion() {
 		return cdata("//project/parent/version");
 	}
 
+	/** Gets the project name. */
+	public String getProjectName() {
+		return cdata("//project/name");
+	}
+
+	/** Gets the project description. */
+	public String getProjectDescription() {
+		return cdata("//project/description");
+	}
+
+	/** Gets the project URL. */
+	public String getProjectURL() {
+		return cdata("//project/url");
+	}
+
+	/** Gets the project inception year. */
+	public String getProjectInceptionYear() {
+		return cdata("//project/inceptionYear");
+	}
+
+	/** Gets the organization name. */
+	public String getOrganizationName() {
+		return cdata("//project/organization/name");
+	}
+
+	/** Gets the organization URL. */
+	public String getOrganizationURL() {
+		return cdata("//project/organization/url");
+	}
+
+	// -- Comparable methods --
+
+	@Override
+	public int compareTo(final POM pom) {
+		// sort by groupId first
+		final int gid = getGroupId().compareTo(pom.getGroupId());
+		if (gid != 0) return gid;
+
+		// sort by artifactId second
+		final int aid = getArtifactId().compareTo(pom.getArtifactId());
+		if (aid != 0) return aid;
+
+		// finally, sort by version
+		return compareVersions(getVersion(), pom.getVersion());
+	}
+
 	// -- Utility methods --
 
 	/**
@@ -103,13 +160,15 @@ public static POM getPOM(final Class<?> c, final String groupId,
 	{
 		try {
 			final URL location = ClassUtils.getLocation(c);
-			if (!location.getProtocol().equals("file") || location.toString().endsWith(".jar")) {
+			if (!location.getProtocol().equals("file") ||
+				location.toString().endsWith(".jar"))
+			{
 				// look for pom.xml in JAR's META-INF/maven subdirectory
 				final String pomPath =
 					"META-INF/maven/" + groupId + "/" + artifactId + "/pom.xml";
-				final URL pomURL = new URL("jar:" + location.toString() + "!/" + pomPath);
-				final InputStream pomStream = pomURL.openStream();
-				return new POM(pomStream);
+				final URL pomURL =
+					new URL("jar:" + location.toString() + "!/" + pomPath);
+				return new POM(pomURL);
 			}
 			// look for the POM in the class's base directory
 			final File file = FileUtils.urlToFile(location);
@@ -128,4 +187,107 @@ public static POM getPOM(final Class<?> c, final String groupId,
 		}
 	}
 
+	/** Gets all available Maven POMs on the class path. */
+	public static List<POM> getAllPOMs() {
+		// find all META-INF/maven/ folders on the classpath
+		final String pomPrefix = "META-INF/maven/";
+		final ClassLoader classLoader =
+			Thread.currentThread().getContextClassLoader();
+		final Enumeration<URL> resources;
+		try {
+			resources = classLoader.getResources(pomPrefix);
+		}
+		catch (final IOException exc) {
+			return null;
+		}
+
+		final ArrayList<POM> poms = new ArrayList<POM>();
+
+		// recursively list contents of META-INF/maven/ directories
+		for (final URL resource : new IteratorPlus<URL>(resources)) {
+			for (final URL url : FileUtils.listContents(resource)) {
+				// look for pom.xml files amongst the contents
+				if (url.getPath().endsWith("/pom.xml")) {
+					try {
+						poms.add(new POM(url));
+					}
+					catch (final IOException exc) {
+						// ignore and continue
+					}
+					catch (final ParserConfigurationException exc) {
+						// ignore and continue
+					}
+					catch (final SAXException exc) {
+						// ignore and continue
+					}
+				}
+			}
+		}
+
+		return poms;
+	}
+
+	/**
+	 * Compares two version strings.
+	 * <p>
+	 * Given the variation between versioning styles, there is no single
+	 * comparison method that can possibly be correct 100% of the time. So this
+	 * method works on a "best effort" basis; YMMV.
+	 * </p>
+	 * <p>
+	 * The algorithm is as follows:
+	 * </p>
+	 * <ul>
+	 * <li>Split on non-alphameric characters.</li>
+	 * <li>Compare each token one by one.</li>
+	 * <li>Comparison is numerical when possible (i.e., when an integer can be
+	 * parsed from the token), and lexicographic otherwise.</li>
+	 * <li>If one version string runs out of tokens, the version with additional
+	 * tokens remaining is considered <em>greater than</em> the version without
+	 * additional tokens.</li>
+	 * <li>There is one exception: if two version strings are identical except
+	 * that one has a suffix beginning with a dash ({@code -}), the version with
+	 * suffix will be considered <em>less than</em> the one without a suffix. The
+	 * reason for this is to accommodate the <a
+	 * href="http://semver.org/">SemVer</a> versioning scheme's usage of
+	 * "prerelease" version suffixes. For example, {@code 2.0.0} will compare
+	 * greater than {@code 2.0.0-beta-1}, whereas {@code 2.0.0} will compare less
+	 * than {@code 2.0.0.1}.</li>
+	 * </ul>
+	 * 
+	 * @return a negative integer, zero, or a positive integer as the first
+	 *         argument is less than, equal to, or greater than the second.
+	 * @see Comparator#compare(Object, Object)
+	 */
+	public static int compareVersions(final String v1, final String v2) {
+		final String[] t1 = v1.split("[^\\w]");
+		final String[] t2 = v2.split("[^\\w]");
+		final int size = Math.min(t1.length, t2.length);
+		for (int i = 0; i < size; i++) {
+			try {
+				final long n1 = Long.parseLong(t1[i]);
+				final long n2 = Long.parseLong(t2[i]);
+				if (n1 < n2) return -1;
+				if (n1 > n2) return 1;
+			}
+			catch (final NumberFormatException exc) {
+				final int result = t1[i].compareTo(t2[i]);
+				if (result != 0) return result;
+			}
+		}
+		if (t1.length == t2.length) return 0; // versions match
+
+		// check for SemVer prerelease versions
+		if (v1.startsWith(v2) && v1.charAt(v2.length()) == '-') {
+			// v1 is a prerelease version of v2
+			return -1;
+		}
+		if (v2.startsWith(v1) && v2.charAt(v1.length()) == '-') {
+			// v2 is a prerelease version of v1
+			return 1;
+		}
+
+		return t1.length < t2.length ? -1 : 1;
+	}
+
 }

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

@@ -38,6 +38,7 @@
 import java.io.InputStream;
 import java.io.PrintStream;
 import java.io.StringWriter;
+import java.net.URL;
 
 import javax.xml.parsers.DocumentBuilder;
 import javax.xml.parsers.DocumentBuilderFactory;
@@ -66,6 +67,9 @@
  */
 public class XML {
 
+	/** Path to the XML document (e.g., a file or URL). */
+	private final String path;
+
 	/** The parsed XML DOM. */
 	private final Document doc;
 
@@ -76,31 +80,49 @@ public class XML {
 	public XML(final File file) throws ParserConfigurationException,
 		SAXException, IOException
 	{
-		this(loadXML(file));
+		this(file.getAbsolutePath(), loadXML(file));
+	}
+
+	/** Parses XML from the given URL. */
+	public XML(final URL url) throws ParserConfigurationException,
+		SAXException, IOException
+	{
+		this(url.getPath(), loadXML(url));
 	}
 
 	/** Parses XML from the given input stream. */
 	public XML(final InputStream in) throws ParserConfigurationException,
 		SAXException, IOException
 	{
-		this(loadXML(in));
+		this(null, loadXML(in));
 	}
 
 	/** Parses XML from the given string. */
 	public XML(final String s) throws ParserConfigurationException,
 		SAXException, IOException
 	{
-		this(loadXML(s));
+		this(null, loadXML(s));
 	}
 
 	/** Creates an XML object for an existing document. */
 	public XML(final Document doc) {
+		this(null, doc);
+	}
+
+	/** Creates an XML object for an existing document. */
+	public XML(final String path, final Document doc) {
+		this.path = path;
 		this.doc = doc;
 		xpath = XPathFactory.newInstance().newXPath();
 	}
 
 	// -- XML methods --
 
+	/** Gets the path to the XML document, or null if none. */
+	public String getPath() {
+		return path;
+	}
+
 	/** Gets the XML's DOM representation. */
 	public Document getDocument() {
 		return doc;
@@ -150,6 +172,16 @@ private static Document loadXML(final File file)
 		return createBuilder().parse(file.getAbsolutePath());
 	}
 
+	/** Loads an XML document from the given URL. */
+	private static Document loadXML(final URL url)
+		throws ParserConfigurationException, SAXException, IOException
+	{
+		final InputStream in = url.openStream();
+		final Document document = loadXML(in);
+		in.close();
+		return document;
+	}
+
 	/** Loads an XML document from the given input stream. */
 	protected static Document loadXML(final InputStream in)
 		throws ParserConfigurationException, SAXException, IOException

src/test/java/org/scijava/util/POMTest.java

@@ -0,0 +1,76 @@
+/*
+ * #%L
+ * SciJava Common shared library for SciJava software.
+ * %%
+ * Copyright (C) 2009 - 2014 Board of Regents of the University of
+ * Wisconsin-Madison, Broad Institute of MIT and Harvard, and Max Planck
+ * Institute of Molecular Cell Biology and Genetics.
+ * %%
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * 
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ * #L%
+ */
+
+package org.scijava.util;
+
+import static org.junit.Assert.assertTrue;
+
+import org.junit.Test;
+
+/**
+ * Tests methods of {@link POM}.
+ * 
+ * @author Curtis Rueden
+ */
+public class POMTest {
+
+	@Test
+	public void testCompareVersions() {
+		// basic checks
+		assertTrue(POM.compareVersions("1", "2") < 0);
+		assertTrue(POM.compareVersions("1.0", "2.0") < 0);
+		assertTrue(POM.compareVersions("1.0", "1.1") < 0);
+		assertTrue(POM.compareVersions("1.0.0", "2.0.0") < 0);
+
+		// sanity checks for argument order
+		assertTrue(POM.compareVersions("2", "1") > 0);
+		assertTrue(POM.compareVersions("2.0", "1.0") > 0);
+		assertTrue(POM.compareVersions("1.1", "1.0") > 0);
+		assertTrue(POM.compareVersions("2.0.0", "1.0.0") > 0);
+
+		// more complex/unusual checks
+		assertTrue(POM.compareVersions("1.0-RC1", "1.0-RC2") < 0);
+		assertTrue(POM.compareVersions("1.0-RC-1", "1.0-RC-2") < 0);
+		assertTrue(POM.compareVersions("1.0-RC-2", "1.0-RC-10") < 0);
+		assertTrue(POM.compareVersions("0.4-alpha", "0.4-beta") < 0);
+		assertTrue(POM.compareVersions("foo", "bar") > 0);
+
+		// checks which expose bugs/limitations
+		assertTrue(POM.compareVersions("1.0-RC2", "1.0-RC10") > 0);
+		assertTrue(POM.compareVersions("1.0-rc1", "1.0-RC2") > 0);
+
+		// check that varying numbers of digits are handled properly
+		assertTrue(POM.compareVersions("2.0.0", "2.0.0.1") < 0);
+		// check that SemVer prerelease versions are handled properly
+		assertTrue(POM.compareVersions("2.0.0", "2.0.0-beta-1") > 0);
+	}
+
+}