Initial Setup

Download & install IntelliJ from https://www.jetbrains.com/idea/

• Make sure to use the Git/Subversion and Eclipse plugins provided with IDEA
• Edit {idea_install_dir}/bin/idea.vmoptions
• Suggested JVM startup parameters if you have 3 Gb RAM

How To Configure Your IDE

Setup Code Style And Format For OpenMRS

Java Code Format

 1. Install Eclipse Code Formatter plugin in intelliJ | Go to Files -> Settings -> Plugins | Select Marketplace and search for Eclipse Code Formatter, then install it and restart your IntelliJ. For mac OS  go to IntellijIDEA -> Preferences -> Plugins

2. Get OpenMRS Formatter XML file

3. Go to Files -> Settings -> Other Settings -> Eclipse Code Formatter |  The configuration must look like this

• Turn on the Eclipse Code Formatter
• Import the previously downloaded XML file
• Turn off the option for Optimizing Imports

Keep everything else to default.

4. Apply the changes 

From now on you can let IntelliJ format any java class for you. Read IntelliJ - Reformatting Source Code on ways to do that.

Java Imports

In order for IntelliJ to order the java imports according to the OpenMRS style and remove unused imports do the following:

Open the IntelliJ preferences like you did when you configured the formatter

We are using the the Eclipse defaults which are different from IntelliJ's!

So make sure that you change the "Import Layout" to match the configuration as shown above. You will need to move the "Import static all other imports" to the top followed by a blank line, then "import javax.*", "import java.*" another blank line and then "import all other imports".

Also check the two settings of "Class count to use import with '*'" and "Names count to use static import with '*'" and make sure to set them to a high enough number like for ex. 99. Otherwise IntelliJ will replace your imports with so called "star imports" using * which we do not want.

From now on you can let IntelliJ format and remove unused imports in any java class for you. Read IntelliJ - Optimize Imports.

! Please apply this command to clean up your imports before you create a pull request on Github since the imports are not cleaned up by the maven formatter plugin we use when you run the build command !

XML Code Format

The OpenMRSFormatter.xml only handles the Java formatting (limitation of Eclipse), you therefore need to configure the XML Editor.

Open the IntelliJ preferences and enter the search term "xml" which should show Editor -> Code Style -> XML under the results in the left pane like shown here

Make sure that

• on the "Tabs and Indents" tab "Use tab character" is selected
• on the "Other" tab the "Right margin (columns)" is set to 125 
  

Add OpenMRS Code Templates

To save you some typing and focus on solving problems we put together a few code snippets/templates (called Live Templates in IntelliJ). Once you imported them you can type short keywords and IntelliJ will insert the appropriate template code with some variables for you to adjust the snippet to your use case.

To import the templates copy the tools/src/main/resources/intellij/templates.xml file to the destination given to you in these IntelliJ sharing live templates instructions.

Follow the next section on how to see and use the templates.

See all templates available

After importing the templates restart IntelliJ, open the preferences and enter the search term "templates" which should show Editor -> Live Templates under the results in the left pane like shown here

As you can see the templates are in what IntelliJ calls "template group" named "OpenMRS" so you can easily find and enable/disable the templates if you for example work on other projects.

You can of course also get the exact names of all snippets by executing

cat tools/src/main/resources/intellij/templates.xml | grep "template name"

From now on you can use the templates:

• type in the name of the template (which you can find in the Templates settings as shown above)
• (if the context menu does not show hit Control+Space)
• hit TAB to expand the code template (this can be changed in the template settings Options -> Expand with)
• if there are variables in the template you can now override them and advance to the next variable or the end with ENTER

Read the next sections for some examples.

Add a unit test to a test class

To add a new unit test to a test class, open the test class in the editor. Place the cursor to where you want to add the test and write test which will open a context menu

(if the context menu does not show hit Control+Space)

to expand the snippet hit TAB (or the key you configured if you changed the default key to expand with)

the cursor is placed at the snippet variables which are there to adjust the template for your use case. In this template you first enter the name of the method you want to test and hit ENTER to advance to type in the should style sentence of what you are testing. Hit ENTER again to advance to the method body.

Add logging to class

If you want to log an event in a class that does not yet have an instance of a Logger open the class and place the cursor to the top and type logger which will show you a list of options like shown below

(if the context menu does not show hit Control+Space)

hit TAB (or the key you configured if you changed the default key to expand with). This will add the logger with the necessary imports like so

You see the access modifier defaults to private but is selected so you can overrule that if you'd like, by hitting ENTER you accept the default value and

you are ready to log!

Log an event

If your class already has a Logger instance just place the cursor to where you want to log and type logd (for debug), logi (for info), ... hit Control+Space (for the context menu) select the template and hit enter. Depending on what template you are using you might need to only enter your log message or also add a parameter after the message like for example for logpe (for logging an error and passing it an exception) or logpi (to log an info message using the slf4j parametrized message style like log.info("the temperatur was {}", temperatureObject) ).

Import OpenMRS core into IntelliJ

1) Clone the desired module

2) Run "mvn clean install -DskipTests"

3) Import the Project in IntelliJ

4) Import from External Model -> Maven

5) Check "Search for projects recursively"

6) Keep all other options as default

Tips on How To Use Your IDE

Running a JUnit Test

Debugging

Example tomcat5.sh file.