Using IntelliJ

This section describes how to install and setup JetBrains' IntelliJ IDEA, then how to import an application into IntelliJ and run it.

Installing and Importing

This section covers installation and setup. These notes/screenshots were prepared using IntelliJ IDEA Community Edition 2019.3, but is believed to be compatible with more recent versions/other editions of the IDE.

Download and Install

Download latest version of IntelliJ Community Edition, and install.

Import Project

In IntelliJ a project can contain multiple modules; these need not be physically located together.

Download either the HelloWorld or SimpleApp starter app to your filesystem.

From the welcome screen, select "import project":

010 welcome

Navigate to the top-level pom.xml of the starter app:

020 import pom

Project imported:

030 imported

Start off by creating a new project:

Use File  Project Structure to confirm that JDK 11 is configured:

040 project structure

TODO: this screenshot is out of date; JDK 11 is now the minimum version required.


Compiler Settings

There are a number of compiler settings that influence the compiler. We highly recommend you set these.

On the Compiler Settings page, ensure that build automatically is enabled (and optionally compile independent modules in parallel):

010 build automatically
Figure 1. IntelliJ Compiler Settings

On the Annotation Processors page, confirm that these are enabled for all of the packaging=jar modules (in other words, those that contain Java and have a src/main/java directory):

020 annotation processor
Figure 2. IntelliJ Annotation Processor Settings

If using JDO/DataNucleus, this setting enables the generation of the Q* classes for DataNucleus type-safe queries.

It is also required for frameworks such as Lombok.

Maven Settings

There are also some other settings for Maven that we recommend you adjust (though these are less critical):

On the Maven settings page:

010 maven installation
Figure 3. IntelliJ Maven Settings - Installation

Still on the Maven settings page, configure as follows:

020 maven configuration
Figure 4. IntelliJ Maven Settings - Configuration

Editor Settings

On the Auto Import settings page, check the optimize imports on the fly and add unambiguous imports on the fly

010 auto import
Figure 5. IntelliJ Auto Import Setting

You might also want to exclude certain packages or classes from auto-import, for example:

  • java.awt.*

  • javax.swing.*

  • lombok.experimental.*


You might want to set up some additional plugins. You can do this using File > Settings > Plugins (or equivalently File > Other Settings > Configure Plugins).

Highly recommended are:

  • Lombok plugin (bundled with the IDE)

    If you plan to use Project Lombok to reduce boilerplate.

  • Maven Helper plugin

  • AsciiDoctor plugin

    Extremely useful if you are doing any authoring of documents (plugin’s git repo is here)


Let’s see how to run both the app and the tests.

We run the application by creating a Run configuration, using Run > Edit Configurations.

There is one complication, which is the ORM. If the app uses JPA, then dynamic class weaving should be configured. If the app uses JDO, then Datanucleus enhancer should be configured.

Running the App (JPA)

With JPA, the classes need to be "weaved" in order to support lazy loading and (more performant) dirty object tracking. This is typically done dynamically at runtime, using a Java agent. The SimpleApp and HelloWorld starter apps demonstrate this, bundling the spring-instrument-5.3.5.jar file. To run, use:


as a JVM argument (where the system properties also are located.)

Running the App (JDO)

DataNucleus requires that all entities are bytecode enhanced. When building from the command line using Maven, the datanucleus:enhance Maven plugin takes care of this.

We can just have IntelliJ run the enhance as a separate run configuration before the run configuration that runs the app itself.

First, set up the run configuration to do the enhance:

005 datanucleus enhance run configuration
Figure 6. Run Configuration to enhance the entities
Check "work offline" (on the General tab) to speed this up slightly.

If on Windows you encounter a "The command line is too long" error, then set '-Dfork=false' as a VM option (on the Runner tab).

Then, set up the run configuration for the app. Note how it runs the "enhance" configuration first:

010 run configuration
Figure 7. Run Configuration to run the app

You should now be able to run the app using Run > Run Configuration. The same configuration can also be used to debug the app if you so need.

Dynamic Enhancement ?

Rather than statically enhancing the classes, an alternative — at least in theory — is to enhance the classes dynamically, at runtime.

This plugin (not tested) purports to support this:

Running the Unit Tests

The easiest way to run the unit tests is just to right click on the relevant package in the Project Window, and choose run unit tests. Hopefully your tests will pass (!).

030 running unit tests
Figure 8. Running Unit Tests from Project Explorer

As a side-effect, this will create a run configuration, very similar to the one we manually created for the main app:

040 running unit tests run configuration
Figure 9. Unit Tests Run Configuration

Thereafter, you should run units by selecting this configuration (if you use the right click approach you’ll end up with lots of run configurations, all similar).

Running the Integration Tests

Integration tests can be run in the same way as unit tests.

One approach is to initially run the tests use the right click on the integtests module:

045 running integ tests
Figure 10. Running Integ Tests from Project Explorer

If the app uses JDO, then the tests might fail because the entities won’t have been enhanced. However, we can then easily update the run configuration to run the datanucleus enhancer goal (same as when running the application):

050 running integration tests run configuration
Figure 11. Integration Tests Run Configuration
Make sure that the search for tests radio button is set to In single module. If this radio button is set to one of the other options then you may obtain class loading issues.