Package io.microsphere.util

Class Version

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<Version>
    @Immutable
public class Version
extends java.lang.Object
implements java.lang.Comparable<Version>, java.io.Serializable
    Represents a version number composed of major, minor, and patch components.

    This class provides methods to compare versions using standard comparison operators such as greater than, less than, and equal to. It also supports parsing version strings in the format "major.minor.patch". The supported version patterns :

    • major
    • major.minor
    • major.minor.patch
    • major.minor.patch-preRelease

    See Semantic Versioning for more details.

    Example Usage

    
 Version v1 = new Version(1, 2, 3);
 Version v2 = Version.of("1.2.3");

 // Comparison
 boolean isEqual = v1.equals(v2); // true
 boolean isGreaterThan = v1.isGreaterThan(Version.of("1.2.2")); // true
 boolean isLessThan = v1.lt(Version.of("1.3.0")); // true

 // Parsing from string
 Version v3 = Version.of("2.0.0");

 // Getting version from a class's manifest
 Version versionFromManifest = Version.getVersion(MyClass.class);
    Since:
    1.0.0
    Author:
    Mercy
    See Also:
    Serialized Form

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Version.Operator  

    • Constructor Summary

      Constructors 
      Constructor Description
      Version​(int major)
      Creates a new Version with the specified major version number.
      Version​(int major, int minor)
      Creates a new Version with the specified major and minor version numbers.
      Version​(int major, int minor, int patch)
      Creates a new Version with the specified major, minor, and patch version numbers.
      Version​(int major, int minor, int patch, java.lang.String preRelease)
      Creates a new Version with the specified major, minor, patch, and pre-release components.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int compareTo​(Version that)
      Compares this version with another version for ordering.
      boolean eq​(Version that)
      Current Version is equal to that
      boolean equals​(Version that)
      Current Version is equal to that
      boolean equals​(java.lang.Object o)
      Current Version is equal to that
      boolean ge​(Version that)
      Current Version is greater than or equal to that
      int getMajor()
      The major version
      int getMinor()
      The minor version
      int getPatch()
      The patch
      java.lang.String getPreRelease()
      The pre-release
      static Version getVersion​(java.lang.Class<?> targetClass)
      Class that exposes the version.
      boolean gt​(Version that)
      Current Version is greater than that
      int hashCode()
      Returns a hash code value for this version.
      boolean isGreaterOrEqual​(Version that)
      Current Version is greater than or equal to that
      boolean isGreaterThan​(Version that)
      Current Version is greater than that
      boolean isLessOrEqual​(Version that)
      Current Version is less than or equal to that
      boolean isLessThan​(Version that)
      Current Version is less than that
      boolean le​(Version that)
      Current Version is less than or equal to that
      boolean lt​(Version that)
      Current Version is less than that
      static Version of​(int major)
      Creates a Version with only a major version number.
      static Version of​(int major, int minor)
      Creates a Version with major and minor version numbers.
      static Version of​(int major, int minor, int patch)
      Creates a Version with major, minor, and patch version numbers.
      static Version of​(int major, int minor, int patch, java.lang.String preRelease)
      Creates a Version with major, minor, patch, and pre-release components.
      static Version of​(java.lang.String version)
      Parses a version string and creates a Version instance.
      static Version ofVersion​(int major)
      Creates a Version with only a major version number.
      static Version ofVersion​(int major, int minor)
      Creates a Version with major and minor version numbers.
      static Version ofVersion​(int major, int minor, int patch)
      Creates a Version with major, minor, and patch version numbers.
      static Version ofVersion​(int major, int minor, int patch, java.lang.String preRelease)
      Creates a Version with major, minor, patch, and pre-release components.
      static Version ofVersion​(java.lang.Class<?> classInResource)
      Creates a Version by detecting the version from the artifact containing the specified class.
      static Version ofVersion​(java.lang.String version)
      Parses a version string and creates a Version instance.
      java.lang.String toString()
      Returns the string representation of this version in the format "major.minor.patch" or "major.minor.patch-preRelease" if a pre-release identifier is present.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • Version

        public Version​(int major)
        Creates a new Version with the specified major version number. Minor and patch are defaulted to 0.

        Example Usage

        
   Version v = new Version(1); // 1.0.0
        Parameters:
        major - the major version number

      • Version

        public Version​(int major,
               int minor)
        Creates a new Version with the specified major and minor version numbers. Patch is defaulted to 0.

        Example Usage

        
   Version v = new Version(1, 2); // 1.2.0
        Parameters:
        major - the major version number
        minor - the minor version number

      • Version

        public Version​(int major,
               int minor,
               int patch)
        Creates a new Version with the specified major, minor, and patch version numbers.

        Example Usage

        
   Version v = new Version(1, 2, 3); // 1.2.3
        Parameters:
        major - the major version number
        minor - the minor version number
        patch - the patch version number

      • Version

        public Version​(int major,
               int minor,
               int patch,
               java.lang.String preRelease)
        Creates a new Version with the specified major, minor, patch, and pre-release components.

        Example Usage

        
   Version v = new Version(1, 2, 3, "SNAPSHOT"); // 1.2.3-SNAPSHOT
        Parameters:
        major - the major version number (must be non-negative)
        minor - the minor version number (must be non-negative)
        patch - the patch version number (must be non-negative)
        preRelease - the optional pre-release identifier (e.g., "SNAPSHOT", "alpha")
        Throws:
        java.lang.IllegalArgumentException - if major, minor, or patch is negative, or all are zero

    • Method Detail

      • getMajor

        public int getMajor()
        The major version
        Returns:
        major version

      • getMinor

        public int getMinor()
        The minor version
        Returns:
        minor version

      • getPatch

        public int getPatch()
        The patch
        Returns:
        patch

      • getPreRelease

        @Nullable
public java.lang.String getPreRelease()
        The pre-release
        Returns:
        pre-release

      • gt

        public boolean gt​(Version that)
        Current Version is greater than that
        Parameters:
        that - the version to be compared
        Returns:
        true if greater than, or false
        See Also:
        isGreaterThan(Version)

      • isGreaterThan

        public boolean isGreaterThan​(Version that)
        Current Version is greater than that
        Parameters:
        that - the version to be compared
        Returns:
        true if greater than, or false
        See Also:
        gt(Version)

      • ge

        public boolean ge​(Version that)
        Current Version is greater than or equal to that
        Parameters:
        that - the version to be compared
        Returns:
        true if greater than, or false
        See Also:
        isGreaterOrEqual(Version)

      • isGreaterOrEqual

        public boolean isGreaterOrEqual​(Version that)
        Current Version is greater than or equal to that
        Parameters:
        that - the version to be compared
        Returns:
        true if greater than, or false
        See Also:
        ge(Version)

      • lt

        public boolean lt​(Version that)
        Current Version is less than that
        Parameters:
        that - the version to be compared
        Returns:
        true if less than, or false

      • isLessThan

        public boolean isLessThan​(Version that)
        Current Version is less than that
        Parameters:
        that - the version to be compared
        Returns:
        true if less than, or false

      • le

        public boolean le​(Version that)
        Current Version is less than or equal to that
        Parameters:
        that - the version to be compared
        Returns:
        true if less than, or false
        See Also:
        isLessOrEqual(Version)

      • isLessOrEqual

        public boolean isLessOrEqual​(Version that)
        Current Version is less than or equal to that
        Parameters:
        that - the version to be compared
        Returns:
        true if less than, or false
        See Also:
        le(Version)

      • eq

        public boolean eq​(Version that)
        Current Version is equal to that
        Parameters:
        that - the version to be compared
        Returns:
        true if equals, or false

      • equals

        public boolean equals​(Version that)
        Current Version is equal to that
        Parameters:
        that - the version to be compared
        Returns:
        true if equals, or false

      • equals

        public boolean equals​(java.lang.Object o)
        Current Version is equal to that
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - the version to be compared
        Returns:
        true if equals, or false

      • hashCode

        public int hashCode()
        Returns a hash code value for this version.

        Example Usage

        
   Version v = Version.of("1.2.3");
   int hash = v.hashCode();
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        a hash code value for this version

      • compareTo

        public int compareTo​(Version that)
        Compares this version with another version for ordering. Versions are compared by major, then minor, then patch, then pre-release.

        Example Usage

        
   Version v1 = Version.of("1.2.3");
   Version v2 = Version.of("1.3.0");
   int result = v1.compareTo(v2); // negative (v1 < v2)
        Specified by:
        compareTo in interface java.lang.Comparable<Version>
        Parameters:
        that - the version to compare against
        Returns:
        a negative integer, zero, or a positive integer as this version is less than, equal to, or greater than the specified version

      • toString

        public java.lang.String toString()
        Returns the string representation of this version in the format "major.minor.patch" or "major.minor.patch-preRelease" if a pre-release identifier is present.

        Example Usage

        
   Version v = new Version(1, 2, 3, "SNAPSHOT");
   String s = v.toString(); // "1.2.3-SNAPSHOT"
        Overrides:
        toString in class java.lang.Object
        Returns:
        the version string

      • of

        public static Version of​(int major)
        Creates a Version with only a major version number.

        Example Usage

        
   Version v = Version.of(2); // 2.0.0
        Parameters:
        major - the major version number
        Returns:
        a new Version instance

      • of

        public static Version of​(int major,
                         int minor)
        Creates a Version with major and minor version numbers.

        Example Usage

        
   Version v = Version.of(1, 2); // 1.2.0
        Parameters:
        major - the major version number
        minor - the minor version number
        Returns:
        a new Version instance

      • of

        public static Version of​(int major,
                         int minor,
                         int patch)
        Creates a Version with major, minor, and patch version numbers.

        Example Usage

        
   Version v = Version.of(1, 2, 3); // 1.2.3
        Parameters:
        major - the major version number
        minor - the minor version number
        patch - the patch version number
        Returns:
        a new Version instance

      • of

        public static Version of​(int major,
                         int minor,
                         int patch,
                         java.lang.String preRelease)
        Creates a Version with major, minor, patch, and pre-release components.

        Example Usage

        
   Version v = Version.of(1, 0, 0, "beta"); // 1.0.0-beta
        Parameters:
        major - the major version number
        minor - the minor version number
        patch - the patch version number
        preRelease - the pre-release identifier
        Returns:
        a new Version instance

      • of

        public static Version of​(java.lang.String version)
        Parses a version string and creates a Version instance. Supports formats: "major", "major.minor", "major.minor.patch", "major.minor.patch-preRelease".

        Example Usage

        
   Version v1 = Version.of("1.2.3");          // 1.2.3
   Version v2 = Version.of("2.0.0-SNAPSHOT"); // 2.0.0-SNAPSHOT
        Parameters:
        version - the version string to parse
        Returns:
        a new Version instance
        Throws:
        java.lang.IllegalArgumentException - if the version string is null, blank, or invalid

      • ofVersion

        public static Version ofVersion​(int major)
        Creates a Version with only a major version number.

        Example Usage

        
   Version v = Version.ofVersion(2); // 2.0.0
        Parameters:
        major - the major version number
        Returns:
        a new Version instance

      • ofVersion

        public static Version ofVersion​(int major,
                                int minor)
        Creates a Version with major and minor version numbers.

        Example Usage

        
   Version v = Version.ofVersion(1, 2); // 1.2.0
        Parameters:
        major - the major version number
        minor - the minor version number
        Returns:
        a new Version instance

      • ofVersion

        public static Version ofVersion​(int major,
                                int minor,
                                int patch)
        Creates a Version with major, minor, and patch version numbers.

        Example Usage

        
   Version v = Version.ofVersion(1, 2, 3); // 1.2.3
        Parameters:
        major - the major version number
        minor - the minor version number
        patch - the patch version number
        Returns:
        a new Version instance

      • ofVersion

        public static Version ofVersion​(int major,
                                int minor,
                                int patch,
                                java.lang.String preRelease)
        Creates a Version with major, minor, patch, and pre-release components.

        Example Usage

        
   Version v = Version.ofVersion(1, 0, 0, "alpha"); // 1.0.0-alpha
        Parameters:
        major - the major version number
        minor - the minor version number
        patch - the patch version number
        preRelease - the pre-release identifier
        Returns:
        a new Version instance

      • ofVersion

        public static Version ofVersion​(java.lang.String version)
        Parses a version string and creates a Version instance. Supports formats: "major", "major.minor", "major.minor.patch", "major.minor.patch-preRelease".

        Example Usage

        
   Version v1 = Version.ofVersion("1.2.3");          // 1.2.3
   Version v2 = Version.ofVersion("2.0.0-SNAPSHOT"); // 2.0.0-SNAPSHOT
   Version v3 = Version.ofVersion("3");              // 3.0.0
        Parameters:
        version - the version string to parse
        Returns:
        a new Version instance
        Throws:
        java.lang.IllegalArgumentException - if the version string is null, blank, or contains non-numeric parts

      • ofVersion

        public static Version ofVersion​(@Nonnull
                                java.lang.Class<?> classInResource)
        Creates a Version by detecting the version from the artifact containing the specified class. This method uses ArtifactDetector to locate the artifact and retrieve its version.

        Example Usage

        
   Version version = Version.ofVersion(MyClass.class); // e.g., 1.0.0
        Parameters:
        classInResource - the class contained in the artifact whose version is to be detected
        Returns:
        a new Version instance
        Throws:
        java.lang.IllegalArgumentException - if the version can't be resolved

      • getVersion

        @Nonnull
public static Version getVersion​(java.lang.Class<?> targetClass)
                          throws java.lang.IllegalArgumentException
        Class that exposes the version. Fetches the "Implementation-Version" manifest attribute from the jar file.
        Parameters:
        targetClass - the class to exposes the version
        Returns:
        non-null
        Throws:
        java.lang.IllegalArgumentException - if the "Implementation-Version" manifest attribute can't be fetched from the jar file.