Package io.sentry.semver

Class Version

java.lang.Object
io.sentry.semver.Version
All Implemented Interfaces:
Serializable, Comparable<Version>
public final class Version extends Object implements Comparable<Version>, Serializable
This class is an implementation of the full semantic version 2.0.0 specification. Instances can be obtained using the static overloads of the create method or by 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.

Author:
Simon Taddiken
See Also:

  • Nested Class Summary

    Nested Classes
    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.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Version
    COMPLIANCE
    Semantic Version Specification to which this class complies.
    static final Comparator<Version>
    NATURAL_ORDER
    Comparator for natural version ordering.
    static final Comparator<Version>
    WITH_BUILD_META_DATA_ORDER
    Comparator for ordering versions with additionally considering the build meta data field when comparing versions.
    static final Version
    ZERO
    The minimum value '0.0.0' for valid versions where all parts are 0 or empty.

  • Method Summary

    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 final Version
    create(int major)
    Creates a new Version with the provided major version, leaving the minor and patch version 0.
    static final Version
    create(int major, int minor)
    Creates a new Version from the two provided components, leaving the patch version 0.
    static final Version
    create(int major, int minor, int patch)
    Creates a new Version from the three provided components.
    static final Version
    create(int major, int minor, int patch, String preRelease)
    Creates a new Version from the provided components.
    static final Version
    create(int major, int minor, int patch, String preRelease, String buildMetaData)
    Creates a new Version from the provided components.
    boolean
    equals(Object obj)
    Determines whether this version is equal to the passed object.
    boolean
    equalsWithBuildMetaData(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.
    String
    getBuildMetaData()
    Gets this version's build meta data.
    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.
    String
    getPreRelease()
    Gets the pre release identifier of this version.
    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
    isGreaterThanOrEqualTo(Version other)
    Tests whether this version is equal to or 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
    isLowerThanOrEqualTo(Version other)
    Tests whether this version is equal to or lower than the given other version in terms of precedence.
    boolean
    isPreRelease()
    Determines whether this is a pre release version.
    boolean
    isStable()
    Whether this is a 'stable' version.
    static boolean
    isValidBuildMetaData(String buildMetaData)
    Returns whether the given String is a valid build meta data identifier.
    static boolean
    isValidPreRelease(String preRelease)
    Returns whether the given String is a valid pre-release identifier.
    static boolean
    isValidVersion(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(String newPrelease)
    Given this Version, returns the next major Version.
    Version
    nextMajor(String[] newPrelease)
    Given this Version, returns the next major Version.
    Version
    nextMinor()
    Given this version, returns the next minor version.
    Version
    nextMinor(String newPrelease)
    Given this version, returns the next minor version.
    Version
    nextMinor(String[] newPrelease)
    Given this version, returns the next minor version.
    Version
    nextPatch()
    Given this version, returns the next patch version.
    Version
    nextPatch(String newPrelease)
    Given this version, returns the next patch version.
    Version
    nextPatch(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 final Version
    parseVersion(String versionString)
    Tries to parse the provided String as a semantic version.
    static Version
    parseVersion(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.
    Version
    toStable()
    Drops both the pre-release and the build meta data from this version.
    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(String newBuildMetaData)
    Creates a new Version from this one, replacing only the build-meta-data part with the given String.
    Version
    withBuildMetaData(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(String newPreRelease)
    Creates a new Version from this one, replacing only the pre-release part with the given String.
    Version
    withPreRelease(String[] newPreRelease)
    Creates a new Version from this one, replacing only the pre-release part with the given array.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • ZERO

      public static final Version ZERO
      The minimum value '0.0.0' for valid versions where all parts are 0 or empty.
      Since:
      2.1.0

    • COMPLIANCE

      public static final Version COMPLIANCE
      Semantic Version Specification to which this class complies.
      Since:
      0.2.0

    • NATURAL_ORDER

      public static final Comparator<Version> NATURAL_ORDER
      Comparator for natural version ordering. See compare(Version, Version) for more information.

      Instead of using this field, consider using a method reference like in Version::compare.

      Since:
      0.2.0

    • WITH_BUILD_META_DATA_ORDER

      public static final Comparator<Version> WITH_BUILD_META_DATA_ORDER
      Comparator for ordering versions with additionally considering the build meta data field when comparing versions.

      Instead of using this field, consider using a method reference like in Version::compareWithBuildMetaData.

      Note: this comparator imposes orderings that are inconsistent with equals.

      Since:
      0.3.0

  • Method Details

    • withMajor

      public Version withMajor(int newMajor)
      Creates a new Version from this one, replacing only the major part with the given one. All other parts will remain the same as in this Version.
      Parameters:
      newMajor - The new major version.
      Returns:
      A new Version.
      Throws:
      IllegalArgumentException - If all fields in the resulting Version are 0.
      Since:
      1.1.0

    • withMinor

      public Version withMinor(int newMinor)
      Creates a new Version from this one, replacing only the minor part with the given one. All other parts will remain the same as in this Version.
      Parameters:
      newMinor - The new minor version.
      Returns:
      A new Version.
      Throws:
      IllegalArgumentException - If all fields in the resulting Version are 0.
      Since:
      1.1.0

    • withPatch

      public Version withPatch(int newPatch)
      Creates a new Version from this one, replacing only the patch part with the given one. All other parts will remain the same as in this Version.
      Parameters:
      newPatch - The new patch version.
      Returns:
      A new Version.
      Throws:
      IllegalArgumentException - If all fields in the resulting Version are 0.
      Since:
      1.1.0

    • withPreRelease

      public Version withPreRelease(String newPreRelease)
      Creates a new Version from this one, replacing only the pre-release part with the given String. All other parts will remain the same as in this Version. You can remove the pre-release part by passing an empty String.
      Parameters:
      newPreRelease - The new pre-release identifier.
      Returns:
      A new Version.
      Throws:
      Version.VersionFormatException - If the given String is not a valid pre-release identifier.
      IllegalArgumentException - If preRelease is null.
      Since:
      1.1.0

    • withPreRelease

      public Version withPreRelease(String[] newPreRelease)
      Creates a new Version from this one, replacing only the pre-release part with the given array. All other parts will remain the same as in this Version. You can remove the pre-release part by passing an empty array.

      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" })
      Parameters:
      newPreRelease - the new pre release parts.
      Returns:
      A new Version.
      Throws:
      Version.VersionFormatException - If the any element of the given array is not a valid pre release identifier part.
      IllegalArgumentException - If newPreRelease is null.
      Since:
      1.2.0

    • withBuildMetaData

      public Version withBuildMetaData(String newBuildMetaData)
      Creates a new Version from this one, replacing only the build-meta-data part with the given String. All other parts will remain the same as in this Version. You can remove the build-meta-data part by passing an empty String.
      Parameters:
      newBuildMetaData - The new build meta data identifier.
      Returns:
      A new Version.
      Throws:
      Version.VersionFormatException - If the given String is not a valid build-meta-data identifier.
      IllegalArgumentException - If newBuildMetaData is null.
      Since:
      1.1.0

    • withBuildMetaData

      public Version withBuildMetaData(String[] newBuildMetaData)
      Creates a new Version from this one, replacing only the build-meta-data part with the given array. All other parts will remain the same as in this Version. You can remove the build-meta-data part by passing an empty array.

      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" })
      Parameters:
      newBuildMetaData - the new build meta data parts.
      Returns:
      A new Version.
      Throws:
      Version.VersionFormatException - If the any element of the given array is not a valid build meta data identifier part.
      IllegalArgumentException - If newBuildMetaData is null.
      Since:
      1.2.0

    • toStable

      public Version toStable()
      Drops both the pre-release and the build meta data from this version.
      Returns:
      The nearest stable version.
      Since:
      2.1.0

    • nextMajor

      public Version nextMajor()
      Given this Version, returns the next major Version. That is, the major part is incremented by 1 and the remaining parts are set to 0. This also drops the pre-release and build-meta-data.
      Returns:
      The incremented version.
      Since:
      1.2.0
      See Also:

    • nextMajor

      public Version nextMajor(String newPrelease)
      Given this Version, returns the next major Version. That is, the major part is incremented by 1 and the remaining parts are set to 0. The pre-release part will be set to the given identifier and the build-meta-data is dropped.
      Parameters:
      newPrelease - The pre-release part for the resulting Version.
      Returns:
      The incremented version.
      Throws:
      Version.VersionFormatException - If the given String is not a valid pre-release identifier.
      IllegalArgumentException - If newPreRelease is null.
      Since:
      1.2.0
      See Also:

    • nextMajor

      public Version nextMajor(String[] newPrelease)
      Given this Version, returns the next major Version. That is, the major part is incremented by 1 and the remaining parts are set to 0. The pre-release part will be set to the given identifier and the build-meta-data is dropped.
      Parameters:
      newPrelease - The pre-release part for the resulting Version.
      Returns:
      The incremented version.
      Throws:
      Version.VersionFormatException - If the any element of the given array is not a valid pre release identifier part.
      IllegalArgumentException - If newPreRelease is null.
      Since:
      1.2.0
      See Also:

    • nextMinor

      public Version nextMinor()
      Given this version, returns the next minor version. That is, the major part remains the same, the minor version is incremented and all other parts are reset/dropped.
      Returns:
      The incremented version.
      Since:
      1.2.0
      See Also:

    • nextMinor

      public Version nextMinor(String newPrelease)
      Given this version, returns the next minor version. That is, the major part remains the same and the minor version is incremented. The pre-release part will be set to the given identifier and the build-meta-data is dropped.
      Parameters:
      newPrelease - The pre-release part for the resulting Version.
      Returns:
      The incremented version.
      Throws:
      Version.VersionFormatException - If the given String is not a valid pre-release identifier.
      IllegalArgumentException - If newPreRelease is null.
      Since:
      1.2.0
      See Also:

    • nextMinor

      public Version nextMinor(String[] newPrelease)
      Given this version, returns the next minor version. That is, the major part remains the same and the minor version is incremented. The pre-release part will be set to the given identifier and the build-meta-data is dropped.
      Parameters:
      newPrelease - The pre-release part for the resulting Version.
      Returns:
      The incremented version.
      Throws:
      Version.VersionFormatException - If the any element of the given array is not a valid pre release identifier part.
      IllegalArgumentException - If newPreRelease is null.
      Since:
      1.2.0
      See Also:

    • nextPatch

      public Version nextPatch()
      Given this version, returns the next patch version. That is, the major and minor parts remain the same, the patch version is incremented and all other parts are reset/dropped.
      Returns:
      The incremented version.
      Since:
      1.2.0
      See Also:

    • nextPatch

      public Version nextPatch(String newPrelease)
      Given this version, returns the next patch version. That is, the major and minor parts remain the same and the patch version is incremented. The pre-release part will be set to the given identifier and the build-meta-data is dropped.
      Parameters:
      newPrelease - The pre-release part for the resulting Version.
      Returns:
      The incremented version.
      Throws:
      Version.VersionFormatException - If the given String is not a valid pre-release identifier.
      IllegalArgumentException - If newPreRelease is null.
      Since:
      1.2.0
      See Also:

    • nextPatch

      public Version nextPatch(String[] newPrelease)
      Given this version, returns the next patch version. That is, the major and minor parts remain the same and the patch version is incremented. The pre-release part will be set to the given identifier and the build-meta-data is dropped.
      Parameters:
      newPrelease - The pre-release part for the resulting Version.
      Returns:
      The incremented version.
      Throws:
      Version.VersionFormatException - If the any element of the given array is not a valid pre release identifier part.
      IllegalArgumentException - If newPreRelease is null.
      Since:
      1.2.0
      See Also:

    • nextPreRelease

      public Version nextPreRelease()
      Derives a new Version instance from this one by only incrementing the pre-release identifier. The build-meta-data will be dropped, all other fields remain the same.

      The incrementation of the pre-release identifier behaves as follows:

      • In case the identifier is currently empty, it becomes "1" in the result.
      • If the identifier's last part is numeric, that last part will be incremented in the result.
      • If the last part is not numeric, the identifier is interpreted as identifier.0 which becomes identifier.1 after increment.
      Examples:
      Pre-release identifier incrementation behavior
      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
      Returns:
      The incremented Version.
      Since:
      1.2.0

    • nextBuildMetaData

      public Version nextBuildMetaData()
      Derives a new Version instance from this one by only incrementing the build-meta-data identifier. All other fields remain the same.

      The incrementation of the build-meta-data identifier behaves as follows:

      • In case the identifier is currently empty, it becomes "1" in the result.
      • If the identifier's last part is numeric, that last part will be incremented in the result. Leading 0's will be removed.
      • If the last part is not numeric, the identifier is interpreted as identifier.0 which becomes identifier.1 after increment.
      Examples:
      Build meta data incrementation behavior
      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
      Returns:
      The incremented Version.
      Since:
      1.2.0

    • isValidVersion

      public static boolean isValidVersion(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.

      Note: this method does not throw an exception upon null input, but returns false instead.

      Parameters:
      version - The String to check.
      Returns:
      Whether the given String is formatted as a semantic version.
      Since:
      0.5.0

    • isValidPreRelease

      public static boolean isValidPreRelease(String preRelease)
      Returns whether the given String is a valid pre-release identifier. That is, this method returns 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.

      Parameters:
      preRelease - The String to check.
      Returns:
      Whether the given String is a valid pre-release identifier.
      Since:
      0.5.0

    • isValidBuildMetaData

      public static boolean isValidBuildMetaData(String buildMetaData)
      Returns whether the given String is a valid build meta data identifier. That is, this method returns 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.

      Parameters:
      buildMetaData - The String to check.
      Returns:
      Whether the given String is a valid build meta data identifier.
      Since:
      0.5.0

    • max

      public static Version max(Version v1, Version v2)
      Returns the greater of the two given versions by comparing them using their natural ordering. If both versions are equal, then the first argument is returned.
      Parameters:
      v1 - The first version.
      v2 - The second version.
      Returns:
      The greater version.
      Throws:
      IllegalArgumentException - If either argument is null.
      Since:
      0.4.0

    • min

      public static Version min(Version v1, Version v2)
      Returns the lower of the two given versions by comparing them using their natural ordering. If both versions are equal, then the first argument is returned.
      Parameters:
      v1 - The first version.
      v2 - The second version.
      Returns:
      The lower version.
      Throws:
      IllegalArgumentException - If either argument is null.
      Since:
      0.4.0

    • compare

      public static int compare(Version v1, Version v2)
      Compares two versions, following the semantic version specification. Here is a quote from semantic version 2.0.0 specification:

      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.

      Parameters:
      v1 - The first version for comparison.
      v2 - The second version for comparison.
      Returns:
      A value below 0 iff v1 &lt; v2, a value above 0 iff v1 &gt; v2</tt> and 0 iff <tt>v1 = v2.
      Throws:
      NullPointerException - If either parameter is null.
      Since:
      0.2.0

    • compareWithBuildMetaData

      public static int compareWithBuildMetaData(Version v1, Version v2)
      Compares two Versions with additionally considering the build meta data field 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.

      This method fulfills the general contract for Java's Comparators and Comparables.

      Parameters:
      v1 - The first version for comparison.
      v2 - The second version for comparison.
      Returns:
      A value below 0 iff v1 &lt; v2, a value above 0 iff v1 &gt; v2</tt> and 0 iff <tt>v1 = v2.
      Throws:
      NullPointerException - If either parameter is null.
      Since:
      0.3.0

    • create

      public static final Version create(int major, int minor, int patch, String preRelease, String buildMetaData)
      Creates a new Version from the provided components. Neither value of 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.
      Parameters:
      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.
      Returns:
      The version instance.
      Throws:
      Version.VersionFormatException - If preRelease or buildMetaData does not conform to the semantic version specification.

    • create

      public static final Version create(int major, int minor, int patch, String preRelease)
      Creates a new Version from the provided components. The version's build meta data field will be empty. Neither value of 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.
      Parameters:
      major - The major version.
      minor - The minor version.
      patch - The patch version.
      preRelease - The pre release version or the empty string.
      Returns:
      The version instance.
      Throws:
      Version.VersionFormatException - If preRelease is not empty and does not conform to the semantic versioning specification

    • create

      public static final Version create(int major, int minor, int patch)
      Creates a new Version from the three provided components. The version's pre release and build meta data fields will be empty. Neither value must be lower than 0 and at least one must be greater than zero.
      Parameters:
      major - The major version.
      minor - The minor version.
      patch - The patch version.
      Returns:
      The version instance.

    • create

      public static final Version create(int major, int minor)
      Creates a new Version from the two provided components, leaving the patch version 0. The version's pre release and build meta data fields will be empty. Neither value must be lower than 0 and at least one must be greater than zero.
      Parameters:
      major - The major version.
      minor - The minor version.
      Returns:
      The version instance.
      Since:
      2.1.0

    • create

      public static final Version create(int major)
      Creates a new Version with the provided major version, leaving the minor and patch version 0. The version's pre release and build meta data fields will be empty. The major value must be lower than or equal to 0.
      Parameters:
      major - The major version.
      Returns:
      The version instance.
      Since:
      2.1.0

    • parseVersion

      public static final Version parseVersion(String versionString)
      Tries to parse the provided String as a semantic version. If the string does not conform to the semantic version specification, a Version.VersionFormatException will be thrown.
      Parameters:
      versionString - The String to parse.
      Returns:
      The parsed version.
      Throws:
      Version.VersionFormatException - If the String is no valid version
      IllegalArgumentException - If versionString is null.

    • parseVersion

      public static Version parseVersion(String versionString, boolean allowPreRelease)
      Tries to parse the provided String as a semantic version. If 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.

      Parameters:
      versionString - The String to parse.
      allowPreRelease - Whether pre-release and build meta data field are allowed.
      Returns:
      The parsed version.
      Throws:
      Version.VersionFormatException - If the String is no valid version
      Since:
      0.4.0

    • min

      public Version min(Version other)
      Returns the lower of this version and the given version according to its natural ordering. If versions are equal, this is returned.
      Parameters:
      other - The version to compare with.
      Returns:
      The lower version.
      Throws:
      IllegalArgumentException - If other is null.
      Since:
      0.5.0
      See Also:

    • max

      public Version max(Version other)
      Returns the greater of this version and the given version according to its natural ordering. If versions are equal, this is returned.
      Parameters:
      other - The version to compare with.
      Returns:
      The greater version.
      Throws:
      IllegalArgumentException - If other is null.
      Since:
      0.5.0
      See Also:

    • getMajor

      public int getMajor()
      Gets this version's major number.
      Returns:
      The major version.

    • getMinor

      public int getMinor()
      Gets this version's minor number.
      Returns:
      The minor version.

    • getPatch

      public int getPatch()
      Gets this version's path number.
      Returns:
      The patch number.

    • getPreReleaseParts

      public String[] getPreReleaseParts()
      Gets the pre release identifier parts of this version as array. Modifying the resulting array will have no influence on the internal state of this object.
      Returns:
      Pre release version as array. Array is empty if this version has no pre release part.

    • getPreRelease

      public String getPreRelease()
      Gets the pre release identifier of this version. If this version has no such identifier, an empty string is returned.

      Note: This method will always reconstruct a new String by joining the single identifier parts.

      Returns:
      This version's pre release identifier or an empty String if this version has no such identifier.

    • getBuildMetaData

      public String getBuildMetaData()
      Gets this version's build meta data. If this version has no build meta data, the returned string is empty.

      Note: This method will always reconstruct a new String by joining the single identifier parts.

      Returns:
      The build meta data or an empty String if this version has no build meta data.

    • getBuildMetaDataParts

      public String[] getBuildMetaDataParts()
      Gets the build meta data identifier parts of this version as array. Modifying the resulting array will have no influence on the internal state of this object.
      Returns:
      Build meta data as array. Array is empty if this version has no build meta data part.

    • isInitialDevelopment

      public boolean isInitialDevelopment()
      Determines whether this version is still under initial development.
      Returns:
      true iff this version's major part is zero.

    • isStable

      public boolean isStable()
      Whether this is a 'stable' version. That is, it has no pre-release identifier.
      Returns:
      true iff getPreRelease() is empty.
      Since:
      2.1.0
      See Also:

    • isPreRelease

      public boolean isPreRelease()
      Determines whether this is a pre release version.
      Returns:
      true iff getPreRelease() is not empty.
      See Also:

    • hasBuildMetaData

      public boolean hasBuildMetaData()
      Determines whether this version has a build meta data field.
      Returns:
      true iff getBuildMetaData() is not empty.

    • toString

      public String toString()
      Creates a String representation of this version by joining its parts together as by the semantic version specification.
      Overrides:
      toString in class Object
      Returns:
      The version as a String.

    • hashCode

      public int hashCode()
      The hash code for a version instance is computed from the fields major, minor, patch and pre-release.
      Overrides:
      hashCode in class Object
      Returns:
      A hash code for this object.

    • equals

      public boolean equals(Object obj)
      Determines whether this version is equal to the passed object. This is the case if the passed object is an instance of Version and this version compared to the provided one yields 0. Thus, this method ignores the getBuildMetaData() field.
      Overrides:
      equals in class Object
      Parameters:
      obj - the object to compare with.
      Returns:
      true iff obj is an instance of Version and this.compareTo((Version) obj) == 0
      See Also:

    • equalsWithBuildMetaData

      public boolean equalsWithBuildMetaData(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.
      Parameters:
      obj - The object to compare with.
      Returns:
      true iff this.equals(obj) and this.getBuildMetaData().equals(((Version) obj).getBuildMetaData())
      Since:
      0.4.0

    • compareTo

      public int compareTo(Version other)
      Compares this version to the provided one, following the semantic versioning specification. See compare(Version, Version) for more information.
      Specified by:
      compareTo in interface Comparable<Version>
      Parameters:
      other - The version to compare to.
      Returns:
      A value lower than 0 if this < other, a value greater than 0 if this > other and 0 if this == other. The absolute value of the result has no semantical interpretation.

    • compareToWithBuildMetaData

      public int compareToWithBuildMetaData(Version other)
      Compares this version to the provided one. Unlike the 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.

      Parameters:
      other - The version to compare to.
      Returns:
      A value lower than 0 if this < other, a value greater than 0 if this > other and 0 if this == other. The absolute value of the result has no semantical interpretation.
      Since:
      0.3.0

    • toUpperCase

      public Version toUpperCase()
      Returns a new Version where all identifiers are converted to upper case letters.
      Returns:
      A new version with lower case identifiers.
      Since:
      1.1.0

    • toLowerCase

      public Version toLowerCase()
      Returns a new Version where all identifiers are converted to lower case letters.
      Returns:
      A new version with lower case identifiers.
      Since:
      1.1.0

    • isGreaterThan

      public boolean isGreaterThan(Version other)
      Tests whether this version is strictly greater than the given other version in terms of precedence. Does not consider the build meta data part.

      Convenience method for this.compareTo(other) > 0 except that this method throws an IllegalArgumentException if other is null.

      Parameters:
      other - The version to compare to.
      Returns:
      Whether this version is strictly greater.
      Since:
      1.1.0

    • isGreaterThanOrEqualTo

      public boolean isGreaterThanOrEqualTo(Version other)
      Tests whether this version is equal to or greater than the given other version in terms of precedence. Does not consider the build meta data part.

      Convenience method for this.compareTo(other) >= 0 except that this method throws an IllegalArgumentException if other is null.

      Parameters:
      other - The version to compare to.
      Returns:
      Whether this version is greater or equal.
      Since:
      2.1.0

    • isLowerThan

      public boolean isLowerThan(Version other)
      Tests whether this version is strictly lower than the given other version in terms of precedence. Does not consider the build meta data part.

      Convenience method for this.compareTo(other) < 0 except that this method throws an IllegalArgumentException if other is null.

      Parameters:
      other - The version to compare to.
      Returns:
      Whether this version is strictly lower.
      Since:
      1.1.0

    • isLowerThanOrEqualTo

      public boolean isLowerThanOrEqualTo(Version other)
      Tests whether this version is equal to or lower than the given other version in terms of precedence. Does not consider the build meta data part.

      Convenience method for this.compareTo(other) <= 0 except that this method throws an IllegalArgumentException if other is null.

      Parameters:
      other - The version to compare to.
      Returns:
      Whether this version is lower or equal.
      Since:
      2.1.0