#132 docs and incorporated some review comments

processor/pom.xml

@@ -88,7 +88,7 @@
                 <artifactId>maven-surefire-plugin</artifactId>
                 <configuration>
                     <systemPropertyVariables>
-                        <mapper.test.output.dir>compilation-tests-${surefire.forkNumber}</mapper.test.output.dir>
+                        <mapper.test.output.dir>compilation-tests_fork-${surefire.forkNumber}</mapper.test.output.dir>
                     </systemPropertyVariables>
                 </configuration>
             </plugin>

processor/src/test/java/org/mapstruct/ap/testutil/runner/AnnotationProcessorTestRunner.java

@@ -23,12 +23,24 @@ import java.net.URL;
 import org.junit.runners.BlockJUnit4ClassRunner;
 import org.junit.runners.model.FrameworkMethod;
 import org.junit.runners.model.Statement;
+import org.mapstruct.ap.testutil.WithClasses;
+import org.mapstruct.ap.testutil.compilation.annotation.ExpectedCompilationOutcome;
+import org.mapstruct.ap.testutil.compilation.annotation.ProcessorOption;
 
 /**
  * A JUnit4 runner for Annotation Processor tests.
  * <p>
  * Test classes and test methods are safe to be executed in parallel.
+ * <p>
+ * The classes to be compiled for a given test method must be specified via {@link WithClasses}. In addition the
+ * following things can be configured optionally :
+ * <ul>
+ * <li>Processor options to be considered during compilation via {@link ProcessorOption}.</li>
+ * <li>The expected compilation outcome and expected diagnostics can be specified via {@link ExpectedCompilationOutcome}
+ * . If no outcome is specified, a successful compilation is assumed.</li>
+ * </ul>
  *
+ * @author Gunnar Morling
  * @author Andreas Gudian
  */
 public class AnnotationProcessorTestRunner extends BlockJUnit4ClassRunner {

processor/src/test/java/org/mapstruct/ap/testutil/runner/CompilingStatement.java

@@ -63,7 +63,7 @@ class CompilingStatement extends Statement {
      */
     public static final String MAPPER_TEST_OUTPUT_DIR_PROPERTY = "mapper.test.output.dir";
     private static final String TARGET_COMPILATION_TESTS = "/target/"
-        + System.getProperty( MAPPER_TEST_OUTPUT_DIR_PROPERTY, "compilation-tests" ) + "_";
+        + System.getProperty( MAPPER_TEST_OUTPUT_DIR_PROPERTY, "compilation-tests" ) + "_thread-";
 
     private static final String LINE_SEPARATOR = System.getProperty( "line.separator" );
     private static final DiagnosticDescriptorComparator COMPARATOR = new DiagnosticDescriptorComparator();

processor/src/test/java/org/mapstruct/ap/testutil/runner/ModifiableURLClassLoader.java

@@ -19,6 +19,7 @@
 package org.mapstruct.ap.testutil.runner;
 
 import java.io.File;
+import java.lang.reflect.InvocationTargetException;
 import java.net.MalformedURLException;
 import java.net.URL;
 import java.net.URLClassLoader;
@@ -36,7 +37,7 @@ public class ModifiableURLClassLoader extends URLClassLoader {
     private static final String ORG_MAPSTRUCT_AP_TEST = "org.mapstruct.ap.test.";
 
     static {
-        ClassLoader.registerAsParallelCapable();
+        tryRegisterAsParallelCapable();
     }
 
     private final ConcurrentMap<URL, URL> addedURLs = new ConcurrentHashMap<URL, URL>();
@@ -73,6 +74,27 @@ public class ModifiableURLClassLoader extends URLClassLoader {
         }
     }
 
+    private static void tryRegisterAsParallelCapable() {
+        try {
+            ClassLoader.class.getMethod( "registerAsParallelCapable" ).invoke( null );
+        }
+        catch ( NoSuchMethodException e ) {
+            return; // ignore
+        }
+        catch ( SecurityException e ) {
+            return; // ignore
+        }
+        catch ( IllegalAccessException e ) {
+            return; // ignore
+        }
+        catch ( IllegalArgumentException e ) {
+            return; // ignore
+        }
+        catch ( InvocationTargetException e ) {
+            return; // ignore
+        }
+    }
+
     private static final class FilteringParentClassLoader extends ClassLoader {
         @Override
         protected Class<?> loadClass(String name, boolean resolve) throws ClassNotFoundException {