Introduce JMH profile and src/jmh/java configuration to co-locate JMH benchmarks.

Closes #2407

Author: mp911de

CONTRIBUTING.adoc

@@ -138,6 +138,37 @@ Upgrading to 2.7 is *not allowed*.
 ** During the milestone phase of a new release train, upgrade to the latest version of a dependency unless compatibility with a former version is required.
 Upgrades to new major versions are allowed, too, but consider ways to support multiple major versions for one release train to allow a smoother transition.
 
+[[advanced.benchmarks]]
+=== Benchmarks
+
+We use JMH for micro-benchmarks.
+
+Our benchmarks are located in the `src/jmh/java` directory so that we compile these as part of our main build. To run benchmarks during development we leverage JUnit 5 and the https://github.com/mp911de/microbenchmark-runner[Microbenchmark Runner].
+Enable the `jmh` Maven Profile, add `@Testable` to the benchmark you want to run (of the benchmark class) and run it as it was a JUnit test right from your IDE.
+
+NOTE: Microbenchmark Runner is not a tool for running final benchmarks, rather it helps to quickly run benchmarks during development to reduce turnaround time.
+
+Benchmarks aren't ran during the build.
+
+JMH's Benchmark Generator (Annotation Processor) must be enabled in each module with the Maven Compiler, see the following example:
+
+[source,xml]
+----
+<plugin>
+    <groupId>org.apache.maven.plugins</groupId>
+    <artifactId>maven-compiler-plugin</artifactId>
+    <configuration>
+        <annotationProcessorPaths>
+            <path>
+                <groupId>org.openjdk.jmh</groupId>
+                <artifactId>jmh-generator-annprocess</artifactId>
+                <version>${jmh}</version>
+            </path>
+        </annotationProcessorPaths>
+    </configuration>
+</plugin>
+----
+
 [[advanced.change-tracking]]
 === Change tracking
 
@@ -192,7 +223,7 @@ Make sure you keep the original author when amending.
 curl $PULL_REQUEST_URL.patch | git am --ignore-whitespace
 ----
 
-* If the you merge back a feature branch and multiple developers contributed to that, try to rearrange to commits and squash the into a single commit per developer.
+* If you merge back a feature branch and multiple developers contributed to that, try to rearrange to commits and squash the into a single commit per developer.
 Combine the commit messages and edit them to make sense.
 * Before pushing the changes to the remote repository, amend the commit(s) to be pushed and add a reference to the pull request to them.
 This will cause the pull request UI in GitHub show and link those commits.
@@ -201,5 +232,5 @@ This will cause the pull request UI in GitHub show and link those commits.
 ----
 …
 
-Original pull request #??
+Original pull request: #??
 ----

parent/pom.xml

@@ -112,6 +112,7 @@
 		<jacoco>0.8.12</jacoco>
 		<jmolecules>1.9.0</jmolecules>
 		<jmolecules-integration>0.21.0</jmolecules-integration>
+		<jmh>1.37</jmh>
 		<jsonpath>2.6.0</jsonpath>
 		<!-- Deprecated: Use junit-vintage-engine and JUnit 4 is included as transitive dependency -->
 		<junit>4.13.2</junit>
@@ -936,6 +937,24 @@
 			</repositories>
 		</profile>
 
+		<profile>
+			<id>jmh</id>
+			<dependencies>
+				<dependency>
+					<groupId>com.github.mp911de.microbenchmark-runner</groupId>
+					<artifactId>microbenchmark-runner-junit5</artifactId>
+					<version>0.4.0.RELEASE</version>
+					<scope>test</scope>
+				</dependency>
+			</dependencies>
+			<repositories>
+				<repository>
+					<id>jitpack.io</id>
+					<url>https://jitpack.io</url>
+				</repository>
+			</repositories>
+		</profile>
+
 	</profiles>
 
 	<dependencyManagement>
@@ -1025,6 +1044,12 @@
 				<version>${webbeans}</version>
 				<scope>test</scope>
 			</dependency>
+			<dependency>
+				<groupId>org.openjdk.jmh</groupId>
+				<artifactId>jmh-generator-annprocess</artifactId>
+				<scope>test</scope>
+				<version>${jmh}</version>
+			</dependency>
 		</dependencies>
 	</dependencyManagement>
 
@@ -1043,6 +1068,14 @@
 			<scope>test</scope>
 		</dependency>
 
+		<!-- JMH -->
+		<dependency>
+			<groupId>org.openjdk.jmh</groupId>
+			<artifactId>jmh-core</artifactId>
+			<scope>test</scope>
+			<version>${jmh}</version>
+		</dependency>
+
 		<dependency>
 			<groupId>org.mockito</groupId>
 			<artifactId>mockito-core</artifactId>
@@ -1287,6 +1320,19 @@
 							</sourceDirs>
 						</configuration>
 					</execution>
+					<execution>
+						<id>jmh-compile</id>
+						<phase>test-compile</phase>
+						<goals>
+							<goal>test-compile</goal>
+						</goals>
+						<configuration>
+							<sourceDirs>
+								<sourceDir>${project.basedir}/src/jmh/kotlin</sourceDir>
+								<sourceDir>${project.basedir}/src/jmh/java</sourceDir>
+							</sourceDirs>
+						</configuration>
+					</execution>
 				</executions>
 			</plugin>
 
@@ -1377,6 +1423,18 @@
 				<groupId>org.codehaus.mojo</groupId>
 				<artifactId>build-helper-maven-plugin</artifactId>
 				<executions>
+					<execution>
+						<id>add-jmh-source</id>
+						<phase>generate-test-sources</phase>
+						<goals>
+							<goal>add-test-source</goal>
+						</goals>
+						<configuration>
+							<sources>
+								<source>${project.basedir}/src/jmh/java</source>
+							</sources>
+						</configuration>
+					</execution>
 					<execution>
 						<id>add-kotlin-source</id>
 						<phase>prepare-package</phase>

pom.xml

@@ -100,8 +100,6 @@
 						</executions>
 					</plugin>
 
-					<!-- Make sure we build on Java 8 with only release dependencies -->
-
 					<plugin>
 						<groupId>org.apache.maven.plugins</groupId>
 						<artifactId>maven-enforcer-plugin</artifactId>