Warning

This page is now hosted on https://odp.finos.org/docs/development-infrastructure/continuous-integration/java

The Foundation hosts several Java projects already and provides a good level of support for building, testing and releasing Java code.

The most adopted (68% in 2016, according to RebelLabs) build tool for Java is Apache Maven, which provides a standard, modular, convention-based model to build and publish your Java projects; as such, the Foundation provides a Maven Module called Parent POM, containing build configurations that can be easily inherited by the single projects; in provides:

Plugin configuration for the most common Maven functionalities
Nightly-built (in Maven terms, snapshots) deployment into Sonatype OSS public repository (oss.sonatype.org)
Release deployment on the Central Repository
Rules to validate Central Repository code requirements
Other integrations for checks and validations

You can also adopt other Java build tools, such as gradle, ivy, ant or others, assuming that they are able to interact with the Central Repository.

Below are listed some of the most common processes that are involved in a Java project lifecycle and how they interact with the project infrastructure provided by the Foundation.

Build

The build process aims to produce reusable Java binaries (in Maven terms, artifacts) in a reliable and reproducible way, from every contributor or consumer workstation; special build requirements should be documented in the project homepage.

The Maven command to build artifacts is mvn package.

Artifact publishing

All Java projects hosted by the Foundation are expected to use a groupId that is (or prefixed by) org.finos.<program name> and are published on the Central Repository (also known as Maven Central)

In order to publish artifacts (in Maven terms, artifact deployment), it's necessary to setup some accounts and configure the workstation accordingly; please note that these steps are not mandatory for all project teams, but only for those performing artifact deployment and releases (normally the project lead or a team member elected as release manager).

Sign up on https://issues.sonatype.org/ (note that this site uses the same credentials as http://oss.sonatype.org/).
Raise a HELP issue or send an email to help@finos.org, with the GitHub URL of your project, and your Sonatype Jira ID (from step 1)

Locate (or create) and edit the settings.xml file in your local file-system to add a <server> item; using Maven encrypted passwords is strongly advised, to avoid setting up the password in clear text

settings.xml

<settings>
  <servers>
    <server>
      <id>ossrh</id>
      <username>[your-sonatype-jira-id]</username>
      <password>[your-sonatype-jira-pwd]</password>
    </server>
    <server>
      <id>ossrh-distro</id>
      <username>[your-sonatype-jira-id]</username>
      <password>[your-sonatype-jira-pwd]</password>
    </server>
  </servers>
</settings>

At this point, you can proceed with the deployment of the snapshot artifacts, by simply invoking mvn deploy from the project root folder; as a result, artifacts will be publicly available on oss.sonatype.org and usable by anyone as Maven dependencies.

You can find more info on the Central Repository howto page for Maven.

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

Maven Central Badge

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

This will appear as follows and link to the artifact on search.maven.org

If you want to run this process continuously for each commit, you can integrate with Travis CI or other Continuous Integration systems.

Release

The Maven release process performs the following activities:

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

All the configurations documented in the section above (see snapshot deployment) also apply to the release process; additionally, it is required to:

Install gpg on the local workstation where the release process is invoked

Configure settings.xml by adding the following profile

settings.xml for GPG

<settings>
  ...
  <profiles>
    <profile>
      <id>ossrh</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <properties>
        <gpg.executable>gpg2</gpg.executable>
      </properties>
    </profile>
  </profiles>
</settings>

Test a snapshot deployment (see above), to make sure that you can authenticate against Sonatype servers

At this point you can proceed with the release:

export GPG_TTY=$(tty)
Run the maven command mvn release:prepare release:perform -Prelease ; the release profile will provide javadocs, sources and gpg signature configuration for the build; if you're not using ssf-parent-pom, you'd need to configure these plugins by yourself (this pom.xml may be useful)
Promote the staged artifacts by accessing the Nexus staging repositories to:
1. Identify which repository refers to the release process performed on step #1. Look at the description column to identify the specific project (look towards bottom of list).
2. Select the staging repository. To release the request, click the Close (button on top menu) the release request - this operation will trigger a validation of the artifacts to be released
3. Click on the refresh button to update status of repository. Click on Release (button on top menu) to sync artifacts with the Central Repository and remove staging repository.

Upon release, your component will be published to Central: this typically occurs within 10 minutes, though updates to search can take up to two hours. You can also watch this youtube video to know more about the Nexus staging lifecycle.

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)

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:

Javadocs - can be easily generated using the maven-javadoc-plugin, which is already configured to run during the build by the SSF 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
Reporting - to collect different metrics from Maven build plugins and publish them as part of the docs
Free content - A free structure of documentation content, which supports different template languages (apt, fml, markdown, xdoc and xhtml)

The SSF Parent POM provides a configuration that allows to publish such content on the Symphony Program's GitHub Pages; to enable it, the build must be invoked using the -Ppublish-site Maven profile switch. For more info, follow the SSF Parent Pom documentation and check the Symphony Program's symphony-java-sample-bots project.

Browser not supported