Merge pull request #275 from scijava/more-handles-multifile

Add browsing support for Locations

Author: ctrueden

src/main/java/org/scijava/io/location/BrowsableLocation.java

@@ -0,0 +1,103 @@
+/*
+ * #%L
+ * SciJava Common shared library for SciJava software.
+ * %%
+ * Copyright (C) 2009 - 2017 Board of Regents of the University of
+ * Wisconsin-Madison, Broad Institute of MIT and Harvard, Max Planck
+ * Institute of Molecular Cell Biology and Genetics, University of
+ * Konstanz, and KNIME GmbH.
+ * %%
+ * 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.io.location;
+
+import java.io.IOException;
+import java.util.Collections;
+import java.util.Set;
+
+/**
+ * A {@link Location} that offers methods to browse other locations relative to
+ * it.
+ *
+ * @author Gabriel Einsdorf
+ * @author Curtis Rueden
+ */
+public interface BrowsableLocation extends Location {
+
+	/**
+	 * Obtains a location pointing to the parent directory of this one.
+	 * 
+	 * @return the parent location of this one, or <code>null</code> if this
+	 *         location has no parent.
+	 * @throws IOException if something goes wrong obtaining the parent.
+	 */
+	BrowsableLocation parent() throws IOException;
+
+	/**
+	 * Obtains a collection of locations for whom this location is the parent.
+	 * Note that this will only succeed if calls to {@link #isDirectory()} on this
+	 * location return <code>true</code>.
+	 * 
+	 * @return A set containing the children of this location, or
+	 *         {@link Collections#EMPTY_SET} if this location has no children.
+	 * @throws IOException if something goes wrong obtaining the children.
+	 * @throws IllegalArgumentException if this location is not a directory (i.e.,
+	 *           {@link #isDirectory()} returns false).
+	 */
+	Set<BrowsableLocation> children() throws IOException;
+
+	/**
+	 * Obtains a location relative to this one, which will be configured
+	 * like the current location, but point to a the file specified by the
+	 * <code>path</code> parameter.
+	 *
+	 * @param path the relative path of the desired location.
+	 * @return A location that points to the specified file location.
+	 * @throws IOException if something goes wrong obtaining the sibling
+	 */
+	BrowsableLocation sibling(String path) throws IOException;
+
+	/**
+	 * Tests whether this location is a <b>directory</b>, meaning that it can have
+	 * children. It is recommended to use this method before calling
+	 * {@link #child(String)} or {@link #children()}, to ensure those calls
+	 * succeed.
+	 * 
+	 * @return True iff the location represents a directory.
+	 */
+	boolean isDirectory();
+
+	/**
+	 * Obtains a location with the given name, for whom this location is the
+	 * parent. Note that this will only succeed if calls to {@link #isDirectory()}
+	 * on this location return <code>true</code>.
+	 *
+	 * @param name the name of the child
+	 * @return a location pointing to the child
+	 * @throws IOException if something goes wrong obtaining the child.
+	 * @throws IllegalArgumentException if this location is not a directory (i.e.,
+	 *           {@link #isDirectory()} returns false).
+	 */
+	BrowsableLocation child(String name) throws IOException;
+}

src/main/java/org/scijava/io/location/FileLocation.java

@@ -33,14 +33,21 @@
 package org.scijava.io.location;
 
 import java.io.File;
+import java.io.IOException;
 import java.net.URI;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Set;
 
 /**
  * {@link Location} backed by a {@link File} on disk.
  *
  * @author Curtis Rueden
+ * @author Gabriel Einsdorf
  */
-public class FileLocation extends AbstractLocation {
+public class FileLocation extends AbstractLocation implements
+	BrowsableLocation
+{
 
 	private final File file;
 
@@ -75,4 +82,47 @@ public String getName() {
 		return file.getName();
 	}
 
+	// -- BrowsableLocation methods --
+
+	@Override
+	public FileLocation parent() throws IOException {
+		return new FileLocation(file.getParentFile());
+	}
+
+	@Override
+	public Set<BrowsableLocation> children() throws IOException {
+		validateDirectory();
+		final File[] files = file.listFiles();
+		if (files == null) return Collections.emptySet();
+
+		final Set<BrowsableLocation> out = new HashSet<>(files.length);
+		for (final File child : files) {
+			out.add(new FileLocation(child));
+		}
+		return out;
+	}
+
+	@Override
+	public FileLocation sibling(final String path) {
+		return new FileLocation(new File(file.getParentFile(), path));
+	}
+
+	@Override
+	public FileLocation child(final String name) {
+		validateDirectory();
+		return new FileLocation(new File(file, name));
+	}
+
+	@Override
+	public boolean isDirectory() {
+		return file.isDirectory();
+	}
+
+	// -- Helper methods --
+
+	private void validateDirectory() {
+		if (isDirectory()) return;
+		throw new IllegalArgumentException(
+			"This location does not point to a directory!");
+	}
 }

src/main/java/org/scijava/io/location/Location.java

@@ -71,8 +71,20 @@ default URI getURI() {
 	 * @return The name, or an empty string if no name is available.
 	 */
 	default String getName() {
-		final URI uri = getURI();
-		return uri == null ? "" : uri.toString();
+		return defaultName();
 	}
 
+	/**
+	 * Gets the default name used when no explicit name is assigned.
+	 * <p>
+	 * Note: this is mostly intended for debugging, since most kinds of
+	 * {@code Location} will assign some non-default name. But in cases where that
+	 * does not occur, this value can be useful to detect the situation.
+	 * </p>
+	 * 
+	 * @return The default name string.
+	 */
+	default String defaultName() {
+		return "Location.defaultName";
+	}
 }