Top Description Fields Methods
io.smallrye.common.version

public Interface VersionScheme

extends Comparator<String>
Known Direct Implementers
io.smallrye.common.version.AbstractVersionScheme
Imports
java.util.Comparator, .Objects, java.util.function.Predicate
A versioning scheme, which has distinct sorting, iteration, and canonicalization rules.

Field Summary

Modifier and TypeField and Description
public 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>
public static final VersionScheme
JPMS

The Java platform module system versioning scheme.

public static final VersionScheme
MAVEN

The Apache Maven versioning scheme.

Method Summary

Modifier and TypeMethod and Description
public StringBuilder

Returns:

the string builder that was passed in
appendCanonicalized(StringBuilder
the string builder to append to (must not be null)
target, String
the possibly non-canonical version (must not be null)
original)

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

public default String

Returns:

the canonical representation of the version (not null)
canonicalize(String
the possibly non-canonical version (must not be null)
original)

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

public int

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
compare(String
the first version (must not be null)
v1, String
the second version (must not be null)
v2)

Redeclares java.util.Comparator.compare.

Compare two versions according to this version scheme.

public default boolean

Returns:

true if the versions are equal, or false otherwise
equals(String
the first version (must not be null)
v1, String
the second version (must not be null)
v2)

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

public default Predicate<String>

Returns:

the parsed range (not null)
fromRangeString(String
the range string to parse (must not be null)
range)

Parse a range specification and return it as a predicate.

public default Predicate<String>

Returns:

the parsed range (not null)
fromRangeString(String
the range string to parse (must not be null)
range, int
the start of the range within the string (inclusive)
start, int
the end of the range within the string (exclusive)
end)

Parse a range specification and return it as a predicate.

public default boolean

Returns:

true if the first version is greater than the second version, or false otherwise
ge(String
the base version
base, String
the other version
other)

Determine if the first version is greater than the second version according to this version scheme.

public default boolean

Returns:

true if the first version is greater than or equal to the second version, or false otherwise
gt(String
the base version
base, String
the other version
other)

Determine if the first version is greater than or equal to the second version according to this version scheme.

public VersionIterator

Returns:

the version iterator (not null)
iterate(String
the version to iterate (must not be null)
version)

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

public default boolean

Returns:

true if the first version is less than or equal to the second version, or false otherwise
le(String
the base version
base, String
the other version
other)

Determine if the first version is less than or equal to the second version according to this version scheme.

public default boolean

Returns:

true if the first version is less than the second version, or false otherwise
lt(String
the base version
base, String
the other version
other)

Determine if the first version is less than the second version according to this version scheme.

public default String

Returns:

the greater (later) of the two versions
max(String
the first version (must not be null)
a, String
the second version (must not be null)
b)

Returns the greater (later) of the two versions.

public default String

Returns:

the lesser (earlier) of the two versions
min(String
the first version (must not be null)
a, String
the second version (must not be null)
b)

Returns the lesser (earlier) of the two versions.

private Predicate<String>
parseMinExcl(String range, int start, int end)

private Predicate<String>
parseMinIncl(String range, int start, int end)

private Predicate<String>

Returns:

the predicate
parseMore(Predicate<String>
the predicate to return
predicate, final String
the range string
range, int
the remaining start
start, int
the end
end)

Parse the end context (make sure there is no trailing garbage, combine subsequent predicates).

private Predicate<String>
parseRange(final String range, int start, final int end)

private Predicate<String>
parseRangeMax(Predicate<String> min, String range, int start, int end)

private Predicate<String>
parseSingle(String range, int start, int end)

public default void
validate(String
the version to validate (must not be null)
version)

Validate the syntax of the given version.

public default Predicate<String>

Returns:

true if the first version is equal to the second version, or false otherwise
whenEquals(String
the other version
other)

Returns a predicate that tests if the version is equal to the base version.

public default Predicate<String>

Returns:

a predicate that tests if the version is greater than or equal to the base version
whenGe(String
the other version
other)

Returns a predicate that tests if the version is greater than or equal to the base version.

public default Predicate<String>

Returns:

true if the first version is less than the second version, or false otherwise
whenGt(String
the other version
other)

Returns a predicate that tests if the version is greater than or equal to the base version.

public default Predicate<String>

Returns:

a predicate that tests if the version is less than or equal to the base version
whenLe(String
the other version
other)

Returns a predicate that tests if the version is less than or equal to the base version.

public default Predicate<String>

Returns:

a predicate that tests if the version is less than the base version
whenLt(String
the other version
other)

Returns a predicate that tests if the version is less than the base version.

Inherited from java.util.Comparator:
comparingcomparingcomparingDoublecomparingIntcomparingLongequalsnaturalOrdernullsFirstnullsLastreversedreverseOrderthenComparingthenComparingthenComparingthenComparingDoublethenComparingIntthenComparingLong

Field Detail

BASICback to summary
public 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.

JPMSback to summary
public 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.

MAVENback to summary
public 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.

Method Detail

appendCanonicalizedback to summary
public 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:StringBuilder

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

original:String

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

Returns:StringBuilder

the string builder that was passed in

canonicalizeback to summary
public default String canonicalize(String original)

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

Parameters
original:String

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

Returns:String

the canonical representation of the version (not null)

compareback to summary
public int compare(String v1, String v2)

Redeclares java.util.Comparator.compare.

Compare two versions according to this version scheme.

Parameters
v1:String

the first version (must not be null)

v2:String

the second version (must not be null)

Returns:int

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

Exceptions
VersionSyntaxException:
if one or both of the versions have syntactic errors according to this scheme
equalsback to summary
public default boolean equals(String v1, String v2)

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

Parameters
v1:String

the first version (must not be null)

v2:String

the second version (must not be null)

Returns:boolean

true if the versions are equal, or false otherwise

fromRangeStringback to summary
public default Predicate<String> fromRangeString(String range)

Parse a range specification and return it as a predicate. This method behaves as a call to fromRangeString(range, 0, range.length()).

Parameters
range:String

the range string to parse (must not be null)

Returns:Predicate<String>

the parsed range (not null)

Exceptions
IllegalArgumentException:
if there is a syntax error in the range or the range cannot match any version
fromRangeStringback to summary
public default Predicate<String> fromRangeString(String range, int start, int end)

Parse a range specification and return it as a predicate. Version ranges are governed by the following general syntax: range ::= range-spec ',' range | range-spec range-spec ::= '[' version '] | min-version ',' max-version min-version ::= '[' version | '(' version | '(' max-version ::= version ']' | version ')' | ')' This is aligned with the syntax used by Maven, however it can be applied to any supported version scheme.

It is important to note that within a range specification, the , separator indicates a logical "and" or "intersection" operation, whereas the , separator found in between range specifications acts as a logical "or" or "union" operation.

Here are some examples of valid version range specifications:

  • 1.0 Version 1.0 as a recommended version (like whenEquals("1.0"))
  • [1.0] Version 1.0 explicitly only (like whenEquals("1.0"))
  • [1.0,2.0) Versions 1.0 (included) to 2.0 (not included) (like whenGe("1.0").and(whenLt("2.0")))
  • [1.0,2.0] Versions 1.0 to 2.0 (both included) (like whenGe("1.0").and(whenLe("2.0")))
  • [1.5,) Versions 1.5 and higher (like whenGe("1.5"))
  • (,1.0],[1.2,) Versions up to 1.0 (included) and 1.2 or higher (like whenLe("1.0").or(whenGe("1.2")))
Parameters
range:String

the range string to parse (must not be null)

start:int

the start of the range within the string (inclusive)

end:int

the end of the range within the string (exclusive)

Returns:Predicate<String>

the parsed range (not null)

Exceptions
IllegalArgumentException:
if there is a syntax error in the range or the range cannot match any version
IndexOutOfBoundsException:
if the values for start or end are not valid
geback to summary
public default boolean ge(String base, String other)

Determine if the first version is greater than the second version according to this version scheme.

Parameters
base:String

the base version

other:String

the other version

Returns:boolean

true if the first version is greater than the second version, or false otherwise

gtback to summary
public default boolean gt(String base, String other)

Determine if the first version is greater than or equal to the second version according to this version scheme.

Parameters
base:String

the base version

other:String

the other version

Returns:boolean

true if the first version is greater than or equal to the second version, or false otherwise

iterateback to summary
public VersionIterator iterate(String version)

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

Parameters
version:String

the version to iterate (must not be null)

Returns:VersionIterator

the version iterator (not null)

leback to summary
public default boolean le(String base, String other)

Determine if the first version is less than or equal to the second version according to this version scheme.

Parameters
base:String

the base version

other:String

the other version

Returns:boolean

true if the first version is less than or equal to the second version, or false otherwise

ltback to summary
public default boolean lt(String base, String other)

Determine if the first version is less than the second version according to this version scheme.

Parameters
base:String

the base version

other:String

the other version

Returns:boolean

true if the first version is less than the second version, or false otherwise

maxback to summary
public default String max(String a, String b)

Returns the greater (later) of the two versions.

Parameters
a:String

the first version (must not be null)

b:String

the second version (must not be null)

Returns:String

the greater (later) of the two versions

minback to summary
public default String min(String a, String b)

Returns the lesser (earlier) of the two versions.

Parameters
a:String

the first version (must not be null)

b:String

the second version (must not be null)

Returns:String

the lesser (earlier) of the two versions

parseMinExclback to summary
private Predicate<String> parseMinExcl(String range, int start, int end)
parseMinInclback to summary
private Predicate<String> parseMinIncl(String range, int start, int end)
parseMoreback to summary
private Predicate<String> parseMore(Predicate<String> predicate, final String range, int start, int end)

Parse the end context (make sure there is no trailing garbage, combine subsequent predicates).

Parameters
predicate:Predicate<String>

the predicate to return

range:String

the range string

start:int

the remaining start

end:int

the end

Returns:Predicate<String>

the predicate

parseRangeback to summary
private Predicate<String> parseRange(final String range, int start, final int end)
parseRangeMaxback to summary
private Predicate<String> parseRangeMax(Predicate<String> min, String range, int start, int end)
parseSingleback to summary
private Predicate<String> parseSingle(String range, int start, int end)
validateback to summary
public default void validate(String version) throws VersionSyntaxException

Validate the syntax of the given version.

Parameters
version:String

the version to validate (must not be null)

Exceptions
VersionSyntaxException:
if the syntax of the version is invalid according to this version scheme
whenEqualsback to summary
public default Predicate<String> whenEquals(String other)

Returns a predicate that tests if the version is equal to the base version.

Parameters
other:String

the other version

Returns:Predicate<String>

true if the first version is equal to the second version, or false otherwise

whenGeback to summary
public default Predicate<String> whenGe(String other)

Returns a predicate that tests if the version is greater than or equal to the base version.

Parameters
other:String

the other version

Returns:Predicate<String>

a predicate that tests if the version is greater than or equal to the base version

whenGtback to summary
public default Predicate<String> whenGt(String other)

Returns a predicate that tests if the version is greater than or equal to the base version.

Parameters
other:String

the other version

Returns:Predicate<String>

true if the first version is less than the second version, or false otherwise

whenLeback to summary
public default Predicate<String> whenLe(String other)

Returns a predicate that tests if the version is less than or equal to the base version.

Parameters
other:String

the other version

Returns:Predicate<String>

a predicate that tests if the version is less than or equal to the base version

whenLtback to summary
public default Predicate<String> whenLt(String other)

Returns a predicate that tests if the version is less than the base version.

Parameters
other:String

the other version

Returns:Predicate<String>

a predicate that tests if the version is less than the base version