Introduction

The source code is available on GitHub and is licensed under the Apache-2.0 license.

The Java/Groovy BootHub template allows you to create Java and/or Groovy project skeletons with feature-rich Gradle build files.

Features:

  • single or multi-module project

  • versioning

  • license header check

  • support for Eclipse and IntelliJ Idea

  • testing with JUnit 4, JUnit 5, or Spock

  • automatic build and test via Travis CI

  • support for AsciiDoc documentation

  • automatic publishing of versioned AsciiDoc and javadoc documentation to GitHub Project Pages

  • static code analysis with FindBugs

  • code coverage with Clover

  • jar signing

  • jar publishing to JCenter and Maven Central

Getting Started

You can generate a project skeleton based on the Java/Groovy template by using the BootHub GUI or the BootHub CLI.

After providing the template-independent data, you need to configure the Maven groupId of your project:


Maven groupId: org.myproject


After deciding whether you want a single-module or a multi-module project, you need to configure the artifacts and packages and you are also allowed to specify a main class for your project.

The example below illustrates the configuration of a single-module project:


Is this a multi-module project? (Y/N): n
Artifact ID [my-project]:
Base package [org.myproject]:
Do you want to designate a main application class for your project? (Y/N): y
Application main class name [MyProjectMain]:


In case of a multi-module project, you need to configure each module and specify the module interdependencies, as shown in the example below:


Is this a multi-module project? (Y/N): y
Module name / Artifact ID: myproject-core
Base package [org.myproject.core]:
More modules? (Y/N): y
Module name / Artifact ID: myproject-api
Base package [org.myproject.api]:
More modules? (Y/N): y
Module name / Artifact ID: myproject-demo
Base package [org.myproject.demo]:
More modules? (Y/N): n
Module interdependencies
Modules on which myproject-core depends:
  1: myproject-api
  2: myproject-demo
Enter your choices as comma-separated values: 1
Modules on which myproject-api depends:
  1: myproject-demo
Enter your choices as comma-separated values:
Modules on which myproject-demo depends:
  1: myproject-core
  2: myproject-api
Enter your choices as comma-separated values: 1,2
Do you want to designate a main application class for your project? (Y/N): y
Module containing the main class:
  1: myproject-core
  2: myproject-api
  3: myproject-demo
Enter your choice: 3
Application main class name [MyProjectMain]: MyDemo


The next step is to provide information about the project developers:


Developers
Developer ID [jsmith]:
Developer name [John Smith]:
Developer email (optional):
More developers? (Y/N) [N]:


You can choose to generate a Java project, a Groovy project, or a project that uses both Java and Groovy:


Language:
* 1: only Java
  2: only Groovy
  3: Java and Groovy
Enter your choice:


The template lets you select the test framework to be used. You can choose between JUnit, Spock or a combination of these two.


Test Framework:
  1: JUnit 4
  2: JUnit 5
* 3: Spock
Enter your choice:


Then you choose whether the generated Gradle script should add support for uploading artifacts to Bintray:


Add support for uploading to Bintray? (Y/N) [Y]:

You can also specify whether your project needs support for documentation:


Publish documentation to GitHub Pages? (Y/N) [Y]:
Custom domain name for GitHub Pages site (optional)
                        (Example: my-project.mydomain.org):
Use AsciiDoc? (Y/N) [Y]:

The template can instruct Travis to automatically publish your documentation to GitHub Pages by executing a Gradle task created for this job.

By default, the GitHub Pages site will be accessible at the standard URL for Project Pages (which has the form https://<username>.github.io/<projectname>), but you can specify a custom domain for your GitHub Pages site. See the Automatic documentation publishing section for more details.

If you choose to use AsciiDoc, the template will generate a documentation skeleton tailored to your project.

Finally, you can specify if the generated Gradle script should include additional tasks such as checking the presence of license headers, performing static code analysis with FindBugs or code coverage with Clover:


Check license header? (Y/N) [Y]:
Use Findbugs? (Y/N) [Y]:
Use Clover? (Y/N) [Y]:


User Guide

Build

After generating the project skeleton and creating a working copy on your computer, you can build the project with:

gradlew build

Let us consider that your project is called my-project and consists of three modules: myproject-core, myproject-api and myproject-demo. Also, let us consider that you specified that the project should have a main application class named MyDemo in the myproject-demo module.

Then, you can build an uncompressed distribution by executing:

gradlew installDist

Running the start script found in the myproject-demo/build/install/myProject/bin directory, the following text should appear on your terminal:

Hello from MyDemo!

IntelliJ Idea

  • start the IntelliJ Idea IDE

  • if your project uses Groovy or Spock: make sure that the Groovy plugin is enabled

  • open build.gradle

Eclipse

  • start the Eclipse IDE

  • if your project uses Groovy or Spock: install the Groovy plugin

  • install a recent version of Buildship

  • import the project using the Gradle Project wizard

Versioning

The file gradle.properties contains variables that are used to create a version string conforming to the semantic versioning standard. The names of these variables are prefixed by the camelCase representation of the project name, for example: myProjectVersionMajor, myProjectVersionMinor, myProjectVersionPatch.

Additionally, a boolean variable (named for example myProjectReleaseBuild) is used to specify whether the current build represents a release or a snapshot.

By editing the values of these variables you can change the version of your project.

For example, to bump your project version to 1.2.3-SNAPSHOT, your gradle.properties should contain:

myProjectVersionMajor = 1
myProjectVersionMinor = 2
myProjectVersionPatch = 3
myProjectReleaseBuild = false

Travis CI

If your project is on GitHub, you will benefit from the Travis configuration and script files generated by BootHub. Besides building the project and running the tests, Travis also executes the tasks responsible for publishing the documentation (AsciiDoc und javadoc/groovydoc) and for managing the list of release-specific links.

In order to allow Travis to take care of your project you need to perform a few actions. Some of the steps described below are one-time operations that may be skipped if they have already been executed.

  1. authorize Travis as OAuth application for your GitHub account (if not already authorized):

    • open https://github.com/marketplace/travis-ci

    • click 'Set up a free trial'

    • in the 'Pricing and Setup' section select 'Open Source'

    • click 'Install it for free'

    • click 'Complete order and begin installation'

    • click 'Authorize travis-ci'

  2. create the publishGhPages Personal Access Token on Github (if not already created):

    • go to https://github.com/settings/tokens/new to generate the new token (click here for more details)

      • enter publishGhPages as token description

      • select public_repo as scope (or repo if your repository is private)

      • click Generate token

    • save the generated token for future use in a secure place (you will not be able to see it again!)

  3. activate Travis for your project

    • copy the publishGhPages token to clipboard

    • open https://travis-ci.org

    • go to your Travis profile page (https://travis-ci.org/profile/<your-github-username>)

    • find your project in the repository list and activate it (click Sync account and press F5 if your project does not appear in the list)

    • go to the Travis Settings page of your project (https://travis-ci.org/<your-github-username>/<your-github-repo>/settings)

    • under Environment Variables add a variable named GH_PAGES_ACCESS_TOKEN with the token value you copied to the clipboard.

      • make sure that 'Display value in build log' is OFF

      • click ADD.

Travis is now ready to build your project. To trigger a new build you need to make a change to your project and push it to GitHub.

Automatic documentation publishing

If Travis is enabled for your GitHub project, it publishes the AsciiDoc and javadoc/groovydoc to GitHub Project Pages.

It also publishes and updates the list of release-specific links:

release list

The README.md file generated by BootHub contains links to the AsciiDoc and javadoc/groovydoc of the latest release, as well as a link to the list of release-specific links:

readme
The links in the README.md file shown above become valid only after Travis has completed its first build.

Custom domain name

If you have specified a custom domain name for the GitHub Pages site during the project generation, BootHub has created a CNAME file in the ghpages directory. This CNAME file, which contains the custom domain name, will be pushed to the gh-pages branch of your GitHub project when Travis builds your project for the first time. (If you have not specified a custom domain name during the project generation, you can also add a custom domain later.)

To access your GitHub Pages site using a custom domain you need to set up the custom domain with your DNS provider, as described in the last of the step of this document.

AsciiDoc

The template generates in the doc directory a documentation skeleton tailored to your project. The information already available in this generated documentation include:

  • the author of the documentation (by default, the first person in the developer list)

  • the location of the source code on GitHub

  • the location of the javadoc/groovydoc

  • project licensing information (including a link to the license file)

  • java version requirements

  • info about the artifacts of this project and how other projects can use them via Maven or Gradle

  • info for developers:

    • how to build the project

    • how to configure the project in Eclipse or IntelliJ Idea

    • how to configure the credentials needed to publish artifacts to Bintray

License header check

If you enabled the license header check, your source files must include the header provided in the license-header.txt file.

See the license-gradle-plugin for more details.

Findbugs

If you enabled FindBugs, the gradle script will use the FindBugs plugin to perform quality checks during the build.

In the file findbugsExclude.xml you can configure which issues to exclude from being reported.

Testing

During the build, the gradle script executes your JUnit and Spock tests.

You can find the test reports in the build/reports/test directory.

Spock test reports are also available in the build/spock-reports directory.

Code coverage

The gradle script uses the Clover plugin to generate a code coverage report.

After executing:

gradlew cloverGenerateReport

you will find the code coverage reports in the build/reports/clover directory.

Publishing to JCenter and Maven Central

The Gradle task bintrayUpload lets you publish your artifacts to Bintray. You can then include your packages in JCenter and synchronize them with Maven Central.

Before being able to execute the bintrayUpload task, you need to configure your credentials.

Credentials

Your Gradle build script uses the gradle-properties-plugin, which allows you to configure additional project properties in the gradle-local.properties file.

This is the file in which you should configure your credentials. Since gradle-local.properties is already listed in your project’s .gitignore file, your credentials will not be committed to git.

To create this file you can simply copy the provided template file gradle-local-template.properties to gradle-local.properties. The content of this file is shown below:

signingKeyId = A0B1C2D3
signingSecretKeyRingFile = C:/dev/gpg/jsmith.gpg

bintrayUser = jsmith
bintrayKey = a0b1c2d3e4f5a0b1c2d3e4f5a0b1c2d3e4f5a0b1

You need to configure the appropriate values for the above properties, which are used for signing your artifacts and for granting you access to Bintray.

The signing credentials consist of:

  • the public key ID (an 8 character hexadecimal string)

  • the absolute path to the secret key ring file containing your private key

  • the passphrase used to protect your private key

The passphrase of your private key is a very sesnsitive information, therefore it is not stored in the gradle-local.properties. Instead, Gradle will ask you to enter it each time you execute the bintrayUpload task.

See the GnuPG documentation and the Gradle signing plugin for details on how to create and configure your signatures.

The Bintray credentials consist of your Bintray user name and your Bintray API Key. See the documentation of the gradle-bintray-plugin for more details.

Developer Guide

This section is for developers who want to fix bugs or change the functionality of the Java/Groovy template.

Read about writing BootHub templates before starting to change the Java/Groovy template.

The Java/Groovy template comes with a suite of tests that generate skeletons with various flag combinations and check their validity. You should update these tests and add new ones according to the changes you make.

Command Line Build

The Java/Groovy template is built with Gradle and requires JDK 8 or higher. Clone the GitHub repository, cd into the top directory and start the build:

git clone https://github.com/boothub-org/boothub-template-java-groovy.git
cd boothub-template-java-groovy
./gradlew clean build            (On Windows: gradlew clean build)

IntelliJ Idea

  • start the IntelliJ Idea IDE

  • make sure that the Groovy plugin is enabled

  • open build.gradle

Eclipse

  • start the Eclipse IDE

  • install the Groovy plugin

  • install a recent version of Buildship

  • import the project using the Gradle Project wizard