Package io.smallrye.common.version

Interface VersionScheme

All Superinterfaces:

Comparator<String>

All Known Implementing Classes:

AbstractVersionScheme

public interface VersionScheme
extends Comparator<String>

A versioning scheme, which has distinct sorting, iteration, and canonicalization rules.

Field Summary

Fields

Modifier and Type	Field	Description
static VersionScheme	BASIC	A basic versioning scheme which is roughly compatible with semantic versioning, GNU's scheme, the OpenSSL scheme, the numeric scheme used by Unix-style and ELF dynamic linkers, etc.
static VersionScheme	JPMS	The Java platform module system versioning scheme.
static VersionScheme	MAVEN	The Apache Maven versioning scheme.

Method Summary

Modifier and Type	Method	Description
StringBuilder	appendCanonicalized(StringBuilder target, String original)	Append the canonical representation of this version to the given builder, according to the current version scheme.
default String	canonicalize(String original)	Get the canonical representation of this version, according to the current version scheme.
int	compare(String v1, String v2)	Compare two versions according to this version scheme.
default boolean	equals(String v1, String v2)	Determine if two versions are equal according to this version scheme.
VersionIterator	iterate(String version)	Iterate the canonicalized components of the given version according to the rules of this versioning scheme.
default void	validate(String version)	Validate the syntax of the given version.

Methods inherited from interface java.util.Comparator

equals, reversed, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong

Field Detail

BASIC

static final VersionScheme BASIC

A basic versioning scheme which is roughly compatible with semantic versioning, GNU's scheme, the OpenSSL scheme, the numeric scheme used by Unix-style and ELF dynamic linkers, etc. The syntax of this scheme can be described with this grammar:

version ::= underscore-sequence
          | version "." underscore-sequence

underscore-sequence ::= dash-sequence
                      | underscore-sequence "_" dash-sequence

dash-sequence ::= plus-sequence
                | dash-sequence "-" plus-sequence

plus-sequence ::= parts
                | plus-sequence "+" parts

parts ::= alpha-parts
        | number-parts

alpha-parts ::= letter+
              | alpha-parts number-parts

number-parts ::= digit+
               | number-parts alpha-parts

digit ::= <Unicode digits>

letter ::= <Unicode letters>
    

Digit parts are sorted numerically (with leading zeros stripped). Alpha parts are sorted lexicographically and case-sensitively. Trailing zero segments are trimmed. When comparing two sequences, the shorter sequence is padded with virtual zero parts until the lengths match. When comparing parts, shorter parts come before longer parts and are not zero-padded. Numeric parts sort after alphabetical parts.

This versioning scheme is generalized from Semantic Versioning 2.0 and other similar version schemes.

MAVEN

static final VersionScheme MAVEN

The Apache Maven versioning scheme.

This versioning scheme is a modified superset of semantic versioning which includes special treatment of certain qualifier tokens and a few other quirks. For a more detailed (if somewhat incomplete) description of this scheme, please refer to the Maven documentation.

JPMS

static final VersionScheme JPMS

The Java platform module system versioning scheme. Note that the JPMS allows modules to be loaded with version numbers that do not conform to this scheme's rules!

This versioning scheme is based approximately on semantic versioning but with a few differences.

Method Detail

compare

int compare(String v1,
            String v2)

Compare two versions according to this version scheme.

Specified by:

compare in interface Comparator<String>

Parameters:

v1 - the first version (must not be null)

v2 - the second version (must not be null)

Returns:

-1, 0, or 1 if the first version is less than, equal to, or greater than the second version according to this version scheme

Throws:

VersionSyntaxException - if one or both of the versions have syntactic errors according to this scheme

equals

default boolean equals(String v1,
                       String v2)

Determine if two versions are equal according to this version scheme.

Parameters:

v1 - the first version (must not be null)

v2 - the second version (must not be null)

Returns:

true if the versions are equal, or false otherwise

canonicalize

default String canonicalize(String original)

Get the canonical representation of this version, according to the current version scheme.

Parameters:

original - the possibly non-canonical version (must not be null)

Returns:

the canonical representation of the version (not null)

appendCanonicalized

StringBuilder appendCanonicalized(StringBuilder target,
                                  String original)

Append the canonical representation of this version to the given builder, according to the current version scheme.

Parameters:

target - the string builder to append to (must not be null)

original - the possibly non-canonical version (must not be null)

Returns:

the string builder that was passed in

validate

default void validate(String version)
               throws VersionSyntaxException

Validate the syntax of the given version.

Parameters:

version - the version to validate (must not be null)

Throws:

VersionSyntaxException - if the syntax of the version is invalid according to this version scheme

iterate

VersionIterator iterate(String version)

Iterate the canonicalized components of the given version according to the rules of this versioning scheme.

Parameters:

version - the version to iterate (must not be null)

Returns:

the version iterator (not null)