Issue ota4j-team#21: Introduce DebugInformation

Introducing a more generic way to provide additional information
for debugging upon assertion failures. The DebugInformation is
key-value based and can contain actual any information.

In addition to this extended the ValueWrapper (now renamed to
ValueDescriptor as it *describes* the value) so that it does some
effort to serialize objects applying some strategies. This way we
could also provide images as for example for UI tests.

The current state neither includes documentation, more tests and
misses the commonly used exception for all exceptions provided
inside here.

This approach also addresses issues:

* ota4j-team#20 support for exception creation strategies
* ota4j-team#4 detach AssertionError from exceptions here
* ota4j-team#9 partially, as you the debug information provided here should
  eventually merge into a standard test report.

src/main/java/org/opentest4j/AssertionFailedException.java

@@ -0,0 +1,113 @@
+/*
+ * Copyright 2015-2016 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.opentest4j;
+
+import static org.opentest4j.CommonDebugInformationKey.ACTUAL;
+import static org.opentest4j.CommonDebugInformationKey.EXPECTED;
+import static org.opentest4j.DebugInformation.builder;
+
+import org.opentest4j.value.ValueDescriptor;
+
+/**
+ * {@code AssertionFailedError} is an <em>initial draft</em> for a common base class for test-related
+ * {@link AssertionError AssertionErrors}.
+ * <p>
+ * In addition to a message and a cause this class stores the expected and actual values of an assertion using the
+ * {@link ValueDescriptor} type.
+ * <p>
+ * <strong>WARNING</strong>: this is a <em>work in progress</em> and is therefore guaranteed to undergo heavy revisions
+ * in the near future based on community feedback.
+ *
+ * @author Sam Brannen
+ * @author Marc Philipp
+ * @since 1.0
+ */
+public class AssertionFailedException extends DebuggableException {
+
+	private static final long serialVersionUID = 1L;
+
+	/**
+	 * Constructs an {@code AssertionFailedError} with no message, no cause, and no expected/actual values.
+	 */
+	public AssertionFailedException() {
+	}
+
+	/**
+	 * Constructs an {@code AssertionFailedError} with a message, no cause, and no expected/actual values.
+	 */
+	public AssertionFailedException(String message) {
+		super(message);
+	}
+
+	/**
+	 * Constructs an {@code AssertionFailedError} with a message and expected/actual values but without a cause.
+	 */
+	public AssertionFailedException(String message, Object expected, Object actual) {
+		super(builder().addValue(EXPECTED.getId(), expected).addValue(ACTUAL.getId(), actual).build(), message);
+	}
+
+	/**
+	 * Constructs an {@code AssertionFailedError} with a message and a cause but without expected/actual values.
+	 */
+	public AssertionFailedException(String message, Throwable cause) {
+		super(message, cause);
+	}
+
+	/**
+	 * Constructs an {@code AssertionFailedError} with a message, expected/actual values, and a cause.
+	 */
+	public AssertionFailedException(String message, Object expected, Object actual, Throwable cause) {
+		super(builder().addValue(EXPECTED.getId(), expected).addValue(ACTUAL.getId(), actual).build(), message, cause);
+	}
+
+	/**
+	 * Returns {@code true} if the expected value is defined, i.e. was passed to the constructor.
+	 *
+	 * @see #getExpected()
+	 */
+	public boolean isExpectedDefined() {
+		return hasDebugInformation() && getDebugInformation().hasValue(EXPECTED.getId());
+	}
+
+	/**
+	 * Returns {@code true} if the actual value is defined, i.e. was passed to the constructor.
+	 *
+	 * @see #getActual()
+	 */
+	public boolean isActualDefined() {
+		return hasDebugInformation() && getDebugInformation().hasValue(ACTUAL.getId());
+	}
+
+	/**
+	 * Returns the wrapped expected value if it is defined; otherwise {@code null}.
+	 *
+	 * @see #isExpectedDefined()
+	 */
+	public ValueDescriptor getExpected() {
+		return isExpectedDefined() ? getDebugInformation().getValue(EXPECTED.getId()) : null;
+	}
+
+	/**
+	 * Returns the wrapped actual value if it is defined; otherwise {@code null}.
+	 *
+	 * @see #isActualDefined()
+	 */
+	public ValueDescriptor getActual() {
+		return isActualDefined() ? getDebugInformation().getValue(ACTUAL.getId()) : null;
+	}
+
+}

src/main/java/org/opentest4j/CommonDebugInformationKey.java

@@ -0,0 +1,20 @@
+
+package org.opentest4j;
+
+/**
+ * @author Mark Michaelis
+ * @since 1.0
+ */
+public enum CommonDebugInformationKey {
+	EXPECTED("expected"), ACTUAL("actual"), MISMATCH_DESCRIPTION("mismatchDescription");
+
+	private final String id;
+
+	CommonDebugInformationKey(String id) {
+		this.id = id;
+	}
+
+	public String getId() {
+		return this.id;
+	}
+}

src/main/java/org/opentest4j/DebugInformation.java

@@ -0,0 +1,60 @@
+
+package org.opentest4j;
+
+import static java.util.Collections.unmodifiableMap;
+
+import java.io.Serializable;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Set;
+
+import org.opentest4j.value.ValueDescriptor;
+
+/**
+ * @author Mark Michaelis
+ * @since 1.0
+ */
+public class DebugInformation implements Serializable {
+
+	private static final long serialVersionUID = -4561854355030078114L;
+	private final Map<String, ValueDescriptor> values;
+
+	private DebugInformation(Map<String, ValueDescriptor> values) {
+		this.values = unmodifiableMap(values);
+	}
+
+	public static DebugInformationBuilder builder() {
+		return new DebugInformationBuilder();
+	}
+
+	public ValueDescriptor getValue(String id) {
+		return this.values.get(id);
+	}
+
+	public boolean hasValue(String id) {
+		return this.values.containsKey(id);
+	}
+
+	public Set<String> getValueIds() {
+		return this.values.keySet();
+	}
+
+	/**
+	 * Builder for debug information to provide upon failure.
+	 *
+	 * @author Mark Michaelis
+	 * @since 1.0
+	 */
+	public static class DebugInformationBuilder {
+		private Map<String, ValueDescriptor> values = new HashMap<String, ValueDescriptor>();
+
+		public DebugInformationBuilder addValue(String id, Object object) {
+			this.values.put(id, ValueDescriptor.create(object));
+			return this;
+		}
+
+		public DebugInformation build() {
+			return new DebugInformation(this.values);
+		}
+	}
+}

src/main/java/org/opentest4j/DebuggableException.java

@@ -0,0 +1,55 @@
+
+package org.opentest4j;
+
+/**
+ * @author Mark Michaelis
+ * @since 1.0
+ */
+public class DebuggableException extends RuntimeException {
+
+	private static final long serialVersionUID = 1405415156020390125L;
+	private final DebugInformation debugInformation;
+
+	public DebuggableException() {
+		this((DebugInformation) null);
+	}
+
+	public DebuggableException(String message) {
+		this((DebugInformation) null, message);
+	}
+
+	public DebuggableException(String message, Throwable cause) {
+		this((DebugInformation) null, message, cause);
+	}
+
+	public DebuggableException(Throwable cause) {
+		this((DebugInformation) null, cause);
+	}
+
+	public DebuggableException(DebugInformation debugInformation) {
+		this.debugInformation = debugInformation;
+	}
+
+	public DebuggableException(DebugInformation debugInformation, String message) {
+		super(message);
+		this.debugInformation = debugInformation;
+	}
+
+	public DebuggableException(DebugInformation debugInformation, String message, Throwable cause) {
+		super(message, cause);
+		this.debugInformation = debugInformation;
+	}
+
+	public DebuggableException(DebugInformation debugInformation, Throwable cause) {
+		super(cause);
+		this.debugInformation = debugInformation;
+	}
+
+	public DebugInformation getDebugInformation() {
+		return this.debugInformation;
+	}
+
+	public boolean hasDebugInformation() {
+		return this.debugInformation != null;
+	}
+}