Merge branch 'master', future 0.7.

Author: UnquietCode

CONTRIBUTORS.md

@@ -1,5 +1,5 @@
 The following individuals and organizations have given their time and energy to help
 with the creation and maintenance of Flapi.
 
-* Jiri Jetmar - FLAPI-126
-* Chris Wensel ([@cwensel](https://github.com/cwensel)) - [#5, #8, FLAPI-114]
+* Jiri Jetmar - [#159]
+* Chris Wensel ([@cwensel](https://github.com/cwensel)) - [#5, #8, #12, #197]

Documentation.java

@@ -107,11 +107,27 @@
     .setReturnType(String class)
 
 // Generate class names which are condensed at the expense of
-// being mangled and not as readable by a human. This is
+// being mangled and not as readable by humans. This is
 // useful if you have a complicated descriptor which creates
-// class names too long to be compiled.  (optional, disabled by default)
+// class names too long to be compiled.  (disabled by default)
     .enableCondensedClassNames()
 
+// Provide a custom name generator instance, to be consulted
+// when creating the generated source code.
+//
+// The `DefaultNameGenerator` implementation will leave names
+// as they are. A more compact form can be achieved by using
+// the `TinyNameGenerator`, which will try to shorten names
+// as much as possible. For more consistent naming the
+// `HashedNameGenerator` can be used, which makes use of the
+// MD5 hashing algorithm.
+	.useCustomNameGenerator(NameGenerator generator)
+
+// Disable the printing of timestamps in the generated source
+// code. This will eliminate changes between successive executions
+// so long as the same version of the tool is used each time.
+	.disableTimestamps()
+
 // Complete the finished descriptor, returning a new 
 // `Descriptor` object. (**required**)
 .build()
@@ -546,8 +562,7 @@ public interface MyHelper {
  *
  * A method may specify a block chain by annotating any number
  * of parameters with `@BlockChain`. The parameter **must** be of
- * type `AtomicReference`, and the annotation must include the
- * type of the block, matching the generic signature of the reference.
+ * type `AtomicReference`.
  *
  * The helper will be introspected like the current type, and the
  * chain will be constructed moving from the leftmost parameter
@@ -569,15 +584,14 @@ interface MyHelper {
 
 	@Last
 	String startBlock(
-		int paramA,	@BlockChain(Alpha.class) AtomicReference<Alpha> helperA,
-		int paramB,	@BlockChain(Beta.class) AtomicReference<Beta> helperB
+		int paramA,	@BlockChain AtomicReference<Alpha> helperA,
+		int paramB,	@BlockChain AtomicReference<Beta> helperB
 	);
 }
 
 // Marks a method parameter as a container for another block's helper.
-// The types must match the generic signature of the `AtomicReference` object,
-// or else an error will be thrown at runtime.
-@BlockChain(Class<?> type)
+// The parameter **must** be of type `AtomicReference`.
+@BlockChain
 
 
 

README.md

@@ -56,8 +56,10 @@ composeEmail()
 
 ### [Getting Started](https://github.com/UnquietCode/Flapi/wiki/Getting-Started)
 If you are using Maven (or Gradle, or Ivy) you can download and install to your local repo, or include the following
-repository and dependency in your POM file:
-```
+repository and dependency in your build script:
+
+#### Maven
+```xml
 <repository>
   <id>uqc</id>
   <name>UnquietCode Repository</name>
@@ -73,13 +75,31 @@ repository and dependency in your POM file:
   <scope>test</scope>
 </dependency>
 ```
-In a test, define your `Descriptor` object and output the generated source code. (The
+
+#### Gradle
+```groovy
+repositories {
+  maven {
+    url 'http://www.unquietcode.com/maven/releases'
+  }
+}
+
+...
+
+dependencies {
+  testCompile 'unquietcode.tools.flapi:flapi:0.6.1'
+}
+```
+
+In a test define your `Descriptor` object and output the generated source code. (The
 [Pizza Builder](https://github.com/UnquietCode/Flapi/wiki/Pizza-Builder-Example)
 example is a simple descriptor you can start with.) You can also make use of the
 [maven plugin](https://github.com/UnquietCode/Flapi/wiki/Maven-Build-Plugin) to
 perform the code generation.
 
-At the time of writing, the project builds fine in JDK 6 and 7. However, please note that the automated builds are no longer being run against JDK 6.
+At the time of writing, the project builds fine in JDK 6 and 7. However, please note that
+the automated builds are no longer being run against JDK 6.
+
 
 ### Additional Resources
 

flapi-build-project/pom.xml

@@ -125,7 +125,7 @@
 			<plugin>
 				<groupId>org.codehaus.mojo</groupId>
 				<artifactId>build-helper-maven-plugin</artifactId>
-				<version>1.7</version>
+				<version>1.9.1</version>
 				<executions>
 					<execution>
 						<id>add-sources</id>

flapi-descriptor/src/main/java/unquietcode/tools/flapi/Supplier.java

@@ -0,0 +1,33 @@
+/*********************************************************************
+ 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;
+
+/**
+ * Simple little ditty to provide things.
+ *
+ * This is meant to be replaced by the real type
+ * contained within Java 8, whenever JDK 7 support
+ * is discontinued.
+ *
+ * TODO delete after propagation
+ *
+ * @author Ben Fagin
+ * @version 2015-01-16
+ */
+public interface Supplier<T> {
+	T get();
+}

flapi-descriptor/src/main/java/unquietcode/tools/flapi/generator/naming/NameGenerator.java

@@ -0,0 +1,66 @@
+/*********************************************************************
+ 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.generator.naming;
+
+/**
+ * Interface which defines a contract for managing the
+ * generated names of the various state classes.
+ *
+ * TODO delete after propagation
+ *
+ * @author Ben Fagin
+ * @version 2015-01-14
+ */
+public interface NameGenerator {
+
+	/**
+	 * Using the provided method name, return a
+	 * suitable string to use as a replacement.
+	 *
+	 * This name is incorporated into the complete class
+	 * name, which can then be further altered.
+	 *
+	 * @param methodKey the unique method key
+	 * @return a new method name, or the same, but not null
+	 */
+	String methodName(String methodKey);
+
+	/**
+	 * Using the provided state name, return a
+	 * suitable string to use as a replacement.
+	 *
+	 * @param stateKey the unique state key
+	 * @return a new state name, or the same, but not null
+	 */
+	String className(String stateKey);
+
+
+	// *Generator
+	String generatorName(String stateName);
+
+	// *Factory
+	String factoryName(String stateName);
+
+	// *Helper
+	String helperName(String stateName);
+
+	// *Builder
+	String builderName(String stateName);
+
+	// Start
+	String wrapperName(String stateName);
+}

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

@@ -12,10 +12,10 @@
  * @version 08-03-2014
  */
 public class DescriptorConfigurator implements DescriptorMaker {
+	private static final int NAME_GROUP = 3;
 
 	@Override
 	public Descriptor descriptor() {
-
 		Descriptor builder = Flapi.builder()
 			.setPackage("unquietcode.tools.flapi.configurator")
 			.setDescriptorName("DescriptorConfigurator")
@@ -37,6 +37,20 @@ public Descriptor descriptor() {
 					.addContent("humanly readable. If your generated class names are too long to be\n")
 					.addContent("compiled, you will have to use this.")
 				.finish()
+			.atMost(1, NAME_GROUP)
+
+			.addMethod("useCustomNameGenerator(unquietcode.tools.flapi.generator.naming.NameGenerator generator)")
+				.withDocumentation()
+					.addContent("Provide a custom NameGenerator.")
+				.finish()
+			.atMost(1, NAME_GROUP)
+
+			.addMethod("disableTimestamps()")
+				.withDocumentation()
+					.addContent("Disable the use of timestamps in the generated source code.\n")
+					.addContent("This will eliminate changes between successive executions so long\n")
+					.addContent("as the same version of the tool is used each time.")
+				.finish()
 			.atMost(1)
 
 			.addMethod("build()").last(Descriptor.class)

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

@@ -13,6 +13,7 @@
 public class MainDescriptor implements DescriptorMaker {
 	private static final int DOC_GROUP = 1;
 	private static final int RETURN_TYPE_GROUP = 2;
+	private static final int NAME_GROUP = 3;
 
 	@Override
 	public Descriptor descriptor() {
@@ -25,37 +26,53 @@ public Descriptor descriptor() {
 			.enableCondensedClassNames()
 
 			// descriptor methods
+
 			.addMethod("setPackage(String packageName)")
 				.withDocumentation("set the root package name to use for the generated classes")
-			.exactly(1)
-
-			.addMethod("setDescriptorName(String descriptorName)")
-				.withDocumentation("set the name of the top level descriptor")
-			.exactly(1)
+			.atMost(1)
 
 			.addMethod("setStartingMethodName(String methodName)")
 				.withDocumentation("set the name of the generator's starting method (default is 'create')")
 			.atMost(1)
 
-			.addMethod("setReturnType(Class returnType)")
-				.withDocumentation("set the return type for the top level descriptor (default is void)")
-			.atMost(1, RETURN_TYPE_GROUP)
-
-			.addMethod("setReturnType(String returnType)")
-				.withDocumentation("set the return type for the top level descriptor (default is void)")
-			.atMost(1, RETURN_TYPE_GROUP)
-
 			.addMethod("enableCondensedClassNames()")
 				.withDocumentation()
 					.addContent("Allow class names to be condensed, at the cost of no longer being\n")
 					.addContent("humanly readable. If your generated class names are too long to be\n")
 					.addContent("compiled, you will have to use this.")
 				.finish()
+			.atMost(1, NAME_GROUP)
+
+			.addMethod("useCustomNameGenerator(unquietcode.tools.flapi.generator.naming.NameGenerator generator)")
+				.withDocumentation()
+					.addContent("Provide a custom NameGenerator.")
+				.finish()
+			.atMost(1, NAME_GROUP)
+
+			.addMethod("disableTimestamps()")
+				.withDocumentation()
+					.addContent("Disable the use of timestamps in the generated source code.\n")
+					.addContent("This will eliminate changes between successive executions so long\n")
+					.addContent("as the same version of the tool is used each time.")
+				.finish()
 			.atMost(1)
 
-			.addMethod("build()")
-				.withDocumentation("Finish work and build the descriptor. This should only be called once.")
-			.last(Descriptor.class)
+			.addMethod("build()").last(Descriptor.class)
+
+			// descriptor methods
+
+			.addMethod("setDescriptorName(String descriptorName)")
+				.withDocumentation("set the name of the top level descriptor")
+			.exactly(1)
+
+			.addMethod("setReturnType(Class returnType)")
+				.withDocumentation("set the return type for the top level descriptor (default is void)")
+			.atMost(1, RETURN_TYPE_GROUP)
+
+			.addMethod("setReturnType(String returnType)")
+				.withDocumentation("set the return type for the top level descriptor (default is void)")
+			.atMost(1, RETURN_TYPE_GROUP)
+
 
 			// Method
 			.startBlock("Method", "addMethod(String methodSignature)")

flapi-parent/pom.xml

@@ -118,7 +118,7 @@
 			<plugin>
 				<groupId>org.codehaus.mojo</groupId>
 				<artifactId>build-helper-maven-plugin</artifactId>
-				<version>1.7</version>
+				<version>1.9.1</version>
 				<executions>
 					<execution>
 						<phase>initialize</phase>

flapi-runtime/src/main/java/unquietcode/tools/flapi/runtime/BlockInvocationHandler.java

@@ -83,6 +83,7 @@ public final Object invoke(Object proxy, Method method, Object[] args) throws Th
 
 	// handles legacy concerns before the chainInfo() array existed by
 	// synthesizing a new array from the older values
+	@SuppressWarnings("deprecation")
 	private Object invokeAndReturn(Method method, Object[] originalArgs, Object proxy, MethodInfo info) {
 		final ChainInfo[] chain;
 
@@ -105,7 +106,7 @@ private Object invokeAndReturn(Method method, Object[] originalArgs, Object prox
 
 	private Object invokeAndReturn(Method method, Object[] originalArgs, Object proxy, MethodInfo info, ChainInfo[] chain) {
 		// Don't use info.chainInfo() directly, since they might not match due
-		// to legacy considerations (will be removed in 1.0).
+		// to legacy considerations (will be removed in 1.0).  TODO remove in 1.0
 
 		final int depth = chain.length;