Skip to main content

Java

FINOS provides support for Java projects by delivering:

  1. The FINOS Parent POM, a Maven POM Module that delivers out-of-the-box features for your FINOS-hosted Java project and saves some Maven configuration hassle
  2. The provisioning, configuration and management of the Maven Central Portal account required to publish your Java project into Maven Central.

The FINOS Parent POM provides:

  1. Plugin configuration for Java sources, Javadocs, Maven Site Plugin, Sonar and Docker
  2. Release deployment in Maven Central using the Maven Release Plugin
  3. Rules to validate Central Repository code requirements
  4. Other integrations for checks and validations

You can also use the FINOS Parent POM as inspiration to enhance your own (parent) POM, or choose other JVM-based build tools, such as Gradle, Ant, Leiningen or others, and inherit/replicate the FINOS Parent POM.

Artifact publishing​

All Java projects hosted by the Foundation are expected to use org.finos.<project slug> as groupId, in order to identify the source of the artifact, and associate it unequivocally to the FINOS project; all released artifacts for incubating and active projects must be hosted on Maven central.

To publish artifacts into Maven Central, you can either use the FINOS Parent POM and inherit its configuration, or copy it from here.

We also strongly suggest to rely on CI/CD actions to execute the deployment, in order to avoid falling into OS or environment-specific challenges; the FINOS Parent POM GitHub Action provides a perfect example, which needs very little changes to adapt to any Maven project.

First step is to make sure that the following tags are NOT included in your pom.xml files:

  1. <distributionManagement>
  2. oss.sonatype.org or s01.oss.sonatype.org
  3. maven-deploy-plugin

Also make sure that:

  1. your GitHub Action generates GPG-signed (use self-signed certificates) artifacts, ready to be deployed
  2. you have properly configured your versioning updates (either using the maven-release-plugin or manually, using the maven-versions-plugin)
  3. your GitHub Action includes configure-java, using the following server-* and gpg-* parameters shown here
  4. the server-id on step d must match with the <publishingServerId> configuration of the central-publishing-maven-plugin in pom.xml; if you're using the FINOS Parent POM, you can override it using the <publish.server.id> property (default is ossrh)

At this point you can request the setup of Maven Central credentials and GPG key for artifact signing to help@finos.org for your (FINOS) Github repository (the provisioning process normally takes 3-4 working days) and trigger the workflow.

If auto publish is enabled (the default configuration for FINOS Parent POM) in the central-publishing-maven-plugin, you should be able to see your new artifact deployed on search.maven.org after roughly 30 minutes, without the need for any further action; otherwise, you'll need to access central.sonatype.com with the project's email and password (needs to be requested to help@finos.org) and trigger the publishing (or drop) of the deployment(s).

Maven Central Badge​

A badge can be added at the top of the project's root-level [README.md] file, using the following Markdown syntax:

[![Maven Central](https://img.shields.io/maven-central/v/org.finos/<project name>.svg?maxAge=2592000)](https://search.maven.org/#artifactdetails%7Corg.finos%7C<project name>%7C2%7Cpom)

Release​

The Maven Release Plugin, configured as part of the FINOS Parent POM, delivers the following features:

  1. Verify that there are no uncommitted changes in the local workspace.
  2. Prompt the user for the desired tag, release and development version names.
  3. Modify and commit release information into the pom.xml file.
  4. Tag the entire project source tree with the new tag name.
  5. Extract file revisions versioned under the new tag name.
  6. Deploy the versioned artifacts to appropriate local and remote repositories.

You can manually run the release process using the following commands:

export GPG_TTY=$(tty)
mvn release:prepare release:perform -Prelease

Note that the artifact publishing process is delivered by the central-publishing-maven-plugin:plugin goal, which is included in the <release.goals> property, see https://github.com/finos/finos-parent-pom/blob/finos-7/pom.xml#L75

Known issues​

If the release command fails with "gpg: signing failed: Inappropriate ioctl for device", run the following command and try again; more info on stackexchange.

export GPG_TTY=$(tty)

You can also override the gpg executable by adding -Dgpg.executable=gpg2 in your CLI or into Maven profiles.

Project Documentation​

Maven allows to generate a documentation website in HTML format and provides different options to publish such content on remote servers; content is composed by:

  1. Javadocs - can be easily generated using the maven-javadoc-plugin, which is already configured to run during the build by the FINOS Parent Pom; the documentation is delivered in HTML format and included in the target/site/apidocs project sub-folder; to invoke the javadoc generation manually, you can invoke mvn javadoc:javadoc.
  2. Reporting - to collect different metrics from Maven build plugins and publish them as part of the docs.
  3. Free content - A free structure of documentation content, which supports different template languages (apt, fml, markdown, xdoc and xhtml)

The FINOS Parent POM provides a configuration that allows to publish such content under the FINOS Project Landscape; to enable it, the build must be invoked using the -Ppublish-site Maven profile. For more info, follow the related Pom documentation.