Update to scijava 34.1.0 and use Location API

core/pom.xml

@@ -6,7 +6,6 @@
 		<groupId>io.scif</groupId>
 		<artifactId>pom-scifio-tutorials</artifactId>
 		<version>1.0.0-SNAPSHOT</version>
-		<relativePath />
 	</parent>
 
 	<groupId>io.scif</groupId>

core/src/main/java/io/scif/tutorials/core/FakeTutorialImages.java

@@ -0,0 +1,47 @@
+package io.scif.tutorials.core;
+
+import org.scijava.io.location.Location;
+import org.scijava.io.location.LocationService;
+
+import io.scif.io.location.TestImgLocation;
+import io.scif.io.location.TestImgLocation.Builder;
+
+// A collection of functions creating fake image {@link Location}s for the SCIFIO 
+// tutorials using {@link TestImgLocation.Builder}
+public class FakeTutorialImages {
+
+	public static Location hugeImage() {
+		TestImgLocation.Builder b = new Builder();
+		b.axes("X","Y");
+		b.lengths(70000, 80000);
+		Location location = b.build();
+		return location;
+	}
+
+	// Note:
+	// This is equivalent to using the LocationService to resolve the String input image from
+	// T1aIntroToSCIFIO
+	// final String sampleImage = 
+	//     "8bit-unsigned&pixelType=uint8&lengths=50,50,3,5,7&axes=X,Y,Z,Channel,Time.fake";
+	// Location location = scifio.location().resolve(sampleImage);
+	public static Location sampleImage() {
+		TestImgLocation.Builder b = new Builder();
+		b.pixelType("uint8"); // set the pixel type
+		b.axes("X", "Y", "Z", "Channel", "Time"); // set new axis names
+		b.lengths(50, 50, 3, 5, 7); // set new axis lengths
+		Location location = b.build(); // build the final location
+		return location;
+	}
+
+	public static Location sampleIndexedImage() {
+		TestImgLocation.Builder b = new Builder();
+		b.pixelType("uint8"); // set the pixel type
+		b.indexed(true);
+		b.planarDims(3);
+		b.axes("X", "Y", "Channel"); // set new axis names
+		b.lengths(50, 50, 3); // set new axis lengths
+		Location location = b.build(); // build the final location
+		return location;
+	}
+
+}

core/src/main/java/io/scif/tutorials/core/T1aIntroToSCIFIO.java

@@ -23,6 +23,10 @@
 import io.scif.SCIFIO;
 
 import java.io.IOException;
+import java.net.URISyntaxException;
+
+import org.scijava.io.location.Location;
+import org.scijava.io.location.LocationService;
 
 /**
  * An introduction to the SCIFIO API. Demonstrates basic plane reading.
@@ -32,7 +36,7 @@
 public class T1aIntroToSCIFIO {
 
 	public static void main(final String... agrs) throws FormatException,
-		IOException
+		IOException, URISyntaxException
 	{
 		// The most convenient way to program against the SCIFIO API is by using
 		// an io.scif.SCIFIO instance. This is basically a "SCIFIO lens" on an
@@ -48,12 +52,17 @@ public static void main(final String... agrs) throws FormatException,
 		// exist on disk - they are defined purely by their file name -  so they're
 		// good for testing.
 		final String sampleImage =
-			"8bit-signed&pixelType=int8&lengths=50,50,3,5,7&axes=X,Y,Z,Channel,Time.fake";
-
+			"8bit-unsigned&pixelType=uint8&lengths=50,50,3,5,7&axes=X,Y,Z,Channel,Time.fake";
+
+		// We use the {@link LocationService} to resolve our input image to a {@link Location}. 
+		// a Location identifies where the data resides, without necessarily specifying 
+		// how to access that data.
+		Location location = scifio.location().resolve(sampleImage);
+
 		// This method checks the Context used by our SCIFIO instance for all its
 		// known format plugins, and returns an io.scif.Reader capable of opening
 		// the specified image's planes.
-		final Reader reader = scifio.initializer().initializeReader(sampleImage);
+		final Reader reader = scifio.initializer().initializeReader(location);
 
 		// ------------------------------------------------------------------------
 		// COMPARISON WITH BIO-FORMATS 4.X

core/src/main/java/io/scif/tutorials/core/T1bReadingTilesBad.java

@@ -23,6 +23,8 @@
 
 import java.io.IOException;
 
+import org.scijava.io.location.Location;
+
 /**
  * WARNING: this code intentionally fails. For functional code, see
  * {@link T1cReadingTilesGood}.
@@ -43,11 +45,15 @@ public static void main(final String... args) throws FormatException,
 		final SCIFIO scifio = new SCIFIO();
 
 		// This time we're going to set up an imageID with planes that won't fit
-		// in a byte array.
-		final String hugeImage = "hugePlane&lengths=70000,80000.fake";
+		// in a byte array. 
+		// For the rest of these tutorials, we will use the {@link TestImgLocation.Builder}
+		// to build fake images for us and return their Location. This is in contrast to creating 
+		// a fake image as a String and then resolving its Location with LocationService like
+		// we did in T1aIntroToSCIFIO.
+		Location hugeImageLocation = FakeTutorialImages.hugeImage();
 
 		// We initialize a reader as we did before
-		final Reader reader = scifio.initializer().initializeReader(hugeImage);
+		final Reader reader = scifio.initializer().initializeReader(hugeImageLocation);
 
 		// Now we'll try the naive thing, and just open all the planes in this
 		// dataset.

core/src/main/java/io/scif/tutorials/core/T1cReadingTilesGood.java

@@ -27,6 +27,8 @@
 import java.io.IOException;
 import java.util.Arrays;
 
+import org.scijava.io.location.Location;
+
 import net.imagej.axis.Axes;
 import net.imglib2.FinalInterval;
 import net.imglib2.Interval;
@@ -47,11 +49,11 @@ public static void main(final String... args) throws FormatException,
 		final SCIFIO scifio = new SCIFIO();
 
 		// This time we're going to set up an image with planes that won't fit
-		// in a 2GB byte array.
-		final String hugeImage = "hugePlane&lengths=70000,80000.fake";
-
+		// in a 2GB byte array and get its Location again.
+		Location hugeImageLocation = FakeTutorialImages.hugeImage();
+		
 		// We initialize a reader as we did before
-		final Reader reader = scifio.initializer().initializeReader(hugeImage);
+		final Reader reader = scifio.initializer().initializeReader(hugeImageLocation);
 
 		// In T1b we saw that the naive use of the API to open planes doesn't
 		// work when the individual planes are too large.

core/src/main/java/io/scif/tutorials/core/T1dSavingImagePlanes.java

@@ -21,10 +21,14 @@
 import io.scif.Reader;
 import io.scif.SCIFIO;
 import io.scif.Writer;
-import io.scif.io.Location;
+import io.scif.io.location.TestImgLocation;
 
 import java.io.File;
 import java.io.IOException;
+import java.net.URISyntaxException;
+
+import org.scijava.io.location.Location;
+import org.scijava.io.location.LocationService;
 
 /**
  * Tutorial demonstrating use of the Writer component.
@@ -34,31 +38,35 @@
 public class T1dSavingImagePlanes {
 
 	public static void main(final String... args) throws FormatException,
-		IOException
+		IOException, URISyntaxException
 	{
 		// In this tutorial, we're going to make our .fake sample image
-		// "real". If you look at the FakeFormat source code, you'll notice that
+		// "real". If you look at the TestImgFormat source code, you'll notice that
 		// it doesn't have a functional Writer, so we'll have to translate
 		// to a different Format that can write our fake planes to disk.
 
 		final SCIFIO scifio = new SCIFIO();
-		final String sampleImage =
-			"8bit-signed&pixelType=int8&lengths=50,50,3,5,7&axes=X,Y,Z,Channel,Time.fake";
+
+		// Create a fake image and get its Location.
+		Location sampleImageLocation = FakeTutorialImages.sampleImage();
 
 		// We'll need a path to write to. By making it a ".png" we are locking in
 		// the final format of the file on disk.
 		final String outPath = "SCIFIOTutorial.png";
+
+		// We can resolve this Location in the same way as T1aIntroToSCIFIO
+		Location outLoction = scifio.location().resolve(outPath); 
 
 		// Clear the file if it already exists.
-		final Location l = new Location(scifio.getContext(), outPath);
-		if (l.exists()) l.delete();
+		File f = new File(outPath);
+		if (f.exists()) f.delete();
 
 		// We'll need a reader for the input image
-		final Reader reader = scifio.initializer().initializeReader(sampleImage);
+		final Reader reader = scifio.initializer().initializeReader(sampleImageLocation);
 
 		// .. and a writer for the output path
 		final Writer writer =
-			scifio.initializer().initializeWriter(sampleImage, outPath);
+			scifio.initializer().initializeWriter(sampleImageLocation, outLoction);
 
 		// Note that these initialize methods are used for convenience.
 		// Initializing a reader and a writer requires that you set the source

core/src/main/java/io/scif/tutorials/core/T2aUntypedComponents.java

@@ -26,6 +26,8 @@
 
 import java.io.IOException;
 
+import org.scijava.io.location.Location;
+
 /**
  * Demonstrates how individual components can be used together instead of the
  * convenience methods in the T1 tutorials. This is for more advanced SCIFIO
@@ -44,21 +46,22 @@ public static void main(final String... args) throws FormatException,
 
 		// As always, we create a context and sample image path first.
 		final SCIFIO scifio = new SCIFIO();
-		final String sampleImage =
-			"8bit-signed&pixelType=int8&lengths=50,50,3,5,7&axes=X,Y,Z,Channel,Time.fake";
+
+		// Create a fake image and get its Location.
+		Location sampleImageLocation = FakeTutorialImages.sampleImage();
 
 		// This time we'll get a handle on the Format itself, which will allow us
 		// to create the additional components. scifio.format() contains several
 		// useful methods for dealing with Formats directly.
 		// NB: This implicitly invokes an io.scif.Checker component to determine
 		// format compatibility. These can also be used individually, e.g. if
 		// given a list of Formats to test.
-		final Format format = scifio.format().getFormat(sampleImage);
+		final Format format = scifio.format().getFormat(sampleImageLocation);
 
 		// Typically the first thing we want to do, after confirming we have a
 		// Format that can support an image, is parse the Metadata of that image.
 		final Parser parser = format.createParser();
-		final Metadata meta = parser.parse(sampleImage);
+		final Metadata meta = parser.parse(sampleImageLocation);
 		System.out.println("Metadata = " + meta);
 
 		// Metadata is used by other components, such as Readers, Writers, and

core/src/main/java/io/scif/tutorials/core/T2bTypedComponents.java

@@ -20,12 +20,15 @@
 import io.scif.ByteArrayPlane;
 import io.scif.FormatException;
 import io.scif.SCIFIO;
-import io.scif.formats.FakeFormat;
-import io.scif.formats.FakeFormat.Parser;
-import io.scif.formats.FakeFormat.Reader;
+
+import io.scif.formats.TestImgFormat;
+import io.scif.formats.TestImgFormat.Parser;
+import io.scif.formats.TestImgFormat.Reader;
 
 import java.io.IOException;
 
+import org.scijava.io.location.Location;
+
 /**
  * In {@link T2aUntypedComponents} we looked at using the general,
  * interface-level SCIFIO components. Now we'll look at how to get access
@@ -42,21 +45,21 @@ public static void main(final String... args) throws FormatException,
 		// if we know exactly what kind of image we're working with?
 
 		final SCIFIO scifio = new SCIFIO();
-		final String sampleImage =
-			"8bit-unsigned&pixelType=uint8&indexed=true&planarDims=3&lengths=50,50,3&axes=X,Y,Channel.fake";
+
+		Location sampleImageLocation = FakeTutorialImages.sampleIndexedImage();
 
 		// This time, since we know we have a .fake image, we'll get a handle to the
 		// Fake format.
-		final FakeFormat fakeFormat =
-			scifio.format().getFormatFromClass(FakeFormat.class);
+		final TestImgFormat fakeFormat =
+			scifio.format().getFormatFromClass(TestImgFormat.class);
 
 		// Two important points here:
 		// 1 - getformatFromClass is overloaded. You can use any component's class
 		// and get back the corresponding Format.
-		// 2 - we didn't invoke the FakeFormat's constructor.
-		// new FakeFormat() would have given us a Format instance with no context.
-		// new FakeFormat(scifio) would have given us a Format with the correct
-		// context, but wouldn't update the context's FakeFormat singleton. So it
+		// 2 - we didn't invoke the TestImgFormat's constructor.
+		// new TestImgFormat() would have given us a Format instance with no context.
+		// new TestImgFormat(scifio) would have given us a Format with the correct
+		// context, but wouldn't update the context's TestImgFormat singleton. So it
 		// would basically be an orphan Format instance.
 		// Formats have no state, so as long as you want a Format that was
 		// discovered as a plugin, you should access it via the desired context. We
@@ -65,16 +68,16 @@ public static void main(final String... args) throws FormatException,
 		// Formats provide access to all other components, and with a typed Format
 		// you can create typed components:
 
-		final FakeFormat.Reader reader = (Reader) fakeFormat.createReader();
-		final FakeFormat.Parser parser = (Parser) fakeFormat.createParser();
+		final TestImgFormat.Reader reader = (Reader) fakeFormat.createReader();
+		final TestImgFormat.Parser parser = (Parser) fakeFormat.createParser();
 
 		// Now that we have typed components, we can guarantee the return type
 		// for many methods, and access type-specific API:
 
-		final FakeFormat.Metadata meta = parser.parse(sampleImage);
+		final TestImgFormat.Metadata meta = parser.parse(sampleImageLocation);
 
 		// getColorTable isn't a part of the Metadata API, but since
-		// FakeFormat.Metadata implements HasColorTable, we have access to this
+		// TestImgFormat.Metadata implements HasColorTable, we have access to this
 		// method.
 		System.out.println("Color table: " + meta.getColorTable(0, 0));
 

core/src/main/java/io/scif/tutorials/core/T3aCustomFormats.java

@@ -33,17 +33,19 @@
 import io.scif.Plane;
 import io.scif.SCIFIO;
 import io.scif.config.SCIFIOConfig;
-import io.scif.io.RandomAccessInputStream;
-import io.scif.io.RandomAccessOutputStream;
 import io.scif.services.FormatService;
 
 import java.io.IOException;
+import java.net.URISyntaxException;
 import java.util.Arrays;
 import java.util.List;
 
 import net.imagej.axis.Axes;
 import net.imglib2.Interval;
 
+import org.scijava.io.handle.DataHandle;
+import org.scijava.io.location.Location;
+import org.scijava.io.location.LocationService;
 import org.scijava.plugin.Plugin;
 
 /**
@@ -181,7 +183,7 @@ public static class Parser extends AbstractParser<Metadata> {
 
 			// In this method we populate the given Metadata object
 			@Override
-			public void typedParse(final RandomAccessInputStream stream,
+			public void typedParse(final DataHandle<Location> handle,
 				final Metadata meta, final SCIFIOConfig config) throws IOException,
 				FormatException
 			{
@@ -337,9 +339,9 @@ public void writePlane(int imageIndex, long planeIndex, Plane plane,
 				final Metadata meta = getMetadata();
 				System.out.println("Metadata = " + meta);
 
-				// This stream is the destination image to write to.
-				final RandomAccessOutputStream stream = getStream();
-				System.out.println("Stream = " + stream);
+				// This data handle is the destination image to write to.
+				final DataHandle<Location> dataHandle = getHandle();
+				System.out.println("DataHandle = " + dataHandle);
 
 				// The given Plane object is the source plane to write
 				final byte[] bytes = plane.getBytes();
@@ -450,7 +452,7 @@ protected void translateImageMetadata(final List<ImageMetadata> source,
 	// *** END OF SAMPLE FORMAT ***
 
 	// This method is provided simply to confirm the format is discovered
-	public static void main(final String... args) throws FormatException {
+	public static void main(final String... args) throws FormatException, URISyntaxException {
 		// ------------------------------------------------------------------------
 		// COMPARISON WITH BIO-FORMATS 4.X
 		// In Bio-Formats 4.X, adding support for a new format required modifying
@@ -470,9 +472,12 @@ public static void main(final String... args) throws FormatException {
 		// ... and a sample image path:
 		final String sampleImage = "notAnImage.scifiosmpl";
 
+		// Resolving the Location of this image.
+		Location location = scifio.location().resolve(sampleImage);
+
 		// As SampleFormat below was annotated as a @Plugin it should be available
 		// to our context:
-		final Format format = scifio.format().getFormat(sampleImage);
+		final Format format = scifio.format().getFormat(location);
 
 		// Verify that we found the format plugin
 		System.out.println("SampleFormat found via FormatService: " +