11 Sep 2014: Article was updated for JMH 1.0.
10 May 2014: Original version.
This article will give you an overview of basic rules and abilities of JMH. The second article will give you an overview of JMH profilers.
JMH is a new microbenchmarking framework (first released late-2013). Its distinctive advantage over other frameworks is that it is developed by the same guys in Oracle who implement the JIT. In particular I want to mention Aleksey Shipilev and his brilliant blog. JMH is likely to be in sync with the latest Oracle JRE changes, which makes its results very reliable.
You can find JMH examples here.
JMH has only 2 requirements (everything else are recommendations):
- You need to create a maven project using a command from the JMH official web page
- You need to annotate test methods with
In some cases, it is not convenient to create a new project just for the performance testing purposes. In this situation you can rather easily add JMH into an existing project. You need to make the following steps:
- Ensure your project directory structure is recognizable by Maven (your benchmarks are at src/main/java at least)
Copy 2 JMH maven dependencies and
maven-shade-pluginfrom the JMH archetype. No other plugins mentioned in the archetype are required at the moment of writing (JMH 1.0).
How to run
Run the following maven command to create a template JMH project from an archetype (it may change over the time, check for the latest version near the start of the the official JMH page):
$ mvn archetype:generate \ -DinteractiveMode=false \ -DarchetypeGroupId=org.openjdk.jmh \ -DarchetypeArtifactId=jmh-java-benchmark-archetype \ -DgroupId=org.sample \ -DartifactId=test \ -Dversion=1.0
Alternatively, copy 2 JMH dependencies and
maven-shade-plugin from the JMH archetype (as described above).
Create one (or a few) java files. Annotate some methods in them with
@Benchmark annotation – these would be your performance benchmarks.
You have at least 2 simple options to run your tests::
Follow the procedure from the official JMH page):
$ cd your_project_directory/ $ mvn clean install $ java -jar target/benchmarks.jar
The last command should be entered verbatim – regardless of your project settings you will end up with
Or use the old way: add
After that you can run it with
$ cd your_project_directory/ $ mvn clean install $ java -cp target/benchmarks.jar your.test.ClassName
Now after extensive “how to run it” manual, let’s look at the framework itself.