Package com.yahoo.component

Class VersionSpecification

java.lang.Object
com.yahoo.component.VersionSpecification
All Implemented Interfaces:
Comparable<VersionSpecification>
public final class VersionSpecification extends Object implements Comparable<VersionSpecification>
A component version specification.

Version specifications have four components.

  1. Major version. A non-negative integer.
  2. Minor version. A non-negative integer.
  3. Micro version. A non-negative integer.
  4. Qualifier. An ascii text string. See Version(String) for the format of the qualifier string.

A null version component means "unspecified", i.e any value of that component matches the specification

VersionSpecification objects are immutable.

Author:
arnej27959, bratseth

  • Field Details

    • emptyVersionSpecification

      public static final VersionSpecification emptyVersionSpecification
      The empty version

  • Constructor Details

    • VersionSpecification

      public VersionSpecification()
      Creates an empty version

    • VersionSpecification

      public VersionSpecification(Integer major)
      Creates a version specification from the specified numerical components.
      Parameters:
      major - major component of the version specification, or null if not specified
      Throws:
      IllegalArgumentException - If the numerical components are negative.

    • VersionSpecification

      public VersionSpecification(Integer major, Integer minor)
      Creates a version specification from the specified numerical components.
      Parameters:
      major - major component of the version specification, or null if not specified
      minor - minor component of the version specification, or null if not specified
      Throws:
      IllegalArgumentException - If the numerical components are negative.

    • VersionSpecification

      public VersionSpecification(Integer major, Integer minor, Integer micro)
      Creates a version specification from the specified numerical components.
      Parameters:
      major - major component of the version specification, or null if not specified
      minor - minor component of the version specification, or null if not specified
      micro - micro component of the version specification, or null if not specified
      Throws:
      IllegalArgumentException - If the numerical components are negative.

    • VersionSpecification

      public VersionSpecification(Integer major, Integer minor, Integer micro, String qualifier)
      Creates a version specification from the specifed components.
      Parameters:
      major - major component of the version specification, or null if not specified
      minor - minor component of the version specification, or null if not specified
      micro - micro component of the version specification, or null if not specified
      qualifier - Qualifier component of the version specification, or null if not specified
      Throws:
      IllegalArgumentException - if the numerical components are negative the qualifier string contains non-word/digit-characters, or an earlier component is not specified but a later one is

    • VersionSpecification

      public VersionSpecification(String versionString)
      Creates a version specification from the specified string.

      VersionSpecification strings follows this grammar (same as Osgi versions): 

       version ::= major('.'minor('.'micro('.'qualifier)?)?)?
 major ::= digit+
 minor ::= digit+
 micro ::= digit+
 qualifier ::= (alpha|digit|'_'|'-')+
 digit ::= [0..9]
 alpha ::= [a..zA..Z]
      Parameters:
      versionString - String representation of the version specification
      Throws:
      IllegalArgumentException - If version is improperly formatted.

  • Method Details

    • fromString

      public static VersionSpecification fromString(String versionString)

    • getMajor

      public int getMajor()
      Returns the major component of this version, or 0 if not specified

    • getMinor

      public int getMinor()
      Returns the minor component of this version, or 0 if not specified

    • getMicro

      public int getMicro()
      Returns the micro component of this version, or 0 if not specified

    • getQualifier

      public String getQualifier()
      Returns the qualifier component of this version, or "" if not specified

    • getSpecifiedMajor

      public Integer getSpecifiedMajor()
      Returns the specified major component, which may be null

    • getSpecifiedMinor

      public Integer getSpecifiedMinor()
      Returns the specified minor component, which may be null

    • getSpecifiedMicro

      public Integer getSpecifiedMicro()
      Returns the specified micro component, which may be null

    • getSpecifiedQualifier

      public String getSpecifiedQualifier()
      Returns the specified qualifier component, which may be null

    • toString

      public String toString()
      Returns the string representation of this version specification as major.minor.micro.qualifier, where trailing unspecified components are omitted
      Overrides:
      toString in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object object)
      Compares this VersionSpecification to another.

      A version is considered to be equal to another version if the major, minor and micro components are equal and the qualifier component is equal (using String.equals).

      Note that two versions are only equal if they are equally specified, use matches(com.yahoo.component.Version) to match a more specified version to a less specified.

      Overrides:
      equals in class Object
      Parameters:
      object - The VersionSpecification object to be compared.
      Returns:
      true if object is a VersionSpecification and is equal to this object; false otherwise.

    • isEmpty

      public boolean isEmpty()
      check if the Version specification is equal to the empty spec ("match anything")

    • lowestMatchingVersion

      public Version lowestMatchingVersion()
      Returns the lowest possible Version object that matches this spec

    • matches

      public boolean matches(Version version)
      Returns true if the given version matches this specification. It matches if all the numeric components specified are the same as in the version, and both qualifiers are either null or set to the same value. I.e, a version which includes a qualifier will only match exactly and will never return true from a request for an unspecified qualifier.

    • compareTo

      public int compareTo(VersionSpecification other)
      Compares this VersionSpecification object to another.

      A version is considered to be less than another version if its major component is less than the other version's major component, or the major components are equal and its minor component is less than the other version's minor component, or the major and minor components are equal and its micro component is less than the other version's micro component, or the major, minor and micro components are equal and it's qualifier component is less than the other version's qualifier component (using String.compareTo).

      A version is considered to be equal to another version if the major, minor and micro components are equal and the qualifier component is equal (using String.compareTo).

      Unspecified numeric components are treated as 0, unspecified qualifier is treated as the empty string.

      Specified by:
      compareTo in interface Comparable<VersionSpecification>
      Parameters:
      other - the VersionSpecification object to be compared.
      Returns:
      A negative integer, zero, or a positive integer if this object is less than, equal to, or greater than the specified VersionSpecification object.
      Throws:
      ClassCastException - if the specified object is not a VersionSpecification.

    • intersect

      public VersionSpecification intersect(VersionSpecification other)