Logos of some services and software we use. Copyright at the corresponding projects.

The only java project template you will ever need!

Java projects have a wide range of configurations and build setups, please show me a full featured hassle setup senpai!

It’s been nearly eight years since I setup my first real java project, it may be seven years since my first maven featured java project and it may be 6 years since my first test coverage featured coffee machine powered block chain driven IOT Industry 4.0 Gradle setup.

Over that time I got to learn several technologies and features from TDD over Multi Module Setups up to CI. Deciding which features you need and to configure them can be a long and annoying process you have to complete before you can write actual Code. In this article I will describe the full setup process of my generic Java Project template I use for most of my Java applications.

The general aspects are concentrated on Open Source via GitHub with integrations for CodeCov.io and Travis-CI. Lay back and enjoy the show.

Components

Here is a short list of our components and how we use it:

Gradle

Build system and general project management and configuration. Link

JUnit 5

Test framework. Link

Mockito

Mocking in our tests. Link

TravisCI

CI and automated builds. Link

JaCoCo

Code Coverage reports. Link

CodeCov

Code Coverage report frontend. Link

Init the project files

We will use Gradle as build system. I really recommend IntelliJ IDEA as IDE as it has superior Gradle integration and can do this step for you. However we will stick to the basic at this time and do this via CLI. You want to have Gradle installed for this step.

First you have to enter your project folder, simple huh? We now use the following command to init our Gradle setup:

gradle init

Thats all! Gradle will setup a wrapper and a settings.gradle and a build.gradle for you.

Open Sourcing my awesome app

The next step is open sourcing your app or at least setting up git for internal version control. In both cases you will need a .gitignore that tells git not to include your meta and build files. In case of IntelliJ and Gradle this .gitignore will look like this:

#####################
### Project files ###
#####################
*.iml
.idea
out

##############
### Gradle ###
##############
.gradle
build

# Never ignore gradle wrapper
!gradle/wrapper/gradle-wrapper.jar

As you can see we will ignore project files (*.iml for IntelliJs project configuration and the .idea folder for the project meta data folder, out for plain old compiler output via IntelliJs artifacts) and the Gradle files (Build & meta again). However we want to enforce that we deliver the gradle wrapper.

Now you can do your initial commit and share your project on GitHub or with your internal Git repository.

Setting up a README.md

To make it easier for other people to understand your project you should create a readme and add a first basic description of your project including your plans, goals and thoughts. Don’t be shy here and add whatever you think could be useful for the world.

Setting up the build system

In case you’re using GitHub I recommend TravisCI. When you’re in a private setup you may want to use GitLab CI or whatever.

First visit the travis website, login and enable build management for your project. Now you have to create a travis.yml file in your project root that tells TravisCI how to build your project. The first simple file could look like this:

######################################
### Configure programming language ###
######################################
language: java

##################################
### Make sure using Oracle JDK ###
##################################
jdk:
  - oraclejdk8

###################################
### Disable Email notifications ###
###################################
notifications:
  email: false

###########################
### Actual Build Script ###
###########################
script:
  - ./gradlew build check

This one will build your java project on the oracle JDK using your gradle wrapper and wont send you emails (Can be really annoying, trust me). You can commit this and watch your first build succeeding, hopefully.

Add Open Source related Guides

When it’s an Open Source project you might want to add some more meta guides to help your community at contributing for your project. In this context a Code of Conduct, a LICENSE and some templates for Issues and Merge requests are useful.

GitHub offers a really nice tool at Project -> Insights -> Community that help you setting up these files.

Configure gradle build

The real fun begins! We will configure the project to use JUnit 5 and Mockito for tests. Your build.gradle should look like this:

We now have a fully working multi module gradle project with JUnit 5 and Mockito ready for work!

Test Coverage Reports

After setting up our test engines we want test coverage reports too! In this case we will use CodeCov.io as a web frontend for serving our reports generated via JaCoCo. But the basic setup in our build.gradle is independent from that:

Add jacoco plugin

We have to add a plugin to gradle. Thats easy.

apply plugin: 'jacoco'

Add Gradle Task

We configure a gradle task that will generate test results based on all sub projects and deploy them in XML and HTML format.

Alter build script

We have to tell Travis that it should execute the codeCoverageReport task and upload the coverage report to codecov. This is also explained at the guides of CodeCov.io.

###########################
### Actual Build Script ###
###########################
script:
  - ./gradlew build check
  - ./gradlew codeCoverageReport

###################################
### Upload Code Coverage Report ###
###################################
after_success:
  - bash <(curl -s https://codecov.io/bash)

Thats all! We now a fully working multi module gradle project with JUnit 5 and Mockito and JaCoCo code coverage reports ready for work!

Add badges

Ever seen something like this:

Build Status. Builds are passing (Dev is currently ahead and master doesn’t have any test results yet)

Thats really easy! In my case this will look like:

Just kidding, you can server the source here and you just have to replace the project URLs.

Building fat jars

In many cases you want to build fat jars that include your dependencies. Gradle is… let’s call it rudimentary here. You will need a foreign plugin:

id 'com.github.johnrengelman.shadow' version '2.0.4'

And now you configure each build.gradle of your projects to use (In case you only want the runtime scoped dependencies, what the mostly the case):

shadowJar {

    configurations = [project.configurations.runtime]
}

Finished! You can now build a fat jar by using “shadowJar” in your Gradle Command.

You can server the full source at https://github.com/FelixKlauke/gradle-project-template and I hope I could help you! Easpecially the setup with Gradle + Multi Module + JUnit 5 + JaCoCo seems to be hard to setup for many many people. You’re free to use my template ❤ I will give the explanation of deployment with nexus in another article. For now you have a working Gradle with JUnit5 and JaCoCo setup featuring code coverage reported and automated builds via TravisCI.

Keep your code clean and your minds calm!