java.io.Serializable, java.lang.Comparable<Version>public final class Version extends java.lang.Object implements java.lang.Comparable<Version>, java.io.Serializable
parsing a String. This class implements Comparable to compare two versions by
following the specifications linked to above. The equals(Object) method
conforms to the result of compareTo(Version), hashCode() is
implemented appropriately. Neither method considers the build meta data field for comparison.
Instances of this class are immutable and thus thread safe. This also means that all methods taking an array or other kind of modifiable objects as input, will first make a copy before using it as internal state.
Note that unless stated otherwise, none of the public methods of this class accept
null values. Most methods will throw an IllegalArgumentException
when encountering a null argument. However, to comply with the
Comparable contract, the comparison methods will throw a
NullPointerException instead.
| Modifier and Type | Class | Description |
|---|---|---|
static class |
Version.VersionFormatException |
This exception indicates that a version- or a part of a version string could not be
parsed according to the semantic version specification.
|
| Modifier and Type | Field | Description |
|---|---|---|
static Version |
COMPLIANCE |
Semantic Version Specification to which this class complies.
|
static java.util.Comparator<Version> |
NATURAL_ORDER |
Comparator for natural version ordering.
|
static java.util.Comparator<Version> |
WITH_BUILD_META_DATA_ORDER |
Comparator for ordering versions with additionally considering the build meta data
field when comparing versions.
|
| Modifier and Type | Method | Description |
|---|---|---|
static int |
compare(Version v1,
Version v2) |
Compares two versions, following the semantic version specification.
|
int |
compareTo(Version other) |
Compares this version to the provided one, following the semantic
versioning specification.
|
int |
compareToWithBuildMetaData(Version other) |
Compares this version to the provided one.
|
static int |
compareWithBuildMetaData(Version v1,
Version v2) |
Compares two Versions with additionally considering the build meta data field if
all other parts are equal.
|
static Version |
create(int major,
int minor,
int patch) |
Creates a new Version from the three provided components.
|
static Version |
create(int major,
int minor,
int patch,
java.lang.String preRelease) |
Creates a new Version from the provided components.
|
static Version |
create(int major,
int minor,
int patch,
java.lang.String preRelease,
java.lang.String buildMetaData) |
Creates a new Version from the provided components.
|
boolean |
equals(java.lang.Object obj) |
Determines whether this version is equal to the passed object.
|
boolean |
equalsWithBuildMetaData(java.lang.Object obj) |
Determines whether this version is equal to the passed object (as determined by
equals(Object) and additionally considers the build meta data part of both
versions for equality. |
java.lang.String |
getBuildMetaData() |
Gets this version's build meta data.
|
java.lang.String[] |
getBuildMetaDataParts() |
Gets the build meta data identifier parts of this version as array.
|
int |
getMajor() |
Gets this version's major number.
|
int |
getMinor() |
Gets this version's minor number.
|
int |
getPatch() |
Gets this version's path number.
|
java.lang.String |
getPreRelease() |
Gets the pre release identifier of this version.
|
java.lang.String[] |
getPreReleaseParts() |
Gets the pre release identifier parts of this version as array.
|
boolean |
hasBuildMetaData() |
Determines whether this version has a build meta data field.
|
int |
hashCode() |
The hash code for a version instance is computed from the fields
major, minor, patch and
pre-release. |
boolean |
isGreaterThan(Version other) |
Tests whether this version is strictly greater than the given other version in
terms of precedence.
|
boolean |
isInitialDevelopment() |
Determines whether this version is still under initial development.
|
boolean |
isLowerThan(Version other) |
Tests whether this version is strictly lower than the given other version in terms
of precedence.
|
boolean |
isPreRelease() |
Determines whether this is a pre release version.
|
static boolean |
isValidBuildMetaData(java.lang.String buildMetaData) |
Returns whether the given String is a valid build meta data identifier.
|
static boolean |
isValidPreRelease(java.lang.String preRelease) |
Returns whether the given String is a valid pre-release identifier.
|
static boolean |
isValidVersion(java.lang.String version) |
Tries to parse the given String as a semantic version and returns whether the
String is properly formatted according to the semantic version specification.
|
Version |
max(Version other) |
Returns the greater of this version and the given version according to its natural
ordering.
|
static Version |
max(Version v1,
Version v2) |
Returns the greater of the two given versions by comparing them using their natural
ordering.
|
Version |
min(Version other) |
Returns the lower of this version and the given version according to its natural
ordering.
|
static Version |
min(Version v1,
Version v2) |
Returns the lower of the two given versions by comparing them using their natural
ordering.
|
Version |
nextBuildMetaData() |
Derives a new Version instance from this one by only incrementing the
build-meta-data identifier.
|
Version |
nextMajor() |
Given this Version, returns the next major Version.
|
Version |
nextMajor(java.lang.String newPrelease) |
Given this Version, returns the next major Version.
|
Version |
nextMajor(java.lang.String[] newPrelease) |
Given this Version, returns the next major Version.
|
Version |
nextMinor() |
Given this version, returns the next minor version.
|
Version |
nextMinor(java.lang.String newPrelease) |
Given this version, returns the next minor version.
|
Version |
nextMinor(java.lang.String[] newPrelease) |
Given this version, returns the next minor version.
|
Version |
nextPatch() |
Given this version, returns the next patch version.
|
Version |
nextPatch(java.lang.String newPrelease) |
Given this version, returns the next patch version.
|
Version |
nextPatch(java.lang.String[] newPrelease) |
Given this version, returns the next patch version.
|
Version |
nextPreRelease() |
Derives a new Version instance from this one by only incrementing the pre-release
identifier.
|
static Version |
parseVersion(java.lang.String versionString) |
Tries to parse the provided String as a semantic version.
|
static Version |
parseVersion(java.lang.String versionString,
boolean allowPreRelease) |
Tries to parse the provided String as a semantic version.
|
Version |
toLowerCase() |
Returns a new Version where all identifiers are converted to lower case letters.
|
java.lang.String |
toString() |
Creates a String representation of this version by joining its parts together as by
the semantic version specification.
|
Version |
toUpperCase() |
Returns a new Version where all identifiers are converted to upper case letters.
|
Version |
withBuildMetaData(java.lang.String newBuildMetaData) |
Creates a new Version from this one, replacing only the build-meta-data part with
the given String.
|
Version |
withBuildMetaData(java.lang.String[] newBuildMetaData) |
Creates a new Version from this one, replacing only the build-meta-data part with
the given array.
|
Version |
withMajor(int newMajor) |
Creates a new Version from this one, replacing only the major part with the given
one.
|
Version |
withMinor(int newMinor) |
Creates a new Version from this one, replacing only the minor part with the given
one.
|
Version |
withPatch(int newPatch) |
Creates a new Version from this one, replacing only the patch part with the given
one.
|
Version |
withPreRelease(java.lang.String newPreRelease) |
Creates a new Version from this one, replacing only the pre-release part with the
given String.
|
Version |
withPreRelease(java.lang.String[] newPreRelease) |
Creates a new Version from this one, replacing only the pre-release part with the
given array.
|
public static final Version COMPLIANCE
public static final java.util.Comparator<Version> NATURAL_ORDER
compare(Version, Version) for
more information.public static final java.util.Comparator<Version> WITH_BUILD_META_DATA_ORDER
Note: this comparator imposes orderings that are inconsistent with equals.
public Version withMajor(int newMajor)
newMajor - The new major version.java.lang.IllegalArgumentException - If all fields in the resulting Version are 0.public Version withMinor(int newMinor)
newMinor - The new minor version.java.lang.IllegalArgumentException - If all fields in the resulting Version are 0.public Version withPatch(int newPatch)
newPatch - The new patch version.java.lang.IllegalArgumentException - If all fields in the resulting Version are 0.public Version withPreRelease(java.lang.String newPreRelease)
newPreRelease - The new pre-release identifier.Version.VersionFormatException - If the given String is not a valid pre-release
identifier.java.lang.IllegalArgumentException - If preRelease is null.public Version withPreRelease(java.lang.String[] newPreRelease)
The passed array will be copied to not allow external modification to the new Version's inner state.
A single part within the array is allowed to contain a dot ('.'). Such parts will be treated as if the array contained those parts as single elements.
v.withPreRelease(new String[] { "a.b" })
<=>
v.withPreRelease(new String[] { "a", "b" })
newPreRelease - the new pre release parts.Version.VersionFormatException - If the any element of the given array is not a valid
pre release identifier part.java.lang.IllegalArgumentException - If newPreRelease is null.public Version withBuildMetaData(java.lang.String newBuildMetaData)
newBuildMetaData - The new build meta data identifier.Version.VersionFormatException - If the given String is not a valid build-meta-data
identifier.java.lang.IllegalArgumentException - If newBuildMetaData is null.public Version withBuildMetaData(java.lang.String[] newBuildMetaData)
The passed array will be copied to not allow external modification to the new Version's inner state. A single part within the array is allowed to contain a dot ('.'). Such parts will be treated as if the array contained those parts as single elements.
v.withBuildMetaData(new String[] { "a.b" })
<=>
v.withBuildMetaData(new String[] { "a", "b" })
newBuildMetaData - the new build meta data parts.Version.VersionFormatException - If the any element of the given array is not a valid
build meta data identifier part.java.lang.IllegalArgumentException - If newBuildMetaData is null.public Version nextMajor()
nextMajor(String),
nextMajor(String[])public Version nextMajor(java.lang.String newPrelease)
newPrelease - The pre-release part for the resulting Version.Version.VersionFormatException - If the given String is not a valid pre-release
identifier.java.lang.IllegalArgumentException - If newPreRelease is null.nextMajor(),
nextMajor(String[])public Version nextMajor(java.lang.String[] newPrelease)
newPrelease - The pre-release part for the resulting Version.Version.VersionFormatException - If the any element of the given array is not a valid
pre release identifier part.java.lang.IllegalArgumentException - If newPreRelease is null.nextMajor(),
nextMajor(String)public Version nextMinor()
nextMinor(String),
nextMinor(String[])public Version nextMinor(java.lang.String newPrelease)
newPrelease - The pre-release part for the resulting Version.Version.VersionFormatException - If the given String is not a valid pre-release
identifier.java.lang.IllegalArgumentException - If newPreRelease is null.nextMinor(),
nextMinor(String[])public Version nextMinor(java.lang.String[] newPrelease)
newPrelease - The pre-release part for the resulting Version.Version.VersionFormatException - If the any element of the given array is not a valid
pre release identifier part.java.lang.IllegalArgumentException - If newPreRelease is null.nextMinor(),
nextMinor(String)public Version nextPatch()
nextPatch(String),
nextPatch(String[])public Version nextPatch(java.lang.String newPrelease)
newPrelease - The pre-release part for the resulting Version.Version.VersionFormatException - If the given String is not a valid pre-release
identifier.java.lang.IllegalArgumentException - If newPreRelease is null.nextPatch(),
nextPatch(String[])public Version nextPatch(java.lang.String[] newPrelease)
newPrelease - The pre-release part for the resulting Version.Version.VersionFormatException - If the any element of the given array is not a valid
pre release identifier part.java.lang.IllegalArgumentException - If newPreRelease is null.nextPatch(),
nextPatch(String)public Version nextPreRelease()
The incrementation of the pre-release identifier behaves as follows:
identifier.0 which becomes identifier.1 after increment.
| Version | After increment |
|---|---|
| 1.2.3 | 1.2.3-1 |
| 1.2.3+build.meta.data | 1.2.3-1 |
| 1.2.3-foo | 1.2.3-foo.1 |
| 1.2.3-foo.1 | 1.2.3-foo.2 |
public Version nextBuildMetaData()
The incrementation of the build-meta-data identifier behaves as follows:
identifier.0 which becomes identifier.1 after increment.
| Version | After increment |
|---|---|
| 1.2.3 | 1.2.3+1 |
| 1.2.3-pre.release | 1.2.3-pre.release+1 |
| 1.2.3+foo | 1.2.3+foo.1 |
| 1.2.3+foo.1 | 1.2.3+foo.2 |
public static boolean isValidVersion(java.lang.String version)
Note: this method does not throw an exception upon null input, but
returns false instead.
version - The String to check.public static boolean isValidPreRelease(java.lang.String preRelease)
true if, and only if the preRelease parameter
is either the empty string or properly formatted as a pre-release identifier
according to the semantic version specification.
Note: this method does not throw an exception upon null input, but
returns false instead.
preRelease - The String to check.public static boolean isValidBuildMetaData(java.lang.String buildMetaData)
true if, and only if the buildMetaData
parameter is either the empty string or properly formatted as a build meta data
identifier according to the semantic version specification.
Note: this method does not throw an exception upon null input, but
returns false instead.
buildMetaData - The String to check.public static Version max(Version v1, Version v2)
v1 - The first version.v2 - The second version.java.lang.IllegalArgumentException - If either argument is null.public static Version min(Version v1, Version v2)
v1 - The first version.v2 - The second version.java.lang.IllegalArgumentException - If either argument is null.public static int compare(Version v1, Version v2)
Precedence refers to how versions are compared to each other when ordered. Precedence MUST be calculated by separating the version into major, minor, patch and pre-release identifiers in that order (Build metadata does not figure into precedence). Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Major, minor, and patch versions are always compared numerically. Example: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. When major, minor, and patch are equal, a pre-release version has lower precedence than a normal version. Example: 1.0.0-alpha < 1.0.0. Precedence for two pre-release versions with the same major, minor, and patch version MUST be determined by comparing each dot separated identifier from left to right until a difference is found as follows: identifiers consisting of only digits are compared numerically and identifiers with letters or hyphens are compared lexically in ASCII sort order. Numeric identifiers always have lower precedence than non-numeric identifiers. A larger set of pre-release fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal. Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.
This method fulfills the general contract for Java's Comparators
and Comparables.
v1 - The first version for comparison.v2 - The second version for comparison.v1 < v2, a value above 0 iff
v1 > v2</tt> and 0 iff <tt>v1 = v2.java.lang.NullPointerException - If either parameter is null.public static int compareWithBuildMetaData(Version v1, Version v2)
Comparison of the build meta data parts happens exactly as for pre release identifiers. Considering of build meta data first kicks in if both versions are equal when using their natural order.
This method fulfills the general contract for Java's Comparators
and Comparables.
v1 - The first version for comparison.v2 - The second version for comparison.v1 < v2, a value above 0 iff
v1 > v2</tt> and 0 iff <tt>v1 = v2.java.lang.NullPointerException - If either parameter is null.public static final Version create(int major, int minor, int patch, java.lang.String preRelease, java.lang.String buildMetaData)
major, minor or patch must be lower than 0 and at least one must be
greater than zero. preRelease or buildMetaData may be the empty
String. In this case, the created Version will have no pre release resp.
build meta data field. If those parameters are not empty, they must conform to the
semantic version specification.major - The major version.minor - The minor version.patch - The patch version.preRelease - The pre release version or the empty string.buildMetaData - The build meta data field or the empty string.Version.VersionFormatException - If preRelease or buildMetaData does
not conform to the semantic version specification.public static final Version create(int major, int minor, int patch, java.lang.String preRelease)
major, minor or patch must be
lower than 0 and at least one must be greater than zero. preRelease may be
the empty String. In this case, the created version will have no pre release field.
If it is not empty, it must conform to the specifications of the semantic version.major - The major version.minor - The minor version.patch - The patch version.preRelease - The pre release version or the empty string.Version.VersionFormatException - If preRelease is not empty and does not
conform to the semantic versioning specificationpublic static final Version create(int major, int minor, int patch)
major - The major version.minor - The minor version.patch - The patch version.public static final Version parseVersion(java.lang.String versionString)
Version.VersionFormatException
will be thrown.versionString - The String to parse.Version.VersionFormatException - If the String is no valid versionjava.lang.IllegalArgumentException - If versionString is null.public static Version parseVersion(java.lang.String versionString, boolean allowPreRelease)
allowPreRelease is false, the String must have neither a
pre-release nor a build meta data part. Thus the given String must have the format
X.Y.Z where at least one part must be greater than zero.
If allowPreRelease is true, the String is parsed according to
the normal semantic version specification.
versionString - The String to parse.allowPreRelease - Whether pre-release and build meta data field are allowed.Version.VersionFormatException - If the String is no valid versionpublic Version min(Version other)
this is returned.other - The version to compare with.java.lang.IllegalArgumentException - If other is null.min(Version, Version)public Version max(Version other)
this is returned.other - The version to compare with.java.lang.IllegalArgumentException - If other is null.max(Version, Version)public int getMajor()
public int getMinor()
public int getPatch()
public java.lang.String[] getPreReleaseParts()
public java.lang.String getPreRelease()
Note: This method will always reconstruct a new String by joining the single identifier parts.
public java.lang.String getBuildMetaData()
Note: This method will always reconstruct a new String by joining the single identifier parts.
public java.lang.String[] getBuildMetaDataParts()
public boolean isInitialDevelopment()
true iff this version's major part is zero.public boolean isPreRelease()
true iff getPreRelease() is not empty.public boolean hasBuildMetaData()
true iff getBuildMetaData() is not empty.public java.lang.String toString()
toString in class java.lang.Objectpublic int hashCode()
major, minor, patch and
pre-release.hashCode in class java.lang.Objectpublic boolean equals(java.lang.Object obj)
compared to the provided one yields 0. Thus, this
method ignores the getBuildMetaData() field.equals in class java.lang.Objectobj - the object to compare with.true iff obj is an instance of Version and
this.compareTo((Version) obj) == 0compareTo(Version)public boolean equalsWithBuildMetaData(java.lang.Object obj)
equals(Object) and additionally considers the build meta data part of both
versions for equality.obj - The object to compare with.true iff this.equals(obj) and
this.getBuildMetaData().equals(((Version) obj).getBuildMetaData())public int compareTo(Version other)
compare(Version, Version) for more
information.compareTo in interface java.lang.Comparable<Version>other - The version to compare to.public int compareToWithBuildMetaData(Version other)
compareTo(Version)
method, this one additionally considers the build meta data field of both versions,
if all other parts are equal. Note: This is not part of the semantic
version specification.
Comparison of the build meta data parts happens exactly as for pre release identifiers. Considering of build meta data first kicks in if both versions are equal when using their natural order.
other - The version to compare to.public Version toUpperCase()
public Version toLowerCase()
public boolean isGreaterThan(Version other)
Convenience method for this.compareTo(other) > 0 except that this method
throws an IllegalArgumentException if other is null.
other - The version to compare to.public boolean isLowerThan(Version other)
Convenience method for this.compareTo(other) < 0 except that this method
throws an IllegalArgumentException if other is null.
other - The version to compare to.Copyright © 2014–2018. All rights reserved.