This guide is simple way how to start cooperate on project using Eclipse environment.
Unless you really plan to modify the midPoint source code you probably do not need Eclipse or any other heavyweight development environment. MidPoint can be easily built from the command line without an IDE. Please see the midPoint Development Snapshot page for the details.
This page may be slightly out of date. If you have any tips or suggestions please do not hesitate to contact us. We will be happy to update the page.
Eclipse mostly works for midPoint development. It is good for development of the "backend" parts of midPoint. But it is quite bad for GUI development. If you plan to participate in GUI development you should seriously consider using IntelliJ IDEA instead of eclipse.
Although Eclipse mostly works it does not work as an fully integrated IDE. If you choose Eclipse then prepare yourself that the easiest way how to do a lot of things in Eclipse is to use command-line tools. We have also not found a way how to import and develop midPoint in eclipse without any errors. Eclipse always complaints about some problems. However if it is set up correctly Eclipse should not report any fake errors in the source code.
There are two alternative for Java environment. You can choose either one. Both are supported.
OpenJDK is an open source Java development kit. It is currently the preferred JDK for running and developing midPoint. The preferred way is to use the packaging mechanism of your operating system to get OpenJDK 8. E.g. on Ubuntu Linux use the following:
- Download java JDK from oracle.com http://www.oracle.com/technetwork/java/javase/downloads/index.html
- Select JDK 8
- Accept license
- select package for your platform
- Continue installation for this platform
- Download Eclipse from eclipse.org http://www.eclipse.org/downloads/
- We prefer Eclipse IDE for Java EE Developers (Kepler, Juno or newer)
- Download it for your platform and install
Checkout MidPoint Sources
You can either use Eclipse or other Git tool (command-line).
Recommendation: Define short paths to the project without spaces and special characters if possible.
If you use the master branch which is present in our git repository please bear in mind that the project which is present is a work in progress and sometimes there could be failing tests or the build could be broken etc.
Checkout MidPoint Sources Using Eclipse
Please note that this method may not work that well. If it does not then use command-line method below.
- Click File -> Import ...
- Select Git -> Projects from Git
- Select Clone URI
- Create new repository location
- Url: https://github.com/Evolveum/midpoint.git
master(or any appropriate branch/tag if you know what you are doing)
- Click Next and Next, accept the defaults
- Select -> Check out as a project in the workspace (you can name the project e.g.
midpoint) <--- TODO: FIX THIS
- Click Finish
- Wait for checkout
Checkout MidPoint Sources Using Command-line
Just use this:
See also Git page for more options.
Import midPoint project to Eclipse
- If you have checked out the code using Eclipse: <--- TODO: FIX THIS
- Right Click on project explorer to -> master (midpoint master)
- Select Import, choose existing maven project
- If you have checked out the code using command-line
- Go to File -> Import
- Expand Maven and select Existing Maven Project, click Next
- Choose the directory into which the code was checked out as a Root Directory
- Make sure that relevant midPoint projects are selected. Which usually means all the projects.
- Click Next
- You may get warning about some errors. This should be limited to the "gitdescribe" maven plugin in recent eclipse versions. Older versions may have more errors. These are usually harmless. Make sure there is "Resolve later" action for all such errors (but in fact we haven't found a way how to resolve all the problems, you just need to live with them).
- Click Finish and confirm to ignore the errors.
- Eclipse will work for a while to import the projects
- Add JAXB generated classes to Eclipse's classpath. MidPoint build process is generating part of the source code from XSD schemas. This needs to be added as source folder so eclipse can see it. (Eclipse 4.4 Luna seems to do this automatically. If you have Luna this step can be skipped). Do the following:
- Build the project
- Do a refresh on the schema project.
- Expand the project, then expand "target" folder, "generated" folder inside it and right click on "cxf" folder. Choose Build Path -> Add as Source Folder from the menu.
- (or right click on project schema -> choose Properties -> Java Build Path configuration screen -> select tab Source -> click Add Folder button -> select directory target/generated/cxf and click OK)
You can build the project directly from Eclipse. But we have found that this is sometimes not a very reliable way. It is much more reliable to use a command-line option.
Build the project (Eclipse)
Please note that this may not work properly. Eclipse-maven integration is not really the best one. Some prefer to fight Eclipse during build, other prefer to use command-line (see below).
- Expand project
midpointand right click on pom.xml -> Run As -> Maven install. This will build and test the system and it may take approx. 5 minutes.
- Please make sure that you use JDK as your JRE in Eclipse. Otherwise, the build will fail with a message similar to this: "Failed to execute goal org.codehaus.mojo:aspectj-maven-plugin:1.4:compile (default) on project parent: Execution default of goal org.codehaus.mojo:aspectj-maven-plugin:1.4:compile failed: Plugin org.codehaus.mojo:aspectj-maven-plugin:1.4 or one of its dependencies could not be resolved: Could not find artifact com.sun:tools:jar:1.4.2 at specified path C:\Program Files\Java\jre6/../lib/tools.jar"
Build the project (Command-line)
Go to the directory that holds the source code and use Maven:
The former version will build all the projects and run all the tests. This may take more than 50minutes as we have a lot of tests. The later version skips the tests and takes approx. 4 minutes.
Other Setup and Tips
- It is a good idea to turn off autobuild (Project -> Build automatically) and to build midPoint manually (using Ctrl-B from eclipse or using a command-line)
- If it looks like eclipse is doing something strange try to refresh the code (File -> Refresh or F5). It is good to do this often. The refresh on top-level project (project "midpoint") should theoretically refresh everything. But the practice may be slightly different.
- You may need to close the
dummy-connector-fakeprojects to be able to correctly run debugger and tests from eclipse. You may also need to close the
schemaproject as well (in some versions).
- It may be easier to run unit tests from command-line by switching to the appropriate component directory and running
mvn clean testor
mvn clean test -Dtest=TestClassName.
Setup the Styles and Templates
This is only necessary if you plan to modify midPoint code and submit it back to midPoint development team. This avoid phantom changes in source code and keeps the project nice, unified and readable.
- Locate formatter-profile-midpoint.xml and codetemplates.xml files in config/eclipse/ directory of the source code
- Click Window -> Preferences
- Setup code formatter
Formatterto the filter input field (select Java -> Code Style -> Formatter)
- Click Import
- Choose formatter-profile-midpoint.xml from your local machine
- Click OK
- Setup code template
templateto the filter input field (select Java -> Code Style -> Code Templates)
- Click Import
- Choose codetemplates.xml from your local machine
- Click OK
Advanced Eclipse configuration for midPoint development
Prerequisites: All projects are imported and built by Eclipse, however there are build errors reported. There already exists Tomcat Server definition
- Add midPoint and prism XML catalogs. When the catalogs are added then Eclipse will not try to download the XSD schemas and will even know parts of the schema in XML editors. Open perferences (Window -> Preferences) and go to XML -> XML Catalog. Click Add and select Next Catalog. Click "Workspace" button and navigate to schema/src/main/resources/META-INF/catalog-runtime.xml. Click OK. Repeat the same thing with prism/src/main/resources/META-INF/catalog.xml.
- Add ICF connectors to webapp deployment assembly configuration: Right click on project admin-gui -> choose Properties -> Find Deployment Assembly configuration screen -> click Add button -> choose folder target/idm/WEB-INF/lib/icf-connectors and click OK (If you cannot see the folder try refreshing the project) -> Update column Deploy Path for icf-connectors definitions to value: WEB-INF/lib/icf-connectors.
- Deploy to Tomcat and midPoint start: In Eclipse main menu select Window -> click Show view and select Servers view -> Right click on Tomcat Server definition and click on Add and Remove menu item -> Move admin-gui project from Available to Configured list -> Click finish button. Right click on Tomcat Server definition and select Start from menu.
- Install TestNG plugin: Help -> Eclipse Marketplace -> Search for "TestNG" and install "TestNG for Eclipse" plugin. Restart Eclipse.
Sometimes Eclipse updates its configuration files and breaks configuration for Deployment assembly definitions, through all the projects. The consequence of that is that mipdoint fails to start and Tomcat log is full of errors (Missing resources and classes). To recover from these type of errors you have to check Deplyment assembly definitions for all projects (Right click on project -> choose Properties -> Find Deployment Assembly configuration screen).
For all projects except admin-gui project definition has to look like:
For admin-gui project definition has look like:
... in the same project find Java Build Path configuration screen and check if Maven Dependencies is checked.
The other type of problem is that Eclipse sometimes updates .classpath files and adds attribute excluding="**" to tags classpath entries. To recover from this error remove all excluding attributes from all .classpath files through all the projects.
There exist jira issues to find a solution for mentioned Eclipse problems: