#44 block mixins

Adds support for mixing in the contents of an existing block. The block can
be referenced by name, or provided in the form of an annotated helper type.

Author: UnquietCode

Documentation.java

@@ -278,10 +278,10 @@ public enum TestEnum {
  * descriptor. (This technique can also be used recursively to
  * return a new instance of the current block.)
  *
- * When a block is declared, a name can be provided which uniquely
+ * (When a block is declared, a name can be provided which uniquely
  * identifies it within the scope of your descriptor. A block can
  * also be declared anonymously, in which case it cannot be
- * referenced.
+ * referenced.)
  */
 
 // Add a method which starts a new block, but by referencing it
@@ -290,6 +290,30 @@ public enum TestEnum {
 .addBlockReference(String blockName, String methodSignature)
 
 
+/**
+ * ### Block Mixins
+ *
+ * Similar to references, it is possible to combine the contents of
+ * a previously declared block with the current one by using a
+ * 'block mixin'. The mixin can be in the form of a string naming
+ * another block in the descriptor, or a class containing Flapi
+ * method annotations (see the [Annotations](#annotations) section
+ * below). Mixins are applied late, so it is possible to use
+ * forward references to blocks which have not yet been decalared.
+ *
+ * (When a block is declared, a name can be provided which uniquely
+ * identifies it within the scope of your descriptor. A block can
+ * also be declared anonymously, in which case it cannot be
+ * referenced.)
+ */
+
+// mixin the contents of another named block
+.addMixin(String blockName)
+
+// mixin the contents of an annotated interface or class
+.addMixin(Class blockType)
+
+
 /**
  * ## Methods 
  * 

flapi-descriptor/src/test/java/unquietcode/tools/flapi/builder/MainDescriptor.java

@@ -222,6 +222,15 @@ public Descriptor descriptor() {
 				.end()
 			.any()
 
+				// Mixins
+				.addMethod("addMixin(String blockName)")
+					.withDocumentation("mix in the contents of another block by name")
+				.any()
+
+				.addMethod("addMixin(Class helper)")
+					.withDocumentation("mix in the contents of an annotated helper")
+				.any()
+
 				.addMethod("addBlockReference(String blockName, String methodSignature)")
 					.withDocumentation("add a new method which proceeds to an existing block")
 					.addBlockChain()
@@ -290,6 +299,16 @@ public Descriptor descriptor() {
 					.addBlockReference("Method")
 				.end()
 			.any()
+
+			// Mixins for the top level block
+			.addMethod("addMixin(String blockName)")
+				.withDocumentation("mix in the contents of another block by name")
+			.any()
+
+			.addMethod("addMixin(Class helper)")
+				.withDocumentation("mix in the contents of an annotated block helper")
+			.any()
+
 		.build();
 
 		return builder;

src/main/java/unquietcode/tools/flapi/Flapi.java

@@ -62,8 +62,7 @@ public static DescriptorBuilder.Start<Void> builder(ExecutionListener...listener
 	public static DescriptorConfiguratorBuilder.Start<Void> create(Class<?> topBlock) {
 		checkNotNull(topBlock, "a starting block is required");
 
-		AnnotationIntrospector introspector = new AnnotationIntrospector();
-		DescriptorOutline outline = introspector.createDescriptor(topBlock);
+		DescriptorOutline outline = AnnotationIntrospector.createDescriptor(topBlock);
 		DescriptorConfiguratorHelperImpl helper = new DescriptorConfiguratorHelperImpl(outline);
 
 		return DescriptorConfiguratorGenerator.create(helper);

src/main/java/unquietcode/tools/flapi/Utilities.java

@@ -0,0 +1,56 @@
+/*********************************************************************
+ Copyright 2015 the Flapi 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 unquietcode.tools.flapi;
+
+import com.google.common.base.Function;
+import com.google.common.collect.Sets;
+
+import java.util.*;
+
+public final class Utilities {
+	
+	private Utilities() { }
+
+
+	// TODO use JDK8 classes
+
+	public static <T> void safeRecurse(T first, Function<T, Collection<T>> function) {
+		safeRecurse(Arrays.asList(first), function);
+	}
+
+	public static <T> void safeRecurse(Collection<T> first, Function<T, Collection<T>> function) {
+		safeRecurse(Sets.<T>newIdentityHashSet(), first, function);
+	}
+
+	private static <T> void safeRecurse(Set<T> seen, Collection<T> first, Function<T, Collection<T>> function) {
+		List<Collection<T>> collections = new ArrayList<>();
+		collections.add(first);
+
+		while (!collections.isEmpty()) {
+			Collection<T> collection = collections.remove(0);
+			if (collection == null || collection.isEmpty()) { continue; }
+
+			for (T e : collection) {
+				if (seen.contains(e)) { continue; }
+				else { seen.add(e); }
+
+				Collection<T> next = function.apply(e);
+				if (next != null) { collections.add(next); }
+			}
+		}
+	}
+}

src/main/java/unquietcode/tools/flapi/annotations/AnnotationIntrospector.java

@@ -45,7 +45,6 @@
 public class AnnotationIntrospector extends IntrospectorSupport {
 	private final Map<Class<?>, BlockOutline> blocks = new HashMap<Class<?>, BlockOutline>();
 
-
 	public static boolean isAnnotated(Class<?> clazz) {
 
 		// for every method in the class
@@ -67,15 +66,16 @@ public static boolean isAnnotated(Class<?> clazz) {
 
 	private static Set<Method> getAllMethods(Class<?> clazz) {
 		Method[] methods = SpringMethodUtils.getUniqueDeclaredMethods(clazz);
-		return new HashSet<Method>(Arrays.asList(methods));
+		return new HashSet<>(Arrays.asList(methods));
 	}
 
-	public DescriptorOutline createDescriptor(Class<?> clazz) {
+	public static DescriptorOutline createDescriptor(Class<?> clazz) {
 		DescriptorOutline descriptor = new DescriptorOutline();
 		descriptor.setPackageName(clazz.getPackage().getName() + ".builder");
 
 		// discover methods and set them on the blocks
-		boolean found = handleClass(descriptor, clazz);
+		AnnotationIntrospector introspector = new AnnotationIntrospector();
+		boolean found = introspector.handleClass(descriptor, clazz);
 
 		if (found) {
 			return descriptor;
@@ -87,6 +87,10 @@ public DescriptorOutline createDescriptor(Class<?> clazz) {
 		return descriptor;
 	}
 
+	public static BlockOutline createBlock(Class<?> clazz) {
+		return createDescriptor(clazz);
+	}
+
 	private BlockOutline handleClass(Class<?> blockClass) {
 		if (blocks.containsKey(blockClass)) {
 			return blocks.get(blockClass);

src/main/java/unquietcode/tools/flapi/graph/GraphBuilder.java

@@ -35,47 +35,18 @@ public class GraphBuilder {
 	private Map<BlockReference, BlockOutline> referenceMap = new IdentityHashMap<BlockReference, BlockOutline>();
 
 	public StateClass buildGraph(DescriptorOutline descriptor) {
+
 		// resolve block references
-		Map<String, BlockOutline> blocks = new HashMap<String, BlockOutline>();
-		findAllBlocks(blocks, descriptor);
+		Map<String, BlockOutline> blocks = BlockOutline.findAllBlocks(descriptor);
 		initializeReferenceMap(blocks, referenceMap, descriptor);
 
 		return convertBlock(descriptor);
 	}
 
-	private static void findAllBlocks(Map<String, BlockOutline> blocks, BlockOutline block) {
-		if (block instanceof BlockReference) {
-			return;
-		}
-
-		final String blockName = block.getName();
-
-		// Defensive, but really it is never ok to have reference cycles,
-		// and usually it means the helpers were called incorrectly.
-		if (blocks.containsKey(blockName)) {
-			if (blocks.get(blockName) == block) {
-				return;
-			} else {
-				throw new DescriptorBuilderException("Duplicate block name: "+blockName);
-			}
-		}
-
-		blocks.put(blockName, block);
-
-		for (MethodOutline method : block.getAllMethods()) {
-			for (BlockOutline chain : method.getBlockChain()) {
-				findAllBlocks(blocks, chain);
-			}
-		}
-
-		for (BlockOutline child : block.getBlocks()) {
-			findAllBlocks(blocks, child);
-		}
-	}
-
-	private static void initializeReferenceMap(Map<String, BlockOutline> blocks,
-		                                       Map<BlockReference, BlockOutline> references,
-	                                           BlockOutline block
+	private static void initializeReferenceMap(
+		Map<String, BlockOutline> blocks,
+		Map<BlockReference, BlockOutline> references,
+		BlockOutline block
 	){
 		if (block instanceof BlockReference) {
 			final BlockReference reference = (BlockReference) block;
@@ -131,7 +102,7 @@ private StateClass convertBlock(BlockOutline block) {
 		// create the sibling states
 		Set<StateClass> seen = Collections.newSetFromMap(new IdentityHashMap<StateClass, Boolean>());
 		Set<Set<MethodOutline>> workingSet = new HashSet<Set<MethodOutline>>();
-		workingSet.add(new TreeSet<MethodOutline>(allMethods));
+		workingSet.add(new TreeSet<>(allMethods));
 
 		while (!workingSet.isEmpty()) {
 			Set<Set<MethodOutline>> nextSet = new HashSet<Set<MethodOutline>>();

src/main/java/unquietcode/tools/flapi/helpers/BlockHelperImpl.java

@@ -17,6 +17,7 @@
 package unquietcode.tools.flapi.helpers;
 
 import unquietcode.tools.flapi.DescriptorBuilderException;
+import unquietcode.tools.flapi.annotations.AnnotationIntrospector;
 import unquietcode.tools.flapi.builder.Block.BlockHelper;
 import unquietcode.tools.flapi.builder.Method.MethodHelper;
 import unquietcode.tools.flapi.outline.BlockOutline;
@@ -120,6 +121,27 @@ static void _addEnumSelector(BlockOutline block, Class clazz, String methodSigna
 		}
 	}
 
+	@Override
+	public void addMixin(Class helper) {
+		_addMixin(block, helper);
+	}
+
+	static void _addMixin(BlockOutline block, Class mixin) {
+		if (!AnnotationIntrospector.isAnnotated(mixin)) {
+			System.err.println("the provided mixin type contains no Flapi method annotations");
+		}
+		block.addMixin(mixin);
+	}
+
+	@Override
+	public void addMixin(String blockName) {
+		_addMixin(block, blockName);
+	}
+
+	static void _addMixin(BlockOutline block, String mixin) {
+		block.addMixin(mixin);
+	}
+
 	@Override
 	public void endBlock() {
 		// nothing

src/main/java/unquietcode/tools/flapi/helpers/DescriptorHelperImpl.java

@@ -92,4 +92,14 @@ public void startBlock(String methodSignature, AtomicReference<MethodHelper> _he
 	public void addEnumSelector(Class clazz, String methodSignature, AtomicReference<MethodHelper> _helper1) {
 		BlockHelperImpl._addEnumSelector(outline, clazz, methodSignature, _helper1);
 	}
+
+	@Override
+	public void addMixin(Class helper) {
+		BlockHelperImpl._addMixin(outline, helper);
+	}
+
+	@Override
+	public void addMixin(String blockName) {
+		BlockHelperImpl._addMixin(outline, blockName);
+	}
 }

src/main/java/unquietcode/tools/flapi/outline/BlockOutline.java

@@ -42,7 +42,11 @@ public class BlockOutline implements Outline {
 	// block methods
 	private final Set<MethodOutline> methods = new TreeSet<MethodOutline>();
 
-	// ------------------------------ //
+	// mixins
+	private final Set<String> mixinBlocks = new HashSet<>();
+	private final Set<Class<?>> mixinTypes = new HashSet<>();
+
+	// ---------------------------------------------------- //
 
 	public Class<?> getHelperClass() {
 		return helperClass;
@@ -88,6 +92,22 @@ public void setName(String name) {
 		this.name = name.trim();
 	}
 
+	public void addMixin(String block) {
+		mixinBlocks.add(Objects.requireNonNull(block));
+	}
+
+	public void addMixin(Class<?> block) {
+		mixinTypes.add(Objects.requireNonNull(block));
+	}
+
+	public Set<String> getBlockMixins() {
+		return mixinBlocks;
+	}
+
+	public Set<Class<?>> getClassMixins() {
+		return mixinTypes;
+	}
+
 	public BlockOutline addBlock(String blockName) {
 		BlockOutline block = new BlockOutline();
 		block.name = blockName;
@@ -127,4 +147,48 @@ public Set<MethodOutline> getTriggeredMethods() {
 	public Set<MethodOutline> getAllMethods() {
 		return methods;
 	}
-}
+
+	//---o---o---o---o---o---o---o---o---o---o---o---o---o---o---o---o---o---o---o---o---o---o---//
+
+	public static Map<String, BlockOutline> findAllBlocks(BlockOutline block) {
+		Map<String, BlockOutline> blocks = new HashMap<>();
+		findAllBlocks(blocks, block);
+		return blocks;
+	}
+
+	private static void findAllBlocks(Map<String, BlockOutline> blocks, BlockOutline block) {
+		if (block instanceof BlockReference) {
+			return;
+		}
+
+		final String blockName = block.getName();
+
+		// Defensive, but really it is never ok to have reference cycles,
+		// and usually it means the helpers were called incorrectly.
+		if (blocks.containsKey(blockName)) {
+			if (blocks.get(blockName) == block) {
+				return;
+			} else {
+				throw new DescriptorBuilderException("Duplicate block name: "+blockName);
+			}
+		}
+
+		blocks.put(blockName, block);
+
+		for (MethodOutline method : block.getAllMethods()) {
+			for (BlockOutline chain : method.getBlockChain()) {
+				findAllBlocks(blocks, chain);
+			}
+		}
+
+		for (BlockOutline child : block.getBlocks()) {
+			findAllBlocks(blocks, child);
+		}
+	}
+
+	protected final void applyMixin(BlockOutline other) {
+		for (MethodOutline method : other.getAllMethods()) {
+			this.methods.add(method.copy());
+		}
+	}
+}