Initial Setup

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

-Xms64m
-Xmx1024m
-XX:MaxPermSize=400m
-ea

How To Configure Your IDE

Setup Code Style And Format For OpenMRS

All images and settings shown in the following sections were taken on IntelliJ version: IDEA 2016.3.4

If you update the documentation please update the IntelliJ version as well!

Java Code Format

In order for IntelliJ to format the code you need to import the OpenMRSFormatter.xml

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

Click on the "Manage..." button next to the "Scheme" drop-down at the top and select "Import..." in the pop-up window

Since the OpenMRSFormatter.xml is created using Eclipse select "Eclipse XML Profile"

Navigate to and select the tools/src/main/resources/eclipse/OpenMRSFormatter.xml and click "Open".

Import the formatter then in an own IntelliJ scheme and call it for example "OpenMRS Formatter"

Ensure the scheme you just created is selected in the "Scheme" dropdown

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

The maximum line length we choose for XML is equal to the one we set for Java files. For Java this is ensured by the Checkstyle - LineLength so please update this number here if the openmrs-core/checkstyle.xml setting changes.

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:

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.