Refactored internal logic of InclusionService into InclusionResolvers

This made it possible to further improve performance by only activating
the InclusionResolvers that have been actually configured to include or
exclude nodes. It also made it possible for custom inclusion resolvers
to be every bit as powerful as the built-in ones, because they are all
treated the same.

The InclusionResolver mechanism also allowed me to get rid of the
InclusionNode and replace it with ValueNode. The original logic that
justified the creation of the InclusionNode has been migrated to the
NodePathInclusionResolver.

Author: SQiShER

CHANGELOG.md

@@ -3,21 +3,14 @@
 ## 0.91
 
 ### Features
-- **Inclusion:** Implemented a mechanism to control the inclusion of properties of 
-  specific object types.
-- **Inclusion:** Implemented a mechanism to register custom inclusion resolvers to 
-  support inclusion rules far beyond the built-in ones.
-- **Introspection:** Implemented a mechanism to register a custom instance factory, 
-  which will be used by `DiffNode#canonicalSet` in order to create instances of missing 
-  objects 
+- **Inclusion:** Implemented a mechanism to control the inclusion of properties of specific object types.
+- **Inclusion:** Implemented a mechanism to register custom inclusion resolvers to support inclusion rules far beyond the built-in ones.
+- **Introspection:** Implemented a mechanism to register a custom instance factory, which is used by `DiffNode#canonicalSet` in order to create instances of missing objects 
 
 ### Improvements
-- **Inclusion:** Performance improvements (via @Deipher)
-- **DiffNode:** `canonicalSet` now automatically creates missing objects along the 
-  path to the root object 
+- **Inclusion:** Performance improvements (Thanks [@Deipher](https://github.com/Deipher))
+- **Inclusion:** `InclusionService` has been split into several `InclusionResolver`s
+- **DiffNode:** `canonicalSet` now automatically creates missing objects along the path to the root object 
 
 ### Bugfixes
-- **Circular Reference Detection:** Fixed 'Detected inconsistency in 
-  enter/leave sequence. Must always be LIFO.' bug that could occur 
-  due to inconsistent cleanup of the instance memory when a circular
-  reference has been detected.
+- **Circular Reference Detection:** Fixed 'Detected inconsistency in enter/leave sequence. Must always be LIFO.' bug that could occur due to inconsistent cleanup of the instance memory when a circular reference has been detected.

src/integration-test/java/de/danielbechler/diff/ObjectDifferIT.java

@@ -299,13 +299,17 @@ public void testCompareWithDifferentTypes()
 	@Test(groups = INTEGRATION)
 	public void testCompareWithIgnoredProperty()
 	{
-		final ObjectDifferBuilder objectDifferBuilder = ObjectDifferBuilder.startBuilding();
-		objectDifferBuilder.inclusion().exclude().node(NodePath.withRoot());
-		objectDiffer = objectDifferBuilder.build();
-
-		final DiffNode node = objectDiffer.compare("foo", "bar");
+		objectDiffer = ObjectDifferBuilder.startBuilding()
+				.inclusion()
+				.exclude().node(NodePath.with("value")).and()
+				.filtering().returnNodesWithState(DiffNode.State.IGNORED).and()
+				.build();
+
+		final ObjectWithIdentityAndValue working = new ObjectWithIdentityAndValue("1", "foo");
+		final ObjectWithIdentityAndValue base = new ObjectWithIdentityAndValue("1", "bar");
+		final DiffNode node = objectDiffer.compare(working, base);
 
-		NodeAssertions.assertThat(node).self().hasState(DiffNode.State.IGNORED);
+		NodeAssertions.assertThat(node).child("value").hasState(DiffNode.State.IGNORED);
 	}
 
 	@Test(groups = INTEGRATION)

src/integration-test/java/de/danielbechler/diff/inclusion/ExclusiveInclusionIT.groovy

@@ -0,0 +1,142 @@
+/*
+ * Copyright 2014 Daniel Bechler
+ *
+ * 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 de.danielbechler.diff.inclusion
+
+import de.danielbechler.diff.ObjectDifferBuilder
+import de.danielbechler.diff.node.DiffNode
+import de.danielbechler.diff.path.NodePath
+import spock.lang.Specification
+
+class ExclusiveInclusionIT extends Specification {
+
+	def objectDifferBuilder = ObjectDifferBuilder.startBuilding()
+			.filtering()
+			.returnNodesWithState(DiffNode.State.IGNORED).and()
+
+	def 'inclusion via type based property does NOT exclude nodes that are not explicitly included'() {
+		given:
+		  def base = new A(b: new B(foo: 'base', bar: 'base'), c: new C(baz: 'base'))
+		  def working = new A(b: new B(foo: 'working', bar: 'base'), c: new C(baz: 'working'))
+
+		when:
+		  def node = objectDifferBuilder
+				  .inclusion()
+				  .include().propertyNameOfType(B, 'foo').and()
+				  .build()
+				  .compare(working, base)
+
+		then:
+		  node.getChild('b').getChild('foo').isChanged()
+		  node.getChild('b').getChild('bar').isIgnored()
+		  node.getChild('c').getChild('baz').isChanged()
+	}
+
+	class A {
+		B b
+		C c
+	}
+
+	class B {
+		String foo
+		String bar
+	}
+
+	class C {
+		String baz
+	}
+
+	def 'inclusion via property name does exclude nodes that are not explicitly included'() {
+		given:
+		  def base = new A(b: new B(foo: 'base', bar: 'base'), c: new C(baz: 'base'))
+		  def working = new A(b: new B(foo: 'working', bar: 'working'), c: new C(baz: 'working'))
+
+		when:
+		  def node = objectDifferBuilder
+				  .inclusion()
+				  .include().propertyName('b').and()
+				  .build()
+				  .compare(working, base)
+
+		then:
+		  node.getChild('b').hasChanges()
+		  node.getChild('b').getChild('foo').isChanged()
+		  node.getChild('b').getChild('bar').isChanged()
+		  node.getChild('c').isIgnored()
+	}
+
+	def 'inclusion via node path does exclude nodes that are not explicitly included'() {
+		given:
+		  def base = new A(b: new B(foo: 'base', bar: 'base'), c: new C(baz: 'base'))
+		  def working = new A(b: new B(foo: 'working', bar: 'working'), c: new C(baz: 'working'))
+
+		when:
+		  def node = objectDifferBuilder
+				  .inclusion()
+				  .include().node(NodePath.with('b')).and()
+				  .build()
+				  .compare(working, base)
+
+		then:
+		  node.getChild('b').hasChanges()
+		  node.getChild('b').getChild('foo').isChanged()
+		  node.getChild('b').getChild('bar').isChanged()
+		  node.getChild('c').isIgnored()
+	}
+
+	def 'inclusion via type does exclude nodes that are not explicitly included - even its children'() {
+		given:
+		  def base = new A(b: new B(foo: 'base', bar: 'base'), c: new C(baz: 'base'))
+		  def working = new A(b: new B(foo: 'working', bar: 'working'), c: new C(baz: 'working'))
+
+		when: 'the property with type B is explicitly included'
+		  def node = objectDifferBuilder
+				  .inclusion()
+				  .include().type(B).and()
+				  .build()
+				  .compare(working, base)
+
+		then: 'the included type should not be ignored'
+		  node.getChild('b').isIgnored() == false
+
+		and: 'its sibling with a different type schould be ignored'
+		  node.getChild('c').isIgnored()
+
+		and: 'the children are also ignored, even though the parent is included'
+		  node.getChild('b').getChild('foo').isIgnored()
+		  node.getChild('b').getChild('bar').isIgnored()
+	}
+
+	def 'inclusion via category does exclude nodes that are not explicitly included'() {
+		given:
+		  def base = new A(b: new B(foo: 'base', bar: 'base'), c: new C(baz: 'base'))
+		  def working = new A(b: new B(foo: 'working', bar: 'working'), c: new C(baz: 'working'))
+
+		when:
+		  def node = objectDifferBuilder
+				  .categories().ofNode(NodePath.with('b')).toBe('included-category').and()
+				  .inclusion()
+				  .include().category('included-category').and()
+				  .build()
+				  .compare(working, base)
+
+		then:
+		  node.getChild('b').hasChanges()
+		  node.getChild('b').getChild('foo').isChanged()
+		  node.getChild('b').getChild('bar').isChanged()
+		  node.getChild('c').isIgnored()
+	}
+}

src/integration-test/java/de/danielbechler/diff/inclusion/InclusionAT.groovy

@@ -116,7 +116,7 @@ class InclusionAT extends Specification {
 	def 'excludes always win over includes'() {
 		given:
 		  objectDifferBuilder.inclusion()
-				  .exclude().node(NodePath.with('songs'))
+				  .exclude().node(NodePath.with('songs')).also()
 				  .include().node(NodePath.startBuildingFrom(NodePath.with('songs')).collectionItem('Happy').build())
 		when:
 		  def node = objectDifferBuilder.build().compare(working, base)
@@ -146,8 +146,10 @@ class InclusionAT extends Specification {
 
 	def 'including an element by path implicitly includes its parents'() {
 		given:
-		  objectDifferBuilder.inclusion()
-				  .include().node(NodePath.startBuilding().propertyName('songs').collectionItem(new Song(title: 'Happy')).build())
+		  def includedNodePath = NodePath.startBuilding()
+				  .propertyName('songs')
+				  .collectionItem(new Song(title: 'Happy'))
+		  objectDifferBuilder.inclusion().include().node(includedNodePath.build())
 		when:
 		  def node = objectDifferBuilder.build().compare(working, base)
 		then:

src/integration-test/java/de/danielbechler/diff/inclusion/PropertyInclusionViaInclusionResolverAT.groovy

@@ -30,6 +30,11 @@ class PropertyInclusionViaInclusionResolverAT extends Specification {
 
 		given: "custom inclusion resolver that excludes all properties named 'foo'"
 		  def inclusionResolver = new InclusionResolver() {
+			  @Override
+			  boolean enablesStrictIncludeMode() {
+				  return false
+			  }
+
 			  @Override
 			  Inclusion getInclusion(DiffNode node) {
 				  if (node.propertyAware && node.propertyName == 'foo') {

src/main/java/de/danielbechler/diff/inclusion/CategoryInclusionResolver.java

@@ -0,0 +1,83 @@
+/*
+ * Copyright 2014 Daniel Bechler
+ *
+ * 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 de.danielbechler.diff.inclusion;
+
+import de.danielbechler.diff.category.CategoryResolver;
+import de.danielbechler.diff.node.DiffNode;
+import de.danielbechler.util.Assert;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Set;
+
+import static de.danielbechler.diff.inclusion.Inclusion.DEFAULT;
+import static de.danielbechler.diff.inclusion.Inclusion.EXCLUDED;
+import static de.danielbechler.diff.inclusion.Inclusion.INCLUDED;
+
+class CategoryInclusionResolver implements InclusionResolver
+{
+	private final CategoryResolver categoryResolver;
+	private final Map<String, Inclusion> categoryInclusions = new HashMap<String, Inclusion>();
+	private boolean containsIncluded;
+	private boolean containsExcluded;
+
+	public CategoryInclusionResolver(final CategoryResolver categoryResolver)
+	{
+		Assert.notNull(categoryResolver, "categoryResolver");
+		this.categoryResolver = categoryResolver;
+	}
+
+	public Inclusion getInclusion(final DiffNode node)
+	{
+		if (isInactive())
+		{
+			return DEFAULT;
+		}
+		final Set<String> categories = categoryResolver.resolveCategories(node);
+		Inclusion resolvedInclusion = DEFAULT;
+		for (final String category : categories)
+		{
+			final Inclusion configuredInclusion = categoryInclusions.get(category);
+			if (configuredInclusion == EXCLUDED)
+			{
+				return EXCLUDED;
+			}
+			if (configuredInclusion == INCLUDED)
+			{
+				resolvedInclusion = INCLUDED;
+			}
+		}
+		return resolvedInclusion;
+	}
+
+	private boolean isInactive()
+	{
+		return !containsIncluded && !containsExcluded;
+	}
+
+	public boolean enablesStrictIncludeMode()
+	{
+		return containsIncluded;
+	}
+
+	public void setInclusion(final String category, final Inclusion inclusion)
+	{
+		categoryInclusions.put(category, inclusion);
+		containsIncluded = categoryInclusions.containsValue(INCLUDED);
+		containsExcluded = categoryInclusions.containsValue(EXCLUDED);
+	}
+}

src/main/java/de/danielbechler/diff/inclusion/InclusionConfigurer.java

@@ -56,13 +56,13 @@ public interface InclusionConfigurer
 
 	public interface ToInclude
 	{
-		ToIncludeAndReturn category(String category);
+		ToInclude category(String category);
 
-		ToIncludeAndReturn type(Class<?> type);
+		ToInclude type(Class<?> type);
 
-		ToIncludeAndReturn node(NodePath nodePath);
+		ToInclude node(NodePath nodePath);
 
-		ToIncludeAndReturn propertyName(String propertyName);
+		ToInclude propertyName(String propertyName);
 
 		/**
 		 * Include one or more properties of the given type. This automatically causes all other properties of that
@@ -73,25 +73,22 @@ public interface ToInclude
 		 * @param propertyNames One or more property names to include.
 		 * @see de.danielbechler.diff.introspection.ObjectDiffProperty#inclusion()
 		 */
-		ToIncludeAndReturn propertyNameOfType(Class<?> type, String... propertyNames);
+		ToInclude propertyNameOfType(Class<?> type, String... propertyNames);
 
-		ToExclude exclude();
-	}
+		InclusionConfigurer also();
 
-	public interface ToIncludeAndReturn extends ToInclude
-	{
 		ObjectDifferBuilder and();
 	}
 
 	public interface ToExclude
 	{
-		ToExcludeAndReturn category(String category);
+		ToExclude category(String category);
 
-		ToExcludeAndReturn type(Class<?> type);
+		ToExclude type(Class<?> type);
 
-		ToExcludeAndReturn node(NodePath nodePath);
+		ToExclude node(NodePath nodePath);
 
-		ToExcludeAndReturn propertyName(String property);
+		ToExclude propertyName(String property);
 
 		/**
 		 * Excludes one or more properties of the given type.
@@ -101,13 +98,11 @@ public interface ToExclude
 		 * @see de.danielbechler.diff.introspection.ObjectDiffProperty#inclusion()
 		 * @see de.danielbechler.diff.introspection.ObjectDiffProperty#excluded()
 		 */
-		ToExcludeAndReturn propertyNameOfType(Class<?> type, String... propertyNames);
+		ToExclude propertyNameOfType(Class<?> type, String... propertyNames);
 
-		ToInclude include();
-	}
+		InclusionConfigurer also();
 
-	public interface ToExcludeAndReturn extends ToExclude
-	{
 		ObjectDifferBuilder and();
 	}
+
 }