Download latest version of IntelliJ Community Edition, and install:

Start the wizard, click through the welcome page:

Choose the location to install the IDE:

Adjust any installation options as you prefer:

and the start menu:

and finish up the wizard:

Later on we’ll specify the Apache Isis/ASF code style settings, so for now select I do not want to import settings:

Finally, if you are young and trendy, set the UI theme to Darcula:

In IntelliJ a project can contain multiple modules; these need not be physically located together. (If you are previously an Eclipse user, you can think of it as similar to an Eclipse workspace).

Start off by creating a new project:

We want to create a new Java project:

We therefore need to specify the JDK.

Specify the directory containing the JDK:

Finally allow IntelliJ to create the directory for the new project:

Next we need to configure IntelliJ with ASF/Apache Isis' standard templates and coding conventions. These are bundled as the settings.jar JAR file download from the Isis website).

Import using: File > Import Settings, and specify the directory that you have downloaded the file to:

Select all the (two) categories of settings available in the JAR file:

And then restart:

There are also some other miscellaneous settings that we recommend that you adjust (though these are not critical).

First, specify an up-to-date Maven installation, using File > Settings (or IntelliJ > Preferences if on MacOS):

Still on the Maven settings page, configure as follows:

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

On the auto import page, check the optimize imports on the fly and add unambiguous imports on the fly

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

Recommended are: * Maven Helper plugin

+ Provides better visualization of dependency trees (similar to Eclipse) * AsciiDoctor plugin

+ Useful if you are doing any authoring of documents.

Some others you might like to explore are:

Once you’ve imported your Isis application, we should run it. We do this by creating a Run configuration, using Run > Edit Configurations.

Set up the details as follows:

We specify the Main class to be org.apache.isis.WebServer; this is a wrapper around Jetty. It’s possible to pass program arguments to this (eg to automatically install fixtures), but for now leave this blank.

Also note that Use classpath of module is the webapp module for your app, and that the working directory is $MODULE_DIR$.

Next, and most importantly, configure the DataNucleus enhancer to run for your dom goal. This can be done by defining a Maven goal to run before the app:

The -o flag in the goal means run off-line; this will run faster.

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.

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

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

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).

Integration tests can be run in the same way as unit tests, however the dom module must also have been enhanced.

One approach is to initially run the tests use the right click on the integtests module; the tests will fail because the code won’t have been enhanced, but we can then go and update the run configuration to run the datanucleus enhancer goal (same as when running the application):

You can download 1-page PDFs cheat sheets for IntelliJ’s keyboard shortcuts: * for Windows * for MacOS:https://www.jetbrains.com/idea/docs/IntelliJIDEA_ReferenceCard_Mac.pdf[MacOS]

Probably the most important shortcut on them is for Find Action: - ctrl-shift-A on Windows - cmd-shift-A on MacOS.

This will let you search for any action just by typing its name.

The Tool Windows are the views around the editor (to left, bottom and right). It’s possible to move these around to your preferred locations.

Using these shortcuts you can easily toggle between the tool windows and the editor, without using the mouse. Peachy!

For all of the following, you don’t need to type every letter, typing "ab" will actually search for ".a.*b.".

Navigating around: * find callers of a method (the call hierarchy): ctrl-alt-H * find subclasses or overrides: ctrl-alt-B * find superclasses/interface/declaration: ctrl-B

Viewing the structure (ie outline) of a class * ctrl-F12 will pop-up a dialog showing all members ** hit ctrl-F12 again to also see inherited members

Massively useful is the "Intentions" popup; IntelliJ tries to guess what you might want to do. You can activate this using`alt-enter`, whenever you see a lightbulb/tooltip in the margin of the current line.

Code completion usually happens whenever you type '.'. You can also use ctrl-space to bring these up.

In certain circumstances (eg in methods0) you can also type ctrl-shift-space to get a smart list of methods etc that you might want to call. Can be useful.

Last, when invoking a method, use ctrl-P to see the parameter types.

Loads of good stuff on the Refactor menu; most used are:

If you can’t remember all those shortcuts, just use ctrl-shift-alt-T (might want to rebind that to something else!) and get a context-sensitive list of refactorings available for the currently selected object

When a Maven module is imported, IntelliJ generates its own project files (suffix .ipr), and the application is actually built from that.

Occasionally these don’t keep in sync (even if auto-import of Maven modules has been enabled).

To fix the issue, try: * reimport module * rebuild selected modules/entire project * remove and then re-add the project * restart, invalidating caches * hit StackOverflow (!)

One thing worth knowing; IntelliJ actively scans the filesystem all the time. It’s therefore (almost always) fine to build the app from the Maven command line; IntelliJ will detect the changes and keep in sync. If you want to force that, use File > Synchronize, ctrl-alt-Y.

DataNucleus' enhancer uses the domain object model’s own classpath to reference DataNucleus JARs. So, even though your domain objects are unlikely to depend on DataNucleus, these references must still be present.

See the earlier section on DataNucleus enhancer for details of the contents of the pom.xml. Chances are it is already set up from running the SimpleApp archetype.

Then, tell DataNucleus to use the project classpath:

When the enhancer runs, it will print out to the console:

If running on Windows then the DataNucleus plugin is very likely to hit the Windows path limit.

To fix this, we configure the enhancer to read from the persistence.xml file.

As a prerequisite, first make sure that your domain object model has a persistence.xml file. Then specify the persistence-unit in the project properties:

On occasion it appears that Eclipse can attempt to run two instances of the DataNucleus enhancer. This is probably due to multiple Eclipse builders being defined; we’ve noticed multiple entries in the Eclipse’s Debug view:

At any rate, you’ll know you’ve encountered this error if you see the following in the console:

The best solution is to remove DataNucleus support and then to re-add it:

If you consistently hit problems, then the final recourse is to disable the automatic enhancement and to remember to manually enhance your domain object model before each run.

Not ideal, we know. Please feel free to contribute a better solution :-)