Archetype-modern-starter Quick Guide

In this quick guide, I will introduce an open source tool called archetype-modern-starter. I created this tool for helping the developers to quick start the projects of modern java standalone application.

What is archetype-modern-starter?

Archetype-modern-starter is a maven archetype, which is able to easily generate a modern java project. The generated project can be used as the start point for further java application development following the best practices.

Archetype-modern-starter is under Apache License 2.0. Its source code is available on GitHub. Its artifacts has been deployed to Maven Central Repository.

Why use archetype-modern-starter?

The project generated by archetype-modern-starter does:

• use the following modern technologies:
• java se 8
• apache maven 3.5.x
• log4j 2.11.1
• junit 4.12
• follow the current best practices:
• project management including dependency management supported by maven 3.x
• unit test supported by junit 4.x
• logging supported by log4j 2.x
• maven resource support including the resource directories are ready
• able to build the executable package and all-in-one package

How to use archetype-modern-starter?

Generate a modern java project

Under the command line, type the following command:
    $ mvn archetype:generate -Dfilter=archetype-modern-starter
Alternative command:
    $ mvn archetype:generate -Dfilter=io.github.coder168:

and then follows the given instructions to provide the project information, includes groupId, artifactId, version, package. The archetype will generate a corresponding java maven project under a new sub-directory of your current working directory.

Work with the generated project

Under the generated project root directory:

• pom.xml is an XML file that contains information about the project and configuration details used by Maven to build the project. You can add or update the dependencies here
• README.md is a manual in Markdown format
• source code files put into the sub directory src/main/java/
• main resource files put into the sub directory src/main/resources/
• testing code files put into the sub directory src/test/java/
• test resource files put into the sub directory src/test/resources/
• to run all of unit tests:
$ mvn test

• to run single unit test with specified unit test class full name, or multiple names/patterns(using wildcard):
$ mvn -Dtest=<test class full name, names/patterns> test

• to do a clean compile and then run your application:
$ mvn clean compile exec:java -Dexec.mainClass=<main class full name>

• to do a clean build:
$ mvn clean package

• there will be two packages to be built: an executable standard jar file & the all-in-one executable file with dependencies. If all-in-one package is not needed, just delete or comment out the plugin section of maven-assembly-plugin within pom.xml
• to execute the build:
$ java -jar target/<project-build-name>.jar

• to clean up:
$ mvn clean

Note: under different environment, the formatting of the arguments could be little different in a tricky way, e.g. under MS Windows 10:

• using "Command Prompt" from the system, to do a clean compile run:
$ mvn clean compile exec:java -Dexec.mainClass=com.group.App

• using "PS Terminal" from VS Code, the same command need to be:
$ mvn clean compile exec:java -D"exec.mainClass=com.group.App"

How to work with its latest version?

In some cases, you may work with the latest version of archetype-modern-starter, i.e., the version available on GitHub but not released to maven central repository. This can be caused by various of reasons, such as new bug fixes or you just fork it and add some cool features and etc.

You can easily install the latest version(SNAPSHOT) into your local repository:

• clone the archetype project from the original GitHub or your forked GitHub
• under the local project directory, type the following command to deploy it into your local repository:
$ mvn clean install
• and then, you can work it as normal with choosing the appropriate version (SNAPSHOT version, not the release versions)

Reference

• Source Code of archetype-modern-starter (GitHub)
• Java SE
• Apache Maven
• Markdown format