Package com.yahoo.component

Class VersionSpecification

java.lang.Object

com.yahoo.component.VersionSpecification

All Implemented Interfaces:

java.lang.Comparable<VersionSpecification>

public final class VersionSpecification
extends java.lang.Object
implements java.lang.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 Summary

Fields

Modifier and Type	Field	Description
static VersionSpecification	emptyVersionSpecification	The empty version

Constructor Summary

Constructors

Constructor	Description
VersionSpecification()	Creates an empty version
VersionSpecification(java.lang.Integer major)	Creates a version specification from the specified numerical components.
VersionSpecification(java.lang.Integer major, java.lang.Integer minor)	Creates a version specification from the specified numerical components.
VersionSpecification(java.lang.Integer major, java.lang.Integer minor, java.lang.Integer micro)	Creates a version specification from the specified numerical components.
VersionSpecification(java.lang.Integer major, java.lang.Integer minor, java.lang.Integer micro, java.lang.String qualifier)	Creates a version specification from the specifed components.
VersionSpecification(java.lang.String versionString)	Creates a version specification from the specified string.

Method Summary

Modifier and Type	Method	Description
int	compareTo(VersionSpecification other)	Compares this VersionSpecification object to another.
boolean	equals(java.lang.Object object)	Compares this VersionSpecification to another.
static VersionSpecification	fromString(java.lang.String versionString)
int	getMajor()	Returns the major component of this version, or 0 if not specified
int	getMicro()	Returns the micro component of this version, or 0 if not specified
int	getMinor()	Returns the minor component of this version, or 0 if not specified
java.lang.String	getQualifier()	Returns the qualifier component of this version, or "" if not specified
java.lang.Integer	getSpecifiedMajor()	Returns the specified major component, which may be null
java.lang.Integer	getSpecifiedMicro()	Returns the specified micro component, which may be null
java.lang.Integer	getSpecifiedMinor()	Returns the specified minor component, which may be null
java.lang.String	getSpecifiedQualifier()	Returns the specified qualifier component, which may be null
int	hashCode()
VersionSpecification	intersect(VersionSpecification other)
boolean	isEmpty()	check if the Version specification is equal to the empty spec ("match anything")
Version	lowestMatchingVersion()	Returns the lowest possible Version object that matches this spec
boolean	matches(Version version)	Returns true if the given version matches this specification.
java.lang.String	toString()	Returns the string representation of this version specification as major.minor.micro.qualifier, where trailing unspecified components are omitted

Methods inherited from class java.lang.Object

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

Field Detail

emptyVersionSpecification

public static final VersionSpecification emptyVersionSpecification

The empty version

Constructor Detail

VersionSpecification

public VersionSpecification()

Creates an empty version

VersionSpecification

public VersionSpecification(java.lang.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:

java.lang.IllegalArgumentException - If the numerical components are negative.

VersionSpecification

public VersionSpecification(java.lang.Integer major,
                            java.lang.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:

java.lang.IllegalArgumentException - If the numerical components are negative.

VersionSpecification

public VersionSpecification(java.lang.Integer major,
                            java.lang.Integer minor,
                            java.lang.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:

java.lang.IllegalArgumentException - If the numerical components are negative.

VersionSpecification

public VersionSpecification(java.lang.Integer major,
                            java.lang.Integer minor,
                            java.lang.Integer micro,
                            java.lang.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:

java.lang.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(java.lang.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:

java.lang.IllegalArgumentException - If version is improperly formatted.

Method Detail

fromString

public static VersionSpecification fromString(java.lang.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 java.lang.String getQualifier()

Returns the qualifier component of this version, or "" if not specified

getSpecifiedMajor

public java.lang.Integer getSpecifiedMajor()

Returns the specified major component, which may be null

getSpecifiedMinor

public java.lang.Integer getSpecifiedMinor()

Returns the specified minor component, which may be null

getSpecifiedMicro

public java.lang.Integer getSpecifiedMicro()

Returns the specified micro component, which may be null

getSpecifiedQualifier

public java.lang.String getSpecifiedQualifier()

Returns the specified qualifier component, which may be null

toString

public java.lang.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 java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.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 java.lang.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 java.lang.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:

java.lang.ClassCastException - if the specified object is not a VersionSpecification.

intersect

public VersionSpecification intersect(VersionSpecification other)