Semantic Version Library

Semantic Version Library is a lightweight library written in Java for semantic versioning management. Java 17+.

It supports stable and prerelease versions (pre-alpha, alpha, beta, release candidate), version comparisons, and optional automatic version checking from a remote URL.

Features

• Fully supports Semantic Versioning: major.minor.patch
• Supports prerelease labels:
  • Pre-Alpha (-pre-alpha, -pre_alpha, -prealpha)
  • Alpha (-alpha)
  • Beta (-beta)
  • Release Candidate (-rc)
  • Stable (Stable is empty)
• Optional prerelease numbers, e.g., 1.2.0-beta.2
• Version comparison between any two SemanticVersion objects
• Automatic online version checking from a specified URL

Installation

Gradle

Add the library to your project manually or via Gradle/Maven by including it as a dependency.

dependencies {
    implementation 'io.github.thomasdarkson:semantic-ver-lib:1.0.0-beta.1'
}

Maven

<dependency>
  <groupId>io.github.thomasdarkson</groupId>
  <artifactId>semantic-ver-lib</artifactId>
  <version>1.0.0-beta.1</version>
</dependency>

Setup

Before using this library, call initialize from semantic.ver.lib.SemanticVerLib class.

public static void main(String[] args) {
	semantic.ver.lib.SemanticVerLib.initialize();
}

Creating a SemanticVersion

A SemanticVersion can be created by 3 methods; stable, prerelease or parse. Only 3 arguments (except parse) is mandatory to use this library but it's recommended to provide all arguments there are.

stable

Arguments:

• Major version number
• Minor version number
• Patch version number
• Remote URL (optional)

Creates a new stable version without a prerelease label. You can provide a remote URL to check for new versions; can be null if version checking is not needed.

import semantic.ver.lib.SemanticVersion;

SemanticVersion version = SemanticVersion.stable(6, 1, 8, null);
System.out.println(version.toString()); // 6.1.8

prerelease

Arguments:

• Major version number
• Minor version number
• Patch version number
• Prerelease Label (optional, defaults to PrereleaseLabels.STABLE)
• Prerelease Number (optional, defaults to OptionalInt.Empty)
• Remote URL (optional)

Creates a prerelease version. You can provide a remote URL to check for new versions; can be null if version checking is not needed.

import semantic.ver.lib.SemanticVersion;

SemanticVersion version = SemanticVersion.prerelease(1, 0, 3, PrereleaseLabels.RELEASE_CANDIDATE, OptionalInt.of(2), null);
System.out.println(version.toString()); // 1.0.3-rc.2

Creates a new version with a prerelease label and number.

parse

Argument:

• Semantic version as string

import semantic.ver.lib.SemanticVersion;

SemanticVersion version = SemanticVersion.parse("2.0.6-alpha.11");
System.out.println(version.preReleaseLabel.toString()); // "alpha"
System.out.println("" + version.preReleaseNumber.getAsInt()); // "11"

Comparing to Versions

You can use compareTo to compare two versions together.

Returns -1, zero, or 1 as this version is less than, equal to, or greater than the specified version. Returns -2 if either version is invalid or null.

SemanticVersion version = SemanticVersion.parse("2.0.6");
SemanticVersion version2 = SemanticVersion.parse("2.0.5");

System.out.println("" + version.compareTo(version2)); // 1 
System.out.println("" + version2.compareTo(version)); // -1 
System.out.println("" + version.compareTo(version)); // 0 

This method also compares prerelease labels and prerelease numbers.

SemanticVersion version = SemanticVersion.parse("2.0.5-beta");
SemanticVersion version2 = SemanticVersion.parse("2.0.5-alpha");

System.out.println("" + version.compareTo(version2)); // 1 

SemanticVersion version = SemanticVersion.parse("2.0.5-alpha.2");
SemanticVersion version2 = SemanticVersion.parse("2.0.5-alpha.1");

System.out.println("" + version.compareTo(version2)); // 1 

There also exists a isNewer function if you don't want to use compareTo.

SemanticVersion version = SemanticVersion.parse("2.0.5-alpha.1");
SemanticVersion version2 = SemanticVersion.parse("2.0.5-alpha");

System.out.println("" + SemanticVersion.isNewer(version, version2)); // true

Checking For Updates

Semantic Version Library can check for updates from a remote URL. The version should be provided in a simple text file, with the version as the only content.

You can check for updates in 3 ways, checkForUpdates(async, consumer), checkForUpdates(consumer), checkForUpdatesEvery(consumer).

checkForUpdates(async, consumer)

This method initiates asynchronously or synchronously based on the async argument. The callback consumer is executed after the check is completed. The consumer receives the Version object that called this method.

String url = "https://raw.githubusercontent.com/ThomasDarkson/RepoThatDefinitelyExists/refs/heads/main/version.txt"; // 2.0.0-rc.12
SemanticVersion v = SemanticVersion.stable(1, 8, 8, url);
v.checkForUpdates(true, null); // Runs asynchronously
v.checkForUpdates(false, null); // Runs synchronously

checkForUpdates(consumer)

This is just a convenience wrapper for checkForUpdates(false, consumer).

checkForUpdatesEvery(seconds, consumer)

This method periodically checks for updates at a fixed rate. The argument seconds is the time in seconds between the start of each update check. The value must be higher than or equal to 3.

String url = "https://raw.githubusercontent.com/ThomasDarkson/RepoThatDefinitelyExists/refs/heads/main/version.txt"; // 2.0.0-rc.12
SemanticVersion v = SemanticVersion.stable(1, 8, 8, url);
v.checkForUpdatesEvery(10, (ver) -> {
	System.out.println("This is executed every 5 seconds until it's stopped");
});

To stop this periodic check, you can call stop().

v.stop(); // Stops the periodic check (if there is one)

Obtaining the Update as a SemanticVersion object

If an update is found for a SemanticVersion object, you can obtain the update as a SemanticVersion object with newVersionAvailable(). This method has no arguments and will return INVALID if there is no update available.

String url = "https://raw.githubusercontent.com/ThomasDarkson/RepoThatDefinitelyExists/refs/heads/main/version.txt"; // 2.0.0-rc.12
SemanticVersion v = SemanticVersion.stable(1, 0, 3, url);
v.checkForUpdates(false, null);
System.out.println(v.newVersionAvailable().toString()); // 2.0.0-rc.12

License and Contributing

Semantic Version Library is licensed under the Apache License 2.0.

You're more than welcome to contribute to this project with pull requests. If you want a feature added, you can create an issue or pull request and I'll review it.