Download and install Eclipse from http://www.eclipse.org/downloads/ we recommend .
OpenMRS Unit Tests
There is one optional Eclipse plugin we recommend to install that allows you to create tests from @should annotations for OpenMRS projects.
Using Help -> Install New Software...
Behavior Test Generator Update Site:http://resources.openmrs.org/eclipse/update/You will also need to clone the OpenMRS core, as this is where some important files are located such as the files required for the OpenMRS formatter.
For testing and development purposes, it is highly recommended that you setup the OpenMRS SDK. Instructions for setting up the OpenMRS SDK can be found here.
How To Configure Your IDE
All images and settings shown in the following sections were taken on Eclipse version: Neon.2 Release 2018-12 (4.610.20)
If you update the documentation please update the Eclipse version as well!
Open the Eclipse preferences under Window → Preferences and enter the search term "formatter", which should show Java -> Code Style -> Formatter→ Code Style → Formatter under the results in the left pane like shown here:
Select "Formatter" click the "Import..." button and navigate and select the tools/src/main/resources/eclipse/OpenMRSFormatter.xml.
Import the OpenMRSFormatter.xml into an own profile and call it for example "OpenMRS Formatter".
Ensure it is selected in the dropdown as shown above so it is the "Active profile".
Once the formatter is selected as the "Active profile" you may select "Apply and Close".
From now on you can let Eclipse format any java class for you with the shortcut
Command+Shift+F on Mac)
Open the Eclipse preferences and under Window → Preferences and enter the search term "organize imports" which should show Java -> Code Style -> Organize Imports under → Code Style → Organize Imports under the results in the left pane like shown here:
Make sure that the sorting order of the import groups you see above (java, javax, org, com) matches. It is the Eclipse default so you might not have to change anything.
Also check the two settings of "Number of (static) imports needed for *" and make sure the number is high enough for Eclipse not to replace your imports with so called "star imports" using * because we do not want these. 99 is the default value for Eclipse and is usually high enough.
Make sure that "Do not create imports for types starting with a lowercase letter" is checked.
Hit "Apply" and then "Ok".
From now on you can let Eclipse format and remove unused imports in any java class for you with the shortcut
Open the Eclipse preferences under Window → Preferences and enter the search term "xml XML editor" which should show XML -> XML Files -> Editor→ XML Files → Editor under the results in the left pane like shown here:
Make sure to set the "Line width" to 125.
Open the Eclipse preferences under Window → Preferences and enter the search term "save actions" which should show Java -> Editor -> Save → Editor → Save Actions under the results in the left pane like shown here:
Enable it and adapt the radio buttons and checkboxes to match the image above.
Ensure that you select
- Perform selection actions on save
- Format source code
- Format edited lines
- Organize imports
- Additional actions
Then click the "Configure..." button and match the following sections:
Nothing should be selected under "Code Organizing".
Nothing should be selected under "Code Style".
Nothing should be selected under "Member Accesses".
Everything should be selected under "Missing Code".
Ensure you select
- Remove unused imports
- Remove unused local variables
- Remove unnecessary casts
Hit the "Ok" button, and then "Apply and Close".
Open the Eclipse preferences under Window → Preferences and enter the search term "print margin" which should show General -> Editors -> Text → Editors → Text Editors under the results in the left pane like shown here
Select "Show Print Margin" and set the margin to the maximum line length thats that is defined in the checkstyle config under LineLength.
Open the Eclipse preferences using Window → Preferences and enter the search term "templates" which should show Java -> Editor -> Templates→ Editor → Templates under the results in the left pane like shown here:
Click on "Import..." and select the tools/src/main/resources/eclipse/templates.xml and enterclick on "Apply and Close".
From now on you can use the templates:
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 and hit
Control+Space (for the context menu) which will show you a list of options like shown belowhere:
select the "OpenMRS Style JUnit 4 Test" and hit enter to get this:
the words you see selected are variables/placeholders, with the darker one being on focus. Enter the method name you want to test and hit TAB to advance to the next variable and type in the should style sentence of what you are testing. Hit TAB again to advance to the method body.
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 and hit
Control+Space (for the context menu) which will show you a list of options like shown below
select the logger template and hit enter. This will add the logger with the necessary imports like so
If you do not like Eclipse to open the pom.xml files in the GUI style window you can disable that by opening the Eclipse preferences and using Window → Preferences and enter the search term "maven" which should show Maven -> User → User Interface under the results in the left pane like shown here:
Make sure the checkbox is checked as shown.
For this to work from within Eclipse you need to enable Maven to download the source code and JavaDocs which you can do by opening the Eclipse preferences using Window → Preferences and entering the search term "maven" as shown here:
Ensure you check
You might need to wait or right click on your Maven project and click on Maven -> Update → Update Project for it to trigger.
Tips on How To Use Your IDE
Import a Project with an Existing Source
- You have an existing Eclipse workspace folder.
- You no longer have projects in Eclipse for the source code in the workspace folder
In order to import an existing project into your current workspace begin by navigating to File → Import...
You will be greeted with an import window with a list of import wizards. Next you will want to navigate to General → Existing Projects into Workspace,
select it and continue with Next as shown here:
Upon selecting Next you will be greeted with a screen similar to the one portrayed here:
From here simply browse for your directory, select all of the wanted projects and select Finish
Debug a Web Application with Eclipse
After you should launch Debug Configurations... using IRun → Debug Configurations...
Once launched you will be greeted with a window. In the left sidebar find the option Remote Java Application and double click to open it as shown here:
Start up tomcat and then debug with this new Remote Java Application and breakpoints within the code will open within Eclipse.
Open the Eclipse preferences using Window → Preferences and enter the search term "clean up" which should show Java -> Code Style -> Clean → Code Style → Clean up under the results in the left pane like shown here
Click 'New...' to create a new profile, in our case we call it 'add override annotations' and you select just what you want to clean up. The options are just like in the save actions settings dialog.
Make sure you only select what you want to change.
Now to clean up all the files in your project you open the Eclipse project explorer and go to the package view, right click and select 'Source' -> → 'Clean Up' as shown below