Introduction to Flow Logix Maven Parent POM

Dramatically simplifies the development of applications by using the parent POM.
Supports Maven 4 and 3.

Project Overview

The base-pom project is a Maven project that provides a collection of parent POMs designed to streamline the development and build process for Java-based applications. It establishes a consistent foundation by defining common configurations, dependencies, and best practices that can be inherited by other projects.

The project is organized into the following modules: - base-pom: Minimal parent POM that can be used for any project. It is a good starting point for new projects. Produces no warnings with Maven 4. - infra-pom: An opinionated infrastructure POM that includes configurations for testing, code coverage, and dependency management. - payara-pom: A pre-configured environment for running integration tests with Payara Server. - checkstyle: Provides Checkstyle configurations to enforce a consistent code style.

Modules

infra-pom

The infra-pom module is an opinionated infrastructure POM that provides a robust foundation for building and testing Java applications. It includes the following features:

  • Testing: Configures Surefire and Failsafe plugins for unit and integration testing, with support for parallel test execution.

  • Code Coverage: Integrates with JaCoCo to measure and report code coverage.

  • Dependency Management: Manages common dependencies, such as Jakarta EE, Lombok, and Mockito.

  • Release Management: Simplifies the release process with pre-configured profiles for deploying to various repositories.

payara-pom

The payara-pom module provides a pre-configured environment for running integration tests with Payara Server. It offers several profiles to support different testing scenarios:

  • payara-server-local: For running tests against a local Payara Server instance.

  • payara-server-remote: For running tests against a remote Payara Server instance.

  • payara-docker: For running tests in a Docker container.

checkstyle

This module contains the Checkstyle dependencies and configuration files. The module is used automatically by the infra-pom module to enforce a consistent code style across your project.

infra-pom Variables

The infra-pom module defines the following properties:

Variable Description

project.build.outputTimestamp

The timestamp for the project build output.

docs.phase

The Maven phase to generate documentation.

delombok.phase

The Maven phase to run delombok.

snippet.path

The path to the code snippets.

release.profile

The release profile to use.

gpg.keyname

The GPG key name for signing artifacts.

staging.server

The staging server for deployment.

nexus.url

The URL of the Nexus repository.

arquillian.container

The Arquillian container to use for testing.

drone.browser

The browser to use for Drone tests.

jacocoAddress

The address for the JaCoCo agent.

jacocoPort

The port for the JaCoCo agent.

jacocoReset

Whether to reset the JaCoCo agent.

jacoco.classDumpDir

The directory to dump JaCoCo class files.

jdk11SurefireOptions

The Surefire options for JDK 11.

jdk11FailsafeOptions

The Failsafe options for JDK 11.

mockito.agentOptions

The agent options for Mockito.

compiler.show.warnings

Whether to show compiler warnings.

compiler.deprecation.arg

The compiler argument for deprecation warnings.

compiler.unchecked.arg

The compiler argument for unchecked warnings.

compiler.parameters.arg

The compiler argument for parameter names.

compiler.annotation.processing

The annotation processing mode for the compiler.

junit5.parallel.tests.enabled

Whether to enable parallel tests for JUnit 5.

junit5.parallel.tests.mode

The parallel test mode for JUnit 5.

test.parallel

The parallel mode for tests.

it.test.parallel

The parallel mode for integration tests.

shrinkwrap.compile.skip

Whether to skip ShrinkWrap compilation.

shrinkwrap.decryption.ignore

Whether to ignore ShrinkWrap decryption problems.

test.containers.jdk.turnOffSVE

Whether to turn off SVE for Testcontainers JDK.

test.thread.count

The number of threads to use for testing.

test.run.order

The run order for tests.

test.redirect.to.file

Whether to redirect test output to a file.

deploy.at-end

Whether to deploy at the end of the build.

deploy.retry-failed-count

The number of times to retry a failed deployment.

jar.skip-if-empty

Whether to skip creating a JAR file if it is empty.

japicmp.skip

Whether to skip the JAPICMP plugin.

javadoc.doclint

The doclint options for Javadoc.

javadoc.sourcepath

The source path for Javadoc.

javadoc.snippet.path

The snippet path for Javadoc.

javadoc.snippet.path.options

The snippet path options for Javadoc.

checkstyle.configLocation

The location of the Checkstyle configuration file.

checkstyle.headerLocation

The location of the Checkstyle header file.

checkstyle.suppressionsLocation

The location of the Checkstyle suppressions file.

checkstyle.excludes

The files to exclude from Checkstyle.

ear.defaultLibBundleDir

The default directory for library bundles in EAR files.

ear.skinnyWars

Whether to create skinny WAR files in EAR projects.

ear.skipClassPathModification

Whether to skip classpath modification in EAR projects.

jdk.minimum.version

The minimum JDK version required to build the project.

maven.minimum.version

The minimum Maven version required to build the project.

jakarta.ee.version

The version of Jakarta EE to use.

lombok.version

The version of Lombok to use.

lombok.javadoc.version

The version of Lombok Javadoc to use.

shrinkwrap.api.version

The version of ShrinkWrap API to use.

shrinkwrap.resolver.version

The version of ShrinkWrap Resolver to use.

mockito.version

The version of Mockito to use.

payara-pom Variables

The payara-pom module defines the following properties:

Variable Description

payara.start.disable

Whether to disable starting Payara.

payara.start.skip

Whether to skip starting Payara.

payara.version

The version of Payara to use.

root.basedir

The base directory of the root project.

dependencies.output-directory

The output directory for dependencies.

dependencies.markers-directory

The markers directory for dependencies.

payara.imageName

The name of the Payara image to use.

payara.asadmin.executable.suffix

The suffix for the asadmin executable.

payara.asadmin.executable

The path to the asadmin executable.

payara.http.port

The HTTP port for Payara.

payara.https.port

The HTTPS port for Payara.

testcontainers.skip

Whether to skip Testcontainers.

CI/CD

The project provides GitHub Actions for other projects. The workflows are defined in the .github/workflows directory and include the following:

  • dependabot-automerge-self.yml: This workflow automatically approves and merges pull requests created by Dependabot.

  • dependabot-automerge.yml: This reusable workflow performs the actual auto-merge process. This workflow can be reused by other projects in other organizations. It includes steps to:

  • Approve the pull request.

  • Wait for external checks (e.g., Jenkins, Snyk) to complete.

  • Merge the pull request if all checks pass.

Frequently Asked Questions

Q: Is this just for Flow Logix, or can I use it for my own projects?
A: This is a general-purpose parent POM that can be used for any project. It is not specific to Flow Logix. You can override the default settings to suit your project’s name, developers, scm or any other section necessary to customize it for your own project.

Q: How is this different from basepom.org or other base POM projects?
A: This POM is designed to be minimal and flexible, with a focus on aggressively reducing the size of your project’s POM. It does not include unnecessary dependencies or plugins, and it is designed to work with Maven 4. It also includes features that are not available in other base POM projects, such as support for Payara Platform and Testcontainers.

Q: Which one do I choose? infra, payara or base?
A: The base POM is minimal and can be used for any project. The infra POM is opinionated with many features and preconfigured defaults, while the payara POM is for projects that use Payara Platform. If you are not sure which one to use, start with the base POM.

Q: I already have a parent POM, can I use this one?
A: Yes, you can use this POM as a parent POM for your project’s parent POM. Then, you can remove all the dependencies and plugins that you do not need. This POM is designed to be flexible and can be used as a starting point for your own parent POM.

Q: How often is this updated?
A: This POM is updated regularly to keep up with the latest versions of the dependencies and plugins. On averaage, it is updated weekly.

Q: Why are reporting plugins not included?
A: Reporting plugins are not included in the parent POM because they are not needed for every project. Reporting can be done more easily in the CI environments. You can add them to your project’s POM if you need them. The infra POM includes some reporting plugins, but they are not mandatory.

Q: Why not use a BOM instead of defining <dependencyManagement> in the parent POM?
A: It is difficult and error-prone to include multiple BOMs from different projects, especially in maven 4. Maven 4 will generate warnings for conflicting BOMs. First principle of this project is to aggressively minimize the size of your project’s POM. The <dependencyManagement> section in the parent POM is designed to be minimal and only includes the most common and error-prone dependencies. You can add additional BOMs to your project if you need them.

Q: Why is jacoco-maven-plugin configured differently than "normal"?
A: Jacoco is configured to merge both unit tests and integration tests into a single report to get a complete picture of the full code coverage. This includes integration tests done in Application Servers.

Q: Why is the build-helper-maven-plugin defined?
A: It is defined to add the src/demo directory to the source directories. Code in this directory can be used in documentation or as Javadoc snippets. The code is built and tested as part of the project build, but it is not included in the final artifact. This allows you to include example code in your project without affecting the final artifact size or dependencies.