Get the code into your IDE

Even if you just want to study the code, it probably makes a lot of sense to do so in an IDE.

Eclipse

Get and install Eclipse

Download the installer for the latest Eclipse version (currently this is Eclipse 2018-12) from http://www.eclipse.org/.
The installer will give you a choice about which “edition” to install.
“Eclipse IDE for Java Developers” will probably do. We found that at least for us, the “Eclipse IDE for Java EE Develeopers” has too much unneeded overhead.

Install Lombok

We use lombok to reduce boilerplate code.

To enable your local Eclipse to compile the code, please go to https://projectlombok.org/download.html and follow the instructions for Eclipse. You might also want to check out our metasfresh-issue #1125 for further details.

Edit the `eclipse.ini` file

Open the eclipse.ini file in the Eclipse instalation directory and check the -vm value.
This is the java version Eclipse itself will run with. Please make sure that it is a recent version and a that it’s a JDK. Why that?

for example, with java-1.8.0_65, Eclipse is unable to retrieve maven artifacts from our repository (some missing root certificate).
when eclipse runs with a JRE instead of a JDK, the jaxb2-maven-plugin plugin might fail (thank you to stackoverflow and also to this blogpost).
So, unless you have only one java version installed, it is recommended to have the -vm parameter in your eclipse.ini file.
Here is how the respective setion from my own eclipse.ini looks like:

[...]
--launcher.appendVmargs
-vm
C:\Program Files\Java\jdk1.8.0_131\bin\javaw.exe
-vmargs
-Dosgi.requiredJavaVersion=1.8
-Dosgi.instance.area.default=@user.home/eclipse-workspace
[...]

Also, we recomment that you make sure to start eclipse with more than the default 1GB of RAM.
Look for -Xmx1024M within the eclipse.ini file and change it to e.g. -Xmx4096M (the more the better).

Edit your maven settings.xml file

The dependency tree of metasfresh contains a few artifacts that are not part of the default maven repository. Therefore we recommend that you add our public repository to your maven settings.xml file.

Please take a look here for details.

Import the code

Start Eclipse. You will be asked for a workspace location. In my example, I’m using C:\development\repos, because it’s where all my working copies are located.
In order for Eclipse to get all the source folders right, it needs the m2e connector for the build-helper-maven-plugin. To install it, you can go like this:
- Open the “Install New Software…” Dialog:
- Enter the following URL into the “Work with:” field: URL https://repository.sonatype.org/content/repositories/forge-sites/m2e-extras/0.15.0/N/0.15.0.201206251206/
- Now Eclipse should present the connector plugin for instalation:
- Note that you can also auto-discover and install this plugin later, after having imported the code. However at this point, you spend already quite some time for Eclipse trying to build and finding 100000s of compile errors, due to the missing source folders.
Make sure that you java the Java perspective open, not the Java EE perspective.
If you intend to contribute changes, we recommend that you check out the eclipse-config folder in the metasfresh-dev repository.
Now you can import the code by
- switching to the workbench, right-clicking into the Package Explorer (on the left of the Eclipse window) and choosing “Import…”
- selecting “Existing Maven Projects”
- choosing the location of your working copies
- and let Eclipse do the rest
Note that if often happens that an Eclipse project needs to be refreshed from its respective maven pom.xml. This can be done with the shortcut Alt-F5 or via right-click on the project in question, and then:

Start metasfresh from within Eclipse

Starting a client
- The launcher file /metasfresh-dist/metasfresh-dist-swingui.launch starts the sing client,
  When developing, this is often the most practical way to run metasfresh from Eclipse.
  Note that in order to do dev-work the swing client only needs to connect to the DB, but not neccesarily to the app server
Starting the server and client individually:
- Start the back-end/app server: use the launcher file /metasfresh-dist/metasfresh-dist-serverRoot.launch
- Start the webui-api: use the launcher file metasfresh-webui-api/metasfresh-webui-api.launch
  - Note that this start the webui’s rest API. To actually interact with metasfresh using your web-browser, you also need to start the javascript webui-frontend as well. See the respective README.md for further details.
- If you are going to work with material-dispo, the print service, the MSV3-server etc: there are also .launch config files for those
- Start the client: use the launcher file /metasfresh-dist/metasfresh-dist-swingui.launch
  - to connect to the app server (as opposed to just the DB), enter the app-server settings localhost and port 61616 in the swing client’s connection dialog
- there are also an alternative ..._jrebel.launch configs. You can them in case you have the JRebel Eclipse plugin.

Note that until eclipse version neon2 the lombok integration is tricky. The recommended eclipse version is at least neon3, as the lombok integration works out of the box with the lombok gui installer (also across multiple eclipse projects). See here for further infos.

Optional - Install the “Eclipse Mylyn to GitHub connector”

The Eclipse Mylyn to GitHub connector is a plugin that allows you to connect mylyn to the different metasfresh repos and use mylyns features to focus on the particular issue at hand.

The connector can be installed via Eclipse’s “Help -> Install New Software…” Dialog:

developers_getting_started_ide_eclipse_install_mylyn_to_github_connector

With this connector installed, you can add GitHub-based mylyn repositories to your Eclipse instalation.

Other IDEs

We don’t yet have experince with code contributions that were created with Netbeans and are only getting started to gain experience with IntelliJ.

We don’t think there is a need to dictate a particular IDE,

but when contributing, please make sure to text-format your contribution in a way that allows us to get a meaningfull diff. to that end, note that your IDE might be able to import our Eclipse formatting spec.

View source file on GitHub.com