GitHub #319: Improved error message for incompatible exec data files.

In case of incompatible execution data formats read from another JaCoCo
version ExecutionDataReader.read() now throws a
IncompatibleExecDataVersionException with a better error message.

org.jacoco.core.test/src/org/jacoco/core/data/ExecutionDataReaderWriterTest.java

@@ -135,8 +135,8 @@ public void testInvalidMagicNumber() throws IOException {
 		createReader().read();
 	}
 
-	@Test(expected = IOException.class)
-	public void testInvalidHeaderVersion() throws IOException {
+	@Test(expected = IncompatibleExecDataVersionException.class)
+	public void testInvalidVersion() throws IOException {
 		buffer = new ByteArrayOutputStream();
 		buffer.write(ExecutionDataWriter.BLOCK_HEADER);
 		buffer.write(0xC0);

org.jacoco.core.test/src/org/jacoco/core/data/IncompatibleExecDataVersionExceptionTest.java

@@ -0,0 +1,49 @@
+/*******************************************************************************
+ * Copyright (c) 2009, 2015 Mountainminds GmbH & Co. KG and Contributors
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ *    Marc R. Hoffmann - initial API and implementation
+ *    
+ *******************************************************************************/
+package org.jacoco.core.data;
+
+import static org.junit.Assert.assertEquals;
+
+import org.junit.Before;
+import org.junit.Test;
+
+/**
+ * Unit tests for {@link IncompatibleExecDataVersionExceptionTest}.
+ */
+public class IncompatibleExecDataVersionExceptionTest {
+
+	private IncompatibleExecDataVersionException exception;
+
+	@Before
+	public void setup() {
+		exception = new IncompatibleExecDataVersionException(0x1234);
+	}
+
+	@Test
+	public void testGetMessage() {
+		String expected = "Cannot read execution data version 0x1234. "
+				+ "This version of JaCoCo uses execution data version 0x"
+				+ Integer.toHexString(ExecutionDataWriter.FORMAT_VERSION) + ".";
+		assertEquals(expected, exception.getMessage());
+	}
+
+	@Test
+	public void testGetActualVersion() {
+		assertEquals(0x1234, exception.getActualVersion());
+	}
+
+	@Test
+	public void testGetExpectedVersion() {
+		assertEquals(ExecutionDataWriter.FORMAT_VERSION,
+				exception.getExpectedVersion());
+	}
+}

org.jacoco.core/src/org/jacoco/core/data/ExecutionDataReader.java

@@ -74,8 +74,11 @@ public void setExecutionDataVisitor(final IExecutionDataVisitor visitor) {
 	 *         stream has been reached.
 	 * @throws IOException
 	 *             might be thrown by the underlying input stream
+	 * @throws IncompatibleExecDataVersionException
+	 *             incompatible data version from different JaCoCo release
 	 */
-	public boolean read() throws IOException {
+	public boolean read() throws IOException,
+			IncompatibleExecDataVersionException {
 		try {
 			byte type;
 			do {
@@ -124,8 +127,7 @@ private void readHeader() throws IOException {
 		}
 		final char version = in.readChar();
 		if (version != ExecutionDataWriter.FORMAT_VERSION) {
-			throw new IOException(format("Incompatible version %x.",
-					Integer.valueOf(version)));
+			throw new IncompatibleExecDataVersionException(version);
 		}
 	}
 

org.jacoco.core/src/org/jacoco/core/data/IncompatibleExecDataVersionException.java

@@ -0,0 +1,58 @@
+/*******************************************************************************
+ * Copyright (c) 2009, 2015 Mountainminds GmbH & Co. KG and Contributors
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ *    Marc R. Hoffmann, somechris - initial API and implementation
+ *    
+ *******************************************************************************/
+package org.jacoco.core.data;
+
+import java.io.IOException;
+
+/**
+ * Signals that execution data in an incompatible version was tried to read.
+ */
+public class IncompatibleExecDataVersionException extends IOException {
+
+	private static final long serialVersionUID = 1L;
+
+	private final int actualVersion;
+
+	/**
+	 * Creates a new exception to flag version mismatches in execution data.
+	 * 
+	 * @param actualVersion
+	 *            version found in the exec data
+	 */
+	public IncompatibleExecDataVersionException(final int actualVersion) {
+		super(String.format("Cannot read execution data version 0x%x. "
+				+ "This version of JaCoCo uses execution data version 0x%x.",
+				Integer.valueOf(actualVersion),
+				Integer.valueOf(ExecutionDataWriter.FORMAT_VERSION)));
+		this.actualVersion = actualVersion;
+	}
+
+	/**
+	 * Gets the version expected in the execution data which can be read by this
+	 * version of JaCoCo.
+	 * 
+	 * @return expected version in execution data
+	 */
+	public int getExpectedVersion() {
+		return ExecutionDataWriter.FORMAT_VERSION;
+	}
+
+	/**
+	 * Gets the actual version found in the execution data.
+	 * 
+	 * @return actual version in execution data
+	 */
+	public int getActualVersion() {
+		return actualVersion;
+	}
+
+}

org.jacoco.doc/docroot/doc/changes.html

@@ -20,12 +20,27 @@ <h1>Change History</h1>
 
 <h2>Snapshot Build @qualified.bundle.version@ (@build.date@)</h2>
 
+<h3>New Features</h3>
+<ul>
+  <li>Improved error message in case of incompatible execution data files.
+      (GitHub <a href="https://github.com/jacoco/jacoco/issues/319">#319</a>).</li>
+</ul>
+
+
 <h3>Fixed Bugs</h3>
 <ul>
   <li>Fix <code>MBeanClient</code> example
       (GitHub <a href="https://github.com/jacoco/jacoco/issues/333">#333</a>).</li>
 </ul>
 
+<h3>API Changes</h3>
+<ul>
+  <li>In case of incompatible execution data formats read from another JaCoCo
+  version <code>ExecutionDataReader.read()</code> now throws a 
+  <code>IncompatibleExecDataVersionException</code>.</li>
+</ul>
+
+
 <h2>Release 0.7.5 (2015/05/24)</h2>
 
 <h3>New Features</h3>