Implement 'EqualityTransformingSet'

Author: nicolaiparlog

src/main/java/org/codefx/libfx/collection/transform/EqualityTransformingSet.java

@@ -0,0 +1,97 @@
+package org.codefx.libfx.collection.transform;
+
+import java.util.HashSet;
+import java.util.Set;
+import java.util.function.BiPredicate;
+import java.util.function.ToIntFunction;
+
+/**
+ * An equality transforming set allows to define the implementations of {@link Object#equals(Object) equals} and
+ * {@link Object#hashCode() hashCode} which are used by the set.
+ * <p>
+ * It does so by storing the entries in an inner set and providing a transforming view on them. See the
+ * {@link org.codefx.libfx.collection.transform package} documentation for general comments on that. Note that instances
+ * of {@code EqualityTransformingSet}s are created with a {@link EqualityTransformingBuilder builder}.
+ * <p>
+ * This implementation mitigates the type safety problems by optionally using a token of the outer type to check
+ * instances against them. This solves some of the critical situations but not all of them. In those other cases
+ * {@link ClassCastException}s might still occur.
+ * <p>
+ * By default the inner set will be a {@link HashSet} but another map can be provided to the builder. Such instances
+ * must be empty and not be referenced anywhere else. The implementations of {@code equals} and {@code hashCode} are
+ * provided as functions to the builder - see there for details.
+ * <p>
+ * The transformations used by this set preserve object identity of outer values. This means if values are added to this
+ * set, an iteration over it will return the same instances.
+ *
+ * @param <E>
+ *            the type of elements in this set
+ */
+public class EqualityTransformingSet<E> extends AbstractTransformingSet<EqHash<E>, E> {
+
+	// #begin FIELDS
+
+	private final Set<EqHash<E>> innerSet;
+
+	private final Class<? super E> outerTypeToken;
+
+	/**
+	 * Compares two outer elements for equality.
+	 */
+	private final BiPredicate<? super E, ? super E> equals;
+
+	/**
+	 * Computes a hashCode for an outer element.
+	 */
+	private final ToIntFunction<? super E> hash;
+
+	// #end FIELDS
+
+	// #begin CONSTRUCTION
+
+	EqualityTransformingSet(Set<?> innerSet, Class<? super E> outerTypeToken,
+			BiPredicate<? super E, ? super E> equals, ToIntFunction<? super E> hash) {
+		this.innerSet = castInnerSet(innerSet);
+		this.outerTypeToken = outerTypeToken;
+		this.equals = equals;
+		this.hash = hash;
+	}
+
+	private static <E> Set<EqHash<E>> castInnerSet(Set<?> untypedInnerSet) {
+		@SuppressWarnings("unchecked")
+		// This class' contract states that the 'innerSet' must be empty and that no other
+		// references to it must exist. This implies that only this class can ever access or mutate it.
+		// Thanks to erasure its generic element type can hence be cast to any other type.
+		Set<EqHash<E>> innerMap = (Set<EqHash<E>>) untypedInnerSet;
+		return innerMap;
+	}
+
+	// #end CONSTRUCTION
+
+	@Override
+	protected Set<EqHash<E>> getInnerSet() {
+		return innerSet;
+	}
+
+	@Override
+	protected boolean isInnerElement(Object object) {
+		// this excludes null objects from being inner element which is correct because even null will be wrapped in EqHash
+		return object instanceof EqHash;
+	}
+
+	@Override
+	protected E transformToOuter(EqHash<E> innerElement) throws ClassCastException {
+		return innerElement.getElement();
+	}
+
+	@Override
+	protected boolean isOuterElement(Object object) {
+		return object == null || outerTypeToken.isInstance(object);
+	}
+
+	@Override
+	protected EqHash<E> transformToInner(E outerElement) throws ClassCastException {
+		return new EqHash<E>(outerElement, equals, hash);
+	}
+
+}

src/test/java/org/codefx/libfx/collection/transform/EqualityTransformingSetTest.java

@@ -0,0 +1,162 @@
+package org.codefx.libfx.collection.transform;
+
+import static org.junit.Assert.assertTrue;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.Set;
+import java.util.function.BiPredicate;
+import java.util.function.ToIntFunction;
+
+import junit.framework.JUnit4TestAdapter;
+import junit.framework.Test;
+import junit.framework.TestSuite;
+
+import org.junit.Before;
+
+import com.google.common.collect.testing.SampleElements;
+import com.google.common.collect.testing.SetTestSuiteBuilder;
+import com.google.common.collect.testing.TestSetGenerator;
+import com.google.common.collect.testing.features.CollectionFeature;
+import com.google.common.collect.testing.features.CollectionSize;
+import com.google.common.collect.testing.features.Feature;
+
+/**
+ * Tests {@link EqualityTransformingSet}.
+ */
+public class EqualityTransformingSetTest {
+
+	/**
+	 * JUnit-3-style method to create the tests run for this class.
+	 *
+	 * @return the tests to run
+	 */
+	public static Test suite() {
+		TestSuite suite = new TestSuite("org.codefx.libfx.collection.transform.TransformingSet");
+		suite.addTest(originalEquality());
+		suite.addTest(lengthBasedEquality());
+		return suite;
+	}
+
+	private static Feature<?>[] features() {
+		return new Feature<?>[] {
+				// since 'EqualityTransformingSet' passes all calls along,
+				// the features are determined by the backing data structure (which is a 'HashSet')
+				CollectionSize.ANY,
+				CollectionFeature.ALLOWS_NULL_VALUES,
+				CollectionFeature.FAILS_FAST_ON_CONCURRENT_MODIFICATION,
+				CollectionFeature.SUPPORTS_ADD,
+				CollectionFeature.SUPPORTS_ITERATOR_REMOVE,
+				CollectionFeature.SUPPORTS_REMOVE,
+		};
+	}
+
+	/**
+	 * Creates a test which uses hashCode and equals of the original keys.
+	 *
+	 * @return the test case
+	 */
+	private static Test originalEquality() {
+		return SetTestSuiteBuilder
+				.using(new TransformingSetGenerator(String::equals, String::hashCode))
+				.named("original equality and hashCode")
+				.withFeatures(features())
+				.createTestSuite();
+	}
+
+	/**
+	 * Creates a test which uses hashCode and equals based on the string's lengths.
+	 *
+	 * @return the test case
+	 */
+	private static Test lengthBasedEquality() {
+		BiPredicate<String, String> equals = (s1, s2) -> s1.length() == s2.length();
+		ToIntFunction<String> hash = s -> s.length();
+
+		Test generalTests = SetTestSuiteBuilder
+				.using(new TransformingSetGenerator(equals, hash))
+				.named("length-based equality and hashCode - general tests")
+				.withFeatures(features())
+				.createTestSuite();
+		TestSuite specificTests = new TestSuite("length-based equality and hashCode - specific tests");
+		specificTests.addTest(new JUnit4TestAdapter(LengthBasedEqualityAndHashCodeTests.class));
+
+		TestSuite tests = new TestSuite("length-based equality and hashCode");
+		tests.addTest(generalTests);
+		tests.addTest(specificTests);
+		return tests;
+	}
+
+	/**
+	 * Tests {@link EqualityTransformingSet} with a specific set of tests geared towards its special functionality, i.e.
+	 * transforming equals and hashCode.
+	 */
+	public static class LengthBasedEqualityAndHashCodeTests {
+
+		private Set<String> testedSet;
+
+		private final BiPredicate<String, String> equals = (s1, s2) -> s1.length() == s2.length();
+
+		private final ToIntFunction<String> hash = s -> s.length();
+
+		@Before
+		@SuppressWarnings("javadoc")
+		public void createSet() {
+			testedSet = EqualityTransformingBuilder
+					.forKeyType(String.class)
+					.withEquals(equals)
+					.withHash(hash)
+					.buildSet();
+		}
+
+		@org.junit.Test
+		@SuppressWarnings("javadoc")
+		public void add_containsWithSameLengthElement_true() {
+			testedSet.add("aaa");
+
+			assertTrue(testedSet.contains("bbb"));
+		}
+
+	}
+
+	private static class TransformingSetGenerator implements TestSetGenerator<String> {
+
+		private final BiPredicate<String, String> equals;
+		private final ToIntFunction<String> hash;
+
+		public TransformingSetGenerator(BiPredicate<String, String> equals, ToIntFunction<String> hash) {
+			this.equals = equals;
+			this.hash = hash;
+		}
+
+		@Override
+		public Set<String> create(Object... elements) {
+			Set<String> transformingSet = EqualityTransformingBuilder
+					.forKeyType(String.class)
+					.withEquals(equals)
+					.withHash(hash)
+					.buildSet();
+			Arrays.stream(elements)
+					.map(String.class::cast)
+					.forEach(transformingSet::add);
+			return transformingSet;
+		}
+
+		@Override
+		public SampleElements<String> samples() {
+			return new SampleElements<String>("A", "AA", "AAA", "AAAA", "AAAAA");
+		}
+
+		@Override
+		public String[] createArray(int length) {
+			return new String[length];
+		}
+
+		@Override
+		public Iterable<String> order(List<String> insertionOrder) {
+			return insertionOrder;
+		}
+
+	}
+
+}