Readme of VMF Maven Plugin completed.

Several Java docs added.
Bug in TestVMFMojo corrected.

maven-plugin/README.md

@@ -2,15 +2,17 @@
 
 [ ![Download](https://api.bintray.com/packages/miho/VMF/VMF-Gradle-Plugin/images/download.svg) ](https://bintray.com/miho/VMF/VMF-Maven-Plugin/_latestVersion)
 
-Just add the plugin to use it with maven (get the latest version from [here](https://plugins.maven.org/plugin/eu.mihosoft.vmf)):
+## Usage
+
+Just add the plugin to your project Pom to generate sources and test sources:
 
 ```xml
 <build>
 	<plugins>
 		<plugin>
 			<groupId>eu.mihosoft.vmf</groupId>
 			<artifactId>vmf-maven-plugin</artifactId>
-			<version>0.1</version>
+			<version>0.2.8.0</version>
 			<configuration>
 			</configuration>
 			<executions>
@@ -32,63 +34,134 @@ Just add the plugin to use it with maven (get the latest version from [here](htt
 </build>
 ```
 
-and remember to reference VMF jar files to use it:
+and remember to reference the VMF jar files in the dependency section:
 
 ```xml
 <dependencies>
 	<dependency>
 		<groupId>eu.mihosoft.vmf</groupId>
 		<artifactId>vmf</artifactId>
-		<version>0.2.7.15</version>
+		<version>0.2.8.0</version>
 	</dependency>
 	<dependency>
 		<groupId>eu.mihosoft.vmf</groupId>
 		<artifactId>vmf-runtime</artifactId>
-		<version>0.2.7.15</version>
+		<version>0.2.8.0</version>
 	</dependency>
 </dependencies>
 ```
 
+A full example can be found in the test suite folder of the VMF project.
+
+## Getting Help
+
+The Apache Maven Help Plugin can be used to get a full description of the available goals and the usage of
+the VMF Maven Plugin:
+
+	mvn help:describe -DgroupId=eu.mihosoft.vmf -DartifactId=vmf-maven-plugin -Dversion=0.2.8.0
+	[INFO] VMF Maven Plugin 0.2.8.0
+	  Generates Java implementation classes from VMF model definitions. VMF is a
+	  lightweight modeling framework. It conveniently translates annotated Java
+	  interfaces into powerful implementations.
+
+	vmf:vmf
+	  Generates Java implementation classes from source files in VMF model
+	  definition during Maven build.
+	  Parameters:
+	  
+	  - vmf.sourceDirectory - the vmf model source directory (default:
+	    ${basedir}/src/main/vmf)
+	  - vmf.targetDirectory - the directory with generated Java files (default:
+	    ${project.build.directory}/generated-sources/java-vmf)
+
+	  Available parameters:
+
+	    sourceDirectory (Default: ${basedir}/src/main/vmf)
+	      Source directory containing the vmf model files.
+	      User property: vmf.sourceDirectory
+
+	    targetDirectory (Default:
+	    ${project.build.directory}/generated-sources/java-vmf)
+	      The target folder where the generated Java classes will be saved to.
+	      User property: vmf.targetDirectory
+
+## FAQ
+
+### Generating Eclipse .classpath File
+
+I am currently facing a problem when using the Apache Maven Eclipse Plugin to generate Eclipse Classpath. When models are located in the test source tree of a Maven project the generated target folder is not added to the Eclipse classpath by default. An invocation of
+
+	mvn eclipse:eclipse
+
+does not generate the test classes and does not add the generated test classes to the classpath.
+
+As a workaround you can generate the test sources together with the Eclipse classpath:
+
+	mvn generate-test-sources eclipse:eclipse
+
+See also this thread from [Stackoverflow](https://stackoverflow.com/questions/19701295/maven-why-does-adding-test-source-via-build-helper-not-work-when-generating-ecl "Maven: Why does adding test source via build helper not work when generating eclipse project?").
+
+### Eclipse Compiler Errors
+
+Eclipse might complain about compile errors in the generated code like
+
+	The target type of this expression is not a well formed parameterized type due to bound(s) mismatch	OwnerImpl.java	/test-suite/target/generated-test-sources/java-vmf/eu/mihosoft/vmftest/complex/horses/impl	line 118	Java Problem
+
+I found several links to a similar problem 
+
+* the [Eclipse issue 425278](https://bugs.eclipse.org/bugs/show_bug.cgi?id=425278 "425278")
+* with a reference to an [Open JDK bug JDK-8033810](https://bugs.openjdk.java.net/browse/JDK-8033810 "JDK-8033810")
+* which is [a duplicate of this JDK-8048547](https://bugs.openjdk.java.net/browse/JDK-8048547 "JDK-8048547")
+
+The code compiles fine with Open JDK but fails inside Eclipse.
+
+Currently I tend to think that this is an Open JDK bug and the code should not compile. At least this is what I read from bug JDK-8033810 that the Eclipse guys filed against Open JDK.
+
+
 ## Building the VMF Maven Plugin
 
-Switch to the plugin directory in a shell on your system (bash or command). Then execute the comman given below.
+If you are plugin developer and want to build the VMF Maven Plugin by yourself please follow the instructions given below.
+
+### Prerequisites
 
-### Unix
+If not already done you must install VMF core and VM runtime into your local Maven repository before you can build the VMF Maven Plugin.
+
+Switch to the core directory and invoke the corresponding Gradle task. Repeat this in the runtime directory as well.
+
+#### Unix
 
 ```bash
-cd maven-plugin
-./maven.sh install
+cd core
+gradlew publishToMavenLocal
+cd ../runtime
+gradlew publishToMavenLocal
 ```
 
-### Windows
+#### Windows
 
 ```bat
-cd maven-plugin
-maven.bat install
+cd core
+gradlew.bat publishToMavenLocal
+cd ..\runtime
+gradlew.bat publishToMavenLocal
 ```
 
-## Prerequisites
-
-If not already done you must install VMF core and VM runtime into your local Maven repository before you can build the plugin.
+### Build
 
-Switch to the core directory and invoke the corresponding Gradle task. Repeat this step after switching to the runtime directory.
+You should be able to build and install the Maven plugin succesfully afterwards. Switch to the plugin directory in a shell on your system (bash or command). Then execute the command given below.
 
-### Unix
+#### Unix
 
 ```bash
-cd core
-./maven.sh install
-cd ../runtime
+cd maven-plugin
 ./maven.sh install
 ```
 
-### Windows
+#### Windows
 
 ```bat
-cd core
-maven.bat install
-cd ..\runtime
+cd maven-plugin
 maven.bat install
 ```
 
-You should be able to install the Maven plugin succesfully afterwards.
+The VMF Maven Plugin should be installed into your local Maven repository by this.

maven-plugin/pom.xml

@@ -38,7 +38,6 @@ Computing and Visualization in Science, 2013, 16(4),
 	<description>Generates Java implementation classes from VMF model definitions. VMF is a lightweight modeling framework. It conveniently translates annotated Java interfaces into powerful implementations.</description>
 	<licenses>
 		<license>
-			<!-- to be clarified! -->
 			<name>The Apache Software License, Version 2.0</name>
 			<url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
 		</license>

maven-plugin/src/main/java/eu/mihosoft/vmf/maven/AbstractVMFMojo.java

@@ -45,6 +45,49 @@
 /**
  * This abstract class is the base for the VMFMojos used to generate sources
  * during Maven build.
+ * 
+ * There are two sub classes of this class
+ * <ul>
+ *   <li>GenerateVMFSourcesMojo - generates classes from models in project source tree</li>
+ *   <li>GenerateVMFTestSourcesMojo - generates classes from models in project test tree</li>
+ * </ul>
+ * 
+ * <p> The plugin execution is invoked with a
+ * <ul>
+ *   <li>source folder - the folder containing the model files (Java source files)</li>
+ *   <li>target folder - the destination folder where generated code is written to</li>
+ * </ul>
+ * 
+ * <p> The source folder with its sub directories is scanned for model files with extension .java.
+ * By convention the parent directory of a model file must be named "vmfmodel".
+ * All other model files are ignored and a warning is logged.
+ * 
+ * <p>After collecting all model files below the source directory they are grouped by their
+ * parent directory.
+ * 
+ * <ul>
+ *   <li>VMF/test-suite/src/test/vmf/eu/mihosoft/vmftest/complex/account/vmfmodel
+ *     <ul>
+ *       <li>Account.java</li>
+ *     </ul>
+ *   </li>
+ *   <li>VMF/test-suite/src/test/vmf/eu/mihosoft/vmftest/annotations/vmfmodel
+ *     <ul>
+ *       <li>AnnotatedModel.java</li>
+ *     </ul>
+ *   </li>
+ *   <li>VMF/test-suite/src/test/vmf/eu/mihosoft/vmftest/complex/unparsermodel/vmfmodel
+ *     <ul>
+ *       <li>GrammarLangModel.java</li>
+ *       <li>UnparserModel.java</li>
+ *     </ul>
+ *   </il>
+ * </ul>
+ * 
+ * <p>For every group code (model directory) code generation is executed.
+ * 
+ * <p>The generated target folder is added to the list of the Java source folders of the project afterwards.
+ * 
  */
 public abstract class AbstractVMFMojo extends AbstractMojo {
 	/** The maven project. */
@@ -54,19 +97,22 @@ public abstract class AbstractVMFMojo extends AbstractMojo {
 	@Override
 	public void execute() throws MojoExecutionException, MojoFailureException {
 		Log log = getLog();
+		// get source directory
 		File sourceDirectory = getSourceDirectory();
 		// do nothing in case of missing source directory
 		if (!sourceDirectory.exists()) {
 			log.info("Source folder ignored as it does not exist " + sourceDirectory);
 			return;
 		}
+		// get all source files from source directory
 		File[] sourceFiles = getSourceFiles(sourceDirectory);
 		Map<File, List<File>> sourceModel = getSourceModel(sourceFiles);
 		// do nothing if no source files found
 		if (sourceModel.size() == 0) {
 			log.info("Nothing to do, no source files found in " + sourceDirectory);
 			return;
 		}
+		// get target directory
 		File targetDirectory = getTargetDirectory();
 		// create non-existant target directory
 		if (!targetDirectory.exists()) {
@@ -77,13 +123,17 @@ public void execute() throws MojoExecutionException, MojoFailureException {
 				return;
 			}
 		}
+		// start generation
 		log.info("Generating source files from " + sourceFiles.length + " model file" + ((sourceFiles.length == 1) ? "" : "s") + " to "
 				+ targetDirectory);
-		addToSources(targetDirectory.getAbsolutePath());
+		// add target folder to project sources
+		addGeneratedFolderToProject(getTargetDirectory().getAbsolutePath());
 		// generate VMF sources
+		// iterate over all packages an run generation process
 		File[] packageFiles = sourceModel.keySet().toArray(new File[sourceModel.size()]);
 		try {
 			for (File packageFile : packageFiles) {
+				// run generation process fpr package
 				List<File> sourceFileList = sourceModel.get(packageFile);
 				File[] sourceFileArray = sourceFileList.toArray(new File[sourceFileList.size()]);
 				// log some infos for user
@@ -105,6 +155,13 @@ public void execute() throws MojoExecutionException, MojoFailureException {
 		}
 	}
 
+	/**
+	 * Converts the list of source files to a model map.
+	 * <p>For every model directory all contained model sources
+	 * are collected and stored with the model directory as key.
+	 * @param sourceFiles the complete list of all source file.
+	 * @return map with model directory and corresponding model sources.
+	 */
 	private Map<File, List<File>> getSourceModel(File[] sourceFiles) {
 		Map<File, List<File>> packageMap = new HashMap<File, List<File>>();
 		for (File sourceFile : sourceFiles) {
@@ -195,10 +252,9 @@ public boolean accept(File file) {
 	/**
 	 * Adds the target directory with Java source files to the compile path.
 	 * 
-	 * @param sourcePath the target directory with Java source files to the compile
-	 *                   path.
+	 * @param folder the generated folder path.
 	 */
-	protected abstract void addToSources(String sourcePath);
+	protected abstract void addGeneratedFolderToProject(String folder);
 
 	/**
 	 * Gets the Maven project.

maven-plugin/src/main/java/eu/mihosoft/vmf/maven/GenerateVMFSourcesMojo.java

@@ -76,7 +76,7 @@ protected void setTargetDirectory(File targetDirectory) {
 	}
 
 	@Override
-	protected void addToSources(String sourcePath) {
-		getProject().addCompileSourceRoot(sourcePath);
+	protected void addGeneratedFolderToProject(String folder) {
+		getProject().addTestCompileSourceRoot(folder);
 	}
 }

maven-plugin/src/main/java/eu/mihosoft/vmf/maven/GenerateVMFTestSourcesMojo.java

@@ -75,7 +75,7 @@ protected File getTargetDirectory() {
 	}
 
 	@Override
-	protected void addToSources(String sourcePath) {
-		getProject().addTestCompileSourceRoot(sourcePath);
+	protected void addGeneratedFolderToProject(String folder) {
+		getProject().addTestCompileSourceRoot(folder);
 	}
 }

maven-plugin/src/test/java/eu/mihosoft/vmf/maven/TestVMFMojo.java

@@ -53,7 +53,7 @@ public void testGenerateVMFSourcesMojo() throws MojoExecutionException, MojoFail
 		mojo.setTargetDirectory(targetDirectory);
 		mojo.setProject(new MavenProject());
 		mojo.execute();
-		List<String> compileSourceRoots = mojo.getProject().getCompileSourceRoots();
+		List<String> compileSourceRoots = mojo.getProject().getTestCompileSourceRoots();
 		assertEquals("Unexpected number of source roots encountered", 1, compileSourceRoots.size());
 		assertEquals("Wrong source directory found", compileSourceRoots.get(0), targetDirectory.getAbsolutePath());
 	}

test-suite/maven.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
 
-export revision=`cat ../config/common.properties | grep publication.version | cut -d'=' -f2`
+export revision=`cat ../config/common.properties | grep ^publication.version | cut -d'=' -f2`
 
 mvn -Drevision=${revision} "$@"

test-suite/pom.xml

@@ -1,4 +1,30 @@
 <?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+Copyright 2017-2019 Michael Hoffer <[email protected]>. All rights reserved.
+Copyright 2017-2019 Goethe Center for Scientific Computing, University Frankfurt. All rights reserved.
+Copyright 2017 Samuel Michaelis. All rights reserved.
+
+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.
+
+If you use this software for scientific research then please cite the following publication(s):
+
+M. Hoffer, C. Poliwoda, & G. Wittum. (2013). Visual reflection library:
+a framework for declarative GUI programming on the Java platform.
+Computing and Visualization in Science, 2013, 16(4),
+181–192. http://doi.org/10.1007/s00791-014-0230-y
+-->
+
 <project xmlns="http://maven.apache.org/POM/4.0.0"
 	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">