Add I/O service

This general-purpose, non-image-specific service migrated from ImageJ:
https://github.com/imagej/imagej/tree/imagej-2.0.0-beta-7.8/core/core/src/main/java/imagej/io

Author: ctrueden

src/main/java/org/scijava/io/AbstractIOPlugin.java

@@ -0,0 +1,86 @@
+/*
+ * #%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.io;
+
+import java.io.IOException;
+
+import org.scijava.plugin.AbstractHandlerPlugin;
+
+/**
+ * Abstract base class for {@link IOPlugin}s.
+ * 
+ * @author Curtis Rueden
+ */
+public abstract class AbstractIOPlugin<D> extends AbstractHandlerPlugin<String>
+	implements IOPlugin<D>
+{
+
+	// -- IOPlugin methods --
+
+	@Override
+	public boolean supportsOpen(final String source) {
+		return false;
+	}
+
+	@Override
+	public boolean supportsSave(final String destination) {
+		return false;
+	}
+
+	@Override
+	public boolean supportsSave(final Object data, final String destination) {
+		return supportsSave(destination) && getDataType().isInstance(data);
+	}
+
+	@Override
+	public D open(final String source) throws IOException {
+		throw new UnsupportedOperationException();
+	}
+
+	@Override
+	public void save(final D data, final String destination) throws IOException {
+		throw new UnsupportedOperationException();
+	}
+
+	// -- Typed methods --
+
+	@Override
+	public boolean supports(final String descriptor) {
+		return supportsOpen(descriptor) || supportsSave(descriptor);
+	}
+
+	@Override
+	public Class<String> getType() {
+		return String.class;
+	}
+
+}

src/main/java/org/scijava/io/DefaultIOService.java

@@ -0,0 +1,106 @@
+/*
+ * #%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.io;
+
+import java.io.IOException;
+
+import org.scijava.event.EventService;
+import org.scijava.log.LogService;
+import org.scijava.plugin.AbstractHandlerService;
+import org.scijava.plugin.Parameter;
+import org.scijava.plugin.Plugin;
+import org.scijava.service.Service;
+
+/**
+ * Default implementation of {@link IOService}.
+ * 
+ * @author Curtis Rueden
+ */
+@Plugin(type = Service.class)
+public final class DefaultIOService
+	extends AbstractHandlerService<String, IOPlugin<?>> implements IOService
+{
+
+	@Parameter
+	private LogService log;
+
+	@Parameter
+	private EventService eventService;
+
+	// -- IOService methods --
+
+	@Override
+	public IOPlugin<?> getOpener(final String source) {
+		for (final IOPlugin<?> handler : getInstances()) {
+			if (handler.supportsOpen(source)) return handler;
+		}
+		return null;
+	}
+
+	@Override
+	public <D> IOPlugin<D> getSaver(final D data, final String destination) {
+		for (final IOPlugin<?> handler : getInstances()) {
+			if (handler.supportsSave(data, destination)) {
+				@SuppressWarnings("unchecked")
+				final IOPlugin<D> typedHandler = (IOPlugin<D>) handler;
+				return typedHandler;
+			}
+		}
+		return null;
+	}
+
+	@Override
+	public Object open(final String source) throws IOException {
+		return getOpener(source).open(source);
+	}
+
+	@Override
+	public void save(final Object data, final String destination)
+		throws IOException
+	{
+		getSaver(data, destination).save(data, destination);
+	}
+
+	// -- HandlerService methods --
+
+	@Override
+	@SuppressWarnings({ "rawtypes", "unchecked" })
+	public Class<IOPlugin<?>> getPluginType() {
+		return (Class) IOPlugin.class;
+	}
+
+	@Override
+	public Class<String> getType() {
+		return String.class;
+	}
+
+}

src/main/java/org/scijava/io/IOPlugin.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.io;
+
+import java.io.IOException;
+
+import org.scijava.plugin.HandlerPlugin;
+import org.scijava.plugin.Plugin;
+
+/**
+ * A plugin which extends an application's I/O capabilities.
+ * <p>
+ * I/O plugins discoverable at runtime must implement this interface and be
+ * annotated with @{@link Plugin} with attribute {@link Plugin#type()} =
+ * {@link IOPlugin}.class. While it possible to create an I/O plugin merely by
+ * implementing this interface, it is encouraged to instead extend
+ * {@link AbstractIOPlugin}, for convenience.
+ * </p>
+ * 
+ * @author Curtis Rueden
+ * @see Plugin
+ * @see IOService
+ */
+public interface IOPlugin<D> extends HandlerPlugin<String> {
+
+	/** The type of data opened and/or saved by the plugin. */
+	Class<D> getDataType();
+
+	/** Checks whether the I/O plugin can open data from the given source. */
+	boolean supportsOpen(String source);
+
+	/** Checks whether the I/O plugin can save data to the given destination. */
+	boolean supportsSave(String destination);
+
+	/**
+	 * Checks whether the I/O plugin can save the given data to the specified
+	 * destination.
+	 */
+	boolean supportsSave(Object data, String destination);
+
+	/** Opens data from the given source. */
+	D open(String source) throws IOException;
+
+	/** Saves the given data to the specified destination. */
+	void save(D data, String destination) throws IOException;
+
+}

src/main/java/org/scijava/io/IOService.java

@@ -0,0 +1,92 @@
+/*
+ * #%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.io;
+
+import java.io.IOException;
+
+import org.scijava.plugin.HandlerService;
+import org.scijava.service.SciJavaService;
+
+/**
+ * Interface for data I/O operations: opening and saving data.
+ * 
+ * @author Curtis Rueden
+ */
+public interface IOService extends HandlerService<String, IOPlugin<?>>,
+	SciJavaService
+{
+
+	/**
+	 * Gets the most appropriate {@link IOPlugin} for opening data from the given
+	 * source.
+	 */
+	IOPlugin<?> getOpener(String source);
+
+	/**
+	 * Gets the most appropriate {@link IOPlugin} for saving data to the given
+	 * destination.
+	 */
+	<D> IOPlugin<D> getSaver(D data, String destination);
+
+	/**
+	 * Loads data from the given source. For extensibility, the nature of the
+	 * source is left intentionally general, but two common examples include file
+	 * paths and URLs.
+	 * <p>
+	 * The opener to use is automatically determined based on available
+	 * {@link IOPlugin}s; see {@link #getOpener(String)}.
+	 * </p>
+	 * 
+	 * @param source The source (e.g., file path) from which to data should be
+	 *          loaded.
+	 * @return An object representing the loaded data, or null if the source is
+	 *         not supported.
+	 * @throws IOException if something goes wrong loading the data.
+	 */
+	Object open(String source) throws IOException;
+
+	/**
+	 * Saves data to the given destination. The nature of the destination is left
+	 * intentionally general, but the most common example is a file path.
+	 * <p>
+	 * The saver to use is automatically determined based on available
+	 * {@link IOPlugin}s; see {@link #getSaver(Object, String)}.
+	 * </p>
+	 * 
+	 * @param data The data to be saved to the destination.
+	 * @param destination The destination (e.g., file path) to which data should
+	 *          be saved.
+	 * @throws IOException if something goes wrong saving the data.
+	 */
+	void save(Object data, String destination) throws IOException;
+
+}