Add a method to detect Java 3D extensions

Author: ctrueden

src/main/java/org/scijava/java3d/DefaultJava3DService.java

@@ -0,0 +1,76 @@
+/*
+ * #%L
+ * Utility classes for working with Java 3D.
+ * %%
+ * Copyright (C) 2015 Board of Regents of the University of
+ * Wisconsin-Madison.
+ * %%
+ * 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.java3d;
+
+import java.io.File;
+import java.util.ArrayList;
+import java.util.List;
+
+import org.scijava.plugin.Plugin;
+import org.scijava.service.AbstractService;
+import org.scijava.service.Service;
+
+/**
+ * Default service for working with Java 3D.
+ * 
+ * @author Curtis Rueden
+ */
+@Plugin(type = Service.class)
+public class DefaultJava3DService extends AbstractService implements
+	Java3DService
+{
+
+	@Override
+	public List<File> getLibExtLocations() {
+		final ArrayList<File> files = new ArrayList<File>();
+		final String extDirs = System.getProperty("java.ext.dirs");
+		if (extDirs == null) return files;
+		for (final String dir : extDirs.split(":")) {
+			checkLibExtDirectory(files, dir);
+		}
+		return files;
+	}
+
+	// -- Helper methods --
+
+	private void checkLibExtDirectory(final ArrayList<File> files,
+		final String dir)
+	{
+		checkFile(files, new File(dir, "j3dcore.jar"));
+		checkFile(files, new File(dir, "vecmath.jar"));
+		checkFile(files, new File(dir, "j3dutils.jar"));
+	}
+
+	private void checkFile(ArrayList<File> files, File file) {
+		if (file.exists()) files.add(file);
+	}
+
+}

src/main/java/org/scijava/java3d/Java3DService.java

@@ -30,13 +30,62 @@
 
 package org.scijava.java3d;
 
+import java.io.File;
+import java.util.List;
+
 import org.scijava.service.SciJavaService;
+import org.scijava.ui.UIService;
 
 /**
  * Interface for services which work with Java 3D.
- *
+ * <p>
+ * Historically, Java 3D was installed as an extension to the Java Runtime
+ * Environment, meaning that JAR files and native libraries were placed in the
+ * {@code lib/ext} directory of the JRE installation, or manually appended to
+ * the Java extensions via the {@code java.ext.dirs} system property.
+ * </p>
+ * <p>
+ * However, that approach has many downsides:
+ * </p>
+ * <ul>
+ * <li>Users must install Java 3D manually, independent of the application.</li>
+ * <li>Thus, at runtime, the application cannot manage the version of Java 3D in
+ * the same was that it manages versions of its regular dependencies.</li>
+ * <li>Similarly, at build time, the Java 3D dependency must be treated
+ * specially (e.g., with Maven, using {@code provided} scope in the POM).</li>
+ * </ul>
+ * <p>
+ * Failure to manage Java 3D installations as needed can result in cryptic
+ * version-skew-related error messages, such as {@link NoSuchMethodError} or
+ * even native-library-related errors. This situation is especially prevalent on
+ * OS X, where Java 3D 1.3 was pre-installed in
+ * {@code /System/Library/Java/Extensions} on older versions of the OS, and left
+ * in place after OS upgrades (despite Java itself being uninstalled).
+ * </p>
+ * <p>
+ * These days, Java 3D is built on top of JOGL, and <a
+ * href="https://github.com/hharrison/java3d-core">available on GitHub</a>. But
+ * old installations of Java 3D still lurk, waiting to disrupt applications at
+ * runtime: libraries present on the Java extensions path take precedence over
+ * those on the regular class path.
+ * </p>
+ * <p>
+ * This service mitigates the issue by warning users (via
+ * {@link UIService#showDialog}) if any Java 3D installations are detected as
+ * Java extensions, and asking the user to clean them up before proceeding.
+ * Consequently, applications can now use the modern JOGL version of Java 3D,
+ * without worrying about obsolete versions of Java 3D interfering at runtime.
+ * </p>
+ * 
  * @author Curtis Rueden
  */
 public interface Java3DService extends SciJavaService {
 
+	/**
+	 * Gets the locations where Java 3D is installed as an extension.
+	 * 
+	 * @return a {@link List} of directories containing Java 3D libraries.
+	 */
+	List<File> getLibExtLocations();
+
 }

src/test/java/org/scijava/java3d/Java3DServiceTest.java

@@ -30,11 +30,88 @@
 
 package org.scijava.java3d;
 
+import static org.junit.Assert.assertEquals;
+
+import java.io.File;
+import java.io.IOException;
+import java.util.HashSet;
+
+import org.junit.After;
+import org.junit.Before;
+import org.junit.Test;
+import org.scijava.Context;
+import org.scijava.util.FileUtils;
+
 /**
  * Tests {@link Java3DService}.
  *
  * @author Curtis Rueden
  */
 public class Java3DServiceTest {
 
+	private Context context;
+	private Java3DService j3d;
+	private File tmp1;
+	private File tmp2;
+
+	@Before
+	public void setUp() throws IOException {
+		context = new Context(Java3DService.class);
+		j3d = context.service(Java3DService.class);
+
+		tmp1 = FileUtils.createTemporaryDirectory("libExt", "1");
+		tmp2 = FileUtils.createTemporaryDirectory("libExt", "2");
+	}
+
+	@After
+	public void tearDown() {
+		FileUtils.deleteRecursively(tmp1);
+		FileUtils.deleteRecursively(tmp2);
+	}
+
+	@Test
+	public void testGetLibExtLocations() throws IOException {
+		final HashSet<File> expected = new HashSet<File>();
+
+		System.setProperty("java.ext.dirs", tmp1.getAbsolutePath() + ":" +
+			tmp2.getAbsolutePath());
+
+		final File j3dcore1 = createFile(tmp1, "j3dcore.jar");
+		expected.add(j3dcore1);
+		assertEquals(expected, libExtFiles());
+
+		final File j3dcore2 = createFile(tmp2, "j3dcore.jar");
+		expected.add(j3dcore2);
+		assertEquals(expected, libExtFiles());
+
+		final File vecmath = createFile(tmp1, "vecmath.jar");
+		createFile(tmp2, "red-herring");
+		expected.add(vecmath);
+		assertEquals(expected, libExtFiles());
+
+		System.setProperty("java.ext.dirs", tmp1.getAbsolutePath());
+		expected.remove(j3dcore2);
+		assertEquals(expected, libExtFiles());
+
+		System.setProperty("java.ext.dirs", "");
+		expected.clear();
+		assertEquals(expected, libExtFiles());
+
+		System.clearProperty("java.ext.dirs");
+		assertEquals(expected, libExtFiles());
+	}
+
+	// -- Helper methods --
+
+	private File createFile(final File dir, final String name) throws IOException
+	{
+		final File file = new File(dir, name);
+		file.createNewFile();
+		return file;
+	}
+
+	private HashSet<File> libExtFiles() {
+		return new HashSet<File>(j3d.getLibExtLocations());
+	}
+
 }