intellij.md

IntelliJ project setup

For all code in monorepo + hoover.

Local setup instructions using IntelliJ IDEA

These setup instructions are aimed at developing in IntelliJ IDEA, but hopefully should be similar in Eclipse.

1. Create the parent directory where all the repositories, including this one, will be cloned e.g.

   mkdir ~/projects/EMAP

2. Clone repositories.

   This repo is now a monorepo that contains the source code from several pre-existing repos (Emap-Core Emap-Interchange Inform-DB emap-hl7-processor). Hoover is still separate.

   The emap script can be used to set up your repos, including cloning them for the first time, but if you want to do it manually:

   cd ~/projects/EMAP
   git clone https://github.com/SAFEHR-data/emap.git
   git clone https://github.com/SAFEHR-data/hoover.git
   git clone https://github.com/SAFEHR-data/internal_emap_documentation.git

3. Open project in IntelliJ IDEA

   File > New > New Project From existing sources and select this repository directory (e.g. ~/projects/EMAP/emap). When prompted, choose "Create project from existing sources"

   "Unmark All" if prompted to select source files for the project.

4. Add Maven projects as IntelliJ modules

   File > Project Structure > Modules

   Click the plus to import a module and select the following pom.xml files

   • core/pom.xml
   • emap-interchange/pom.xml
   • emap-star/pom.xml - NOT to be confused with emap/emap-star/emap-star/pom.xml (which contains the Hibernate entity definitions, but requires the annotation preprocessor)!
   • hl7-reader/pom.xml
   • waveform-reader/pom.xml
   • ../hoover/pom.xml (optional for running within UCLH, outside this repo)

   If you add one by mistake, you can delete the module

   

5. Allow annotation processing

   Go to File > Settings > and searching for processor

   • Check enable annotation preprocessing
   • Change the production sources directory to classes as below
   • Enable "Run processors in a separate step..." as below

   

6. Reload Maven projects

   In the Maven pane (which should now have appeared on the top right of the IDE), click Reimport all maven projects or Reload

7. Point to correct Java versions

   There are several places in IntelliJ that relate to the java version used. These settings are sometimes correctly set from the maven config but you may want to double check in case of errors. Project Structure | Project Settings | Project (SDK to use and default language level) Project Structure | Project Settings | Modules (per module language levels) Preferences | Build, Execution, Deployment | Compiler | Java Compiler (Project bytecode version and per-module bytecode version) Preferences | Build, Execution, Deployment | Build Tools | Maven | Importing (JDK for importer)

   At the time of writing, all modules use java 17, except for emap-setup which uses python.

8. Add lombok and checkstyle plugins

   Go to File > Settings > search for plugins, search lombok and checkstyle and install them

9. Setup checkstyle

   To allow checkstyle to be run go to File > settings > search for checkstyle

   • Set the version of checkstyle to the latest version
   • Click on the + to add a new checkstyle configuration

   

   • Make a description and select the checkstyle file emap/emap-checker.xml. When done, in the bottom panel of the IntelliJ select the inform rules to make the new configuration active.

Running unit tests

Most repositories include unit tests in <repo-name>/src/test/java. You will probably want to set up a separate run config for each component so you can just run the tests that are relevant.

The following modules can be set up in the same, very simple way:

• core
• hl7-reader
• emap-star

Others require some "fake" services which run in docker containers.

Setting up modules that don't require docker containers to run

Creating a configuration as follows:

• Run > Edit Configurations
• Click on the + at the top left-hand side of the window
• Select Junit from the drop down
  • Set Test kind to All in package
  • Set the package to uk.ac.ucl.rits.inform.datasinks.emapstar. Or set the module to e.g. core and the package to uk.ac.ucl.rits.inform
  • You may also want to set logging level to TRACE for our classes by defining the environmental variable: LOGGING_LEVEL_UK_AC_UCL=TRACE

You can just copy this configuration for the other modules, changing the module name each time.

Compiling and running tests

Go to Run > Run, which should create a window in the bottom pane

Expand here if this gives you a compilation error

This may be fixable like so:

• Go to the maven pane on the right-hand side and run the Lifecycle clean goal for: Emap Star Annotations and Emap Star Database Definition. Then clean and then install on Emap Star Schema

• After this then select the Reload All Maven Projects icon at the top of the same pane as shown below

  

• You may also need to run Generate Sources and Update Folders For All Projects

Tests can also be run individually by clicking the play button on a class within an IDE editor window.

For components which require a docker container to run tests

Don't delete the fakeuds definition because it's needed for emap-in-a-box, and it will be needed if we bring the non-proprietary bits of hoover into this repo.

Troubleshooting

It's common to get an "internal compiler error" when running tests from IntelliJ. This can be intermittent and rather frustrating to debug. Double-checking the settings on this page is recommended, especially re annotation processing. Sometimes it's better to use an older JDK that matches the target language version. In the project settings, make sure that all the language versions are set and/or being detected correctly. You can also try running mvn clean from the command line. To do so, you might need to install maven separately if you were so far only using the version bundled with IntelliJ.