Document contract for In/OutputStream resources and fix example (#605)

3 files changed, 37 insertions, 27 deletions

diff --git a/org.jacoco.core/src/org/jacoco/core/analysis/Analyzer.java b/org.jacoco.core/src/org/jacoco/core/analysis/Analyzer.java
index ce053d01..06c7ec2b 100644
--- a/org.jacoco.core/src/org/jacoco/core/analysis/Analyzer.java
+++ b/org.jacoco.core/src/org/jacoco/core/analysis/Analyzer.java
@@ -132,7 +132,8 @@ public class Analyzer {
 	}
 
 	/**
-	 * Analyzes the class definition from a given input stream.
+	 * Analyzes the class definition from a given input stream. The provided
+	 * {@link InputStream} is not closed by this method.
 	 * 
 	 * @param input
 	 *            stream to read class definition from
@@ -154,8 +155,8 @@ public class Analyzer {
 
 	private IOException analyzerError(final String location,
 			final Exception cause) {
-		final IOException ex = new IOException(String.format(
-				"Error while analyzing %s.", location));
+		final IOException ex = new IOException(
+				String.format("Error while analyzing %s.", location));
 		ex.initCause(cause);
 		return ex;
 	}
@@ -164,7 +165,8 @@ public class Analyzer {
 	 * Analyzes all classes found in the given input stream. The input stream
 	 * may either represent a single class file, a ZIP archive, a Pack200
 	 * archive or a gzip stream that is searched recursively for class files.
-	 * All other content types are ignored.
+	 * All other content types are ignored. The provided {@link InputStream} is
+	 * not closed by this method.
 	 * 
 	 * @param input
 	 *            input data
@@ -179,7 +181,7 @@ public class Analyzer {
 		final ContentTypeDetector detector;
 		try {
 			detector = new ContentTypeDetector(input);
-		} catch (IOException e) {
+		} catch (final IOException e) {
 			throw analyzerError(location, e);
 		}
 		switch (detector.getType()) {
@@ -261,11 +263,11 @@ public class Analyzer {
 		return count;
 	}
 
-	private ZipEntry nextEntry(ZipInputStream input, String location)
-			throws IOException {
+	private ZipEntry nextEntry(final ZipInputStream input,
+			final String location) throws IOException {
 		try {
 			return input.getNextEntry();
-		} catch (IOException e) {
+		} catch (final IOException e) {
 			throw analyzerError(location, e);
 		}
 	}
@@ -275,7 +277,7 @@ public class Analyzer {
 		GZIPInputStream gzipInputStream;
 		try {
 			gzipInputStream = new GZIPInputStream(input);
-		} catch (IOException e) {
+		} catch (final IOException e) {
 			throw analyzerError(location, e);
 		}
 		return analyzeAll(gzipInputStream, location);
@@ -286,7 +288,7 @@ public class Analyzer {
 		InputStream unpackedInput;
 		try {
 			unpackedInput = Pack200Streams.unpack(input);
-		} catch (IOException e) {
+		} catch (final IOException e) {
 			throw analyzerError(location, e);
 		}
 		return analyzeAll(unpackedInput, location);
diff --git a/org.jacoco.core/src/org/jacoco/core/instr/Instrumenter.java b/org.jacoco.core/src/org/jacoco/core/instr/Instrumenter.java
index eb91f561..179861ca 100644
--- a/org.jacoco.core/src/org/jacoco/core/instr/Instrumenter.java
+++ b/org.jacoco.core/src/org/jacoco/core/instr/Instrumenter.java
@@ -119,7 +119,8 @@ public class Instrumenter {
 	}
 
 	/**
-	 * Creates a instrumented version of the given class if possible.
+	 * Creates a instrumented version of the given class if possible. The
+	 * provided {@link InputStream} is not closed by this method.
 	 * 
 	 * @param input
 	 *            stream to read class definition from
@@ -142,7 +143,9 @@ public class Instrumenter {
 	}
 
 	/**
-	 * Creates a instrumented version of the given class file.
+	 * Creates a instrumented version of the given class file. The provided
+	 * {@link InputStream} and {@link OutputStream} instances are not closed by
+	 * this method.
 	 * 
 	 * @param input
 	 *            stream to read class definition from
@@ -170,7 +173,9 @@ public class Instrumenter {
 	/**
 	 * Creates a instrumented version of the given resource depending on its
 	 * type. Class files and the content of archive files are instrumented. All
-	 * other files are copied without modification.
+	 * other files are copied without modification. The provided
+	 * {@link InputStream} and {@link OutputStream} instances are not closed by
+	 * this method.
 	 * 
 	 * @param input
 	 *            stream to contents from
@@ -183,12 +188,12 @@ public class Instrumenter {
 	 *             if reading data from the stream fails or a class can't be
 	 *             instrumented
 	 */
-	public int instrumentAll(final InputStream input,
-			final OutputStream output, final String name) throws IOException {
+	public int instrumentAll(final InputStream input, final OutputStream output,
+			final String name) throws IOException {
 		final ContentTypeDetector detector;
 		try {
 			detector = new ContentTypeDetector(input);
-		} catch (IOException e) {
+		} catch (final IOException e) {
 			throw instrumentError(name, e);
 		}
 		switch (detector.getType()) {
@@ -229,11 +234,11 @@ public class Instrumenter {
 		return count;
 	}
 
-	private ZipEntry nextEntry(ZipInputStream input, String location)
-			throws IOException {
+	private ZipEntry nextEntry(final ZipInputStream input,
+			final String location) throws IOException {
 		try {
 			return input.getNextEntry();
-		} catch (IOException e) {
+		} catch (final IOException e) {
 			throw instrumentError(location, e);
 		}
 	}
@@ -243,7 +248,7 @@ public class Instrumenter {
 		final GZIPInputStream gzipInputStream;
 		try {
 			gzipInputStream = new GZIPInputStream(input);
-		} catch (IOException e) {
+		} catch (final IOException e) {
 			throw instrumentError(name, e);
 		}
 		final GZIPOutputStream gzout = new GZIPOutputStream(output);
@@ -257,7 +262,7 @@ public class Instrumenter {
 		final InputStream unpackedInput;
 		try {
 			unpackedInput = Pack200Streams.unpack(input);
-		} catch (IOException e) {
+		} catch (final IOException e) {
 			throw instrumentError(name, e);
 		}
 		final ByteArrayOutputStream buffer = new ByteArrayOutputStream();
@@ -279,7 +284,7 @@ public class Instrumenter {
 			final String name) throws IOException {
 		try {
 			return input.read(buffer);
-		} catch (IOException e) {
+		} catch (final IOException e) {
 			throw instrumentError(name, e);
 		}
 	}
diff --git a/org.jacoco.examples/src/org/jacoco/examples/CoreTutorial.java b/org.jacoco.examples/src/org/jacoco/examples/CoreTutorial.java
index 0f42ee07..8852f908 100644
--- a/org.jacoco.examples/src/org/jacoco/examples/CoreTutorial.java
+++ b/org.jacoco.examples/src/org/jacoco/examples/CoreTutorial.java
@@ -113,8 +113,9 @@ public final class CoreTutorial {
 		// The Instrumenter creates a modified version of our test target class
 		// that contains additional probes for execution data recording:
 		final Instrumenter instr = new Instrumenter(runtime);
-		final byte[] instrumented = instr.instrument(
-				getTargetClass(targetName), targetName);
+		InputStream original = getTargetClass(targetName);
+		final byte[] instrumented = instr.instrument(original, targetName);
+		original.close();
 
 		// Now we're ready to run our instrumented class and need to startup the
 		// runtime first:
@@ -142,7 +143,9 @@ public final class CoreTutorial {
 		// information:
 		final CoverageBuilder coverageBuilder = new CoverageBuilder();
 		final Analyzer analyzer = new Analyzer(executionData, coverageBuilder);
-		analyzer.analyzeClass(getTargetClass(targetName), targetName);
+		original = getTargetClass(targetName);
+		analyzer.analyzeClass(original, targetName);
+		original.close();
 
 		// Let's dump some metrics and line coverage information:
 		for (final IClassCoverage cc : coverageBuilder.getClasses()) {
@@ -155,8 +158,8 @@ public final class CoreTutorial {
 			printCounter("complexity", cc.getComplexityCounter());
 
 			for (int i = cc.getFirstLine(); i <= cc.getLastLine(); i++) {
-				out.printf("Line %s: %s%n", Integer.valueOf(i), getColor(cc
-						.getLine(i).getStatus()));
+				out.printf("Line %s: %s%n", Integer.valueOf(i),
+						getColor(cc.getLine(i).getStatus()));
 			}
 		}
 	}