org.eclipse.equinox.p2.metadata

Class Version

java.lang.Object

org.eclipse.equinox.p2.metadata.Version

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<Version>

Direct Known Subclasses:

BasicVersion

public abstract class Version
extends java.lang.Object
implements java.lang.Comparable<Version>, java.io.Serializable

A class that represents a Version in the Omni Version format. A Version can be thought of as an array of comparable elements and an optional pad value. The pad value is used when comparing two versions with a different number of segments. The Omni Version can convert almost any version into a raw format that it uses for comparisons. This enables a unified order of all such versions and solves problems that arise when the version semantics are different. A good example is the OSGi version versus the version used in Maven. The lack of qualifier in the OSGi version implies that the qualifier is an empty string. So a version without a qualifier is the smallest of all other versions with the same major,minor,micro number. With Maven semantics, it's the opposite. If the qualifier is removed, the resulting version is considered higher then all other versions with the same major, minor, and micro number. The Omni version solves this by using different raw representations of the OSGi and Maven versions. The Omni version addresses a lot of other issues as well, such as reordering of the elements or treating some parts of a version as irrelevant when comparing. The class is signature compatible with org.osgi.framework.Version but attempts to use it as such might render a UnsupportedOperationException in case the raw vector holds incompatible values. The method isOSGiCompatible() can be used to test.

Since:

2.0

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static Version	emptyVersion The version that is semantically less then all other versions.
static Version	MAX_VERSION The version that is semantically greater then all other versions.
static java.lang.String	RAW_PREFIX

Constructor Summary

Constructors

Constructor and Description
Version()

Method Summary

Modifier and Type	Method and Description
static IVersionFormat	compile(java.lang.String format) Compile a version format string into a compiled format..
static Version	create(java.lang.String version) Parses a version identifier from the specified string.
static Version	createOSGi(int major, int minor, int micro) Creates an OSGi version identifier from the specified numerical components.
static Version	createOSGi(int major, int minor, int micro, java.lang.String qualifier) Creates an OSGi version identifier from the specified components.
abstract IVersionFormat	getFormat() Returns the optional format.
abstract java.lang.String	getOriginal() Returns the original part of the string for this version or null if no such part was provided when the version was created.
abstract java.lang.Comparable<?>	getPad() Returns the pad value used when comparing this versions to versions that has a larger number of segments
abstract java.lang.Comparable<?>	getSegment(int index) An element from the raw vector representation of this version.
abstract int	getSegmentCount() Returns the number of elements in the raw vector representation of this version.
abstract boolean	isOSGiCompatible() Checks if this version is in compliance with the OSGi version spec.
static Version	parseVersion(java.lang.String version) Parses a version identifier from the specified string.
java.lang.String	toString()
abstract void	toString(java.lang.StringBuffer sb) Appends the string representation of this version onto the sb StringBuffer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Comparable

compareTo

Field Detail

RAW_PREFIX

public static final java.lang.String RAW_PREFIX

See Also:

Constant Field Values

MAX_VERSION

public static final Version MAX_VERSION

The version that is semantically greater then all other versions.

emptyVersion

public static final Version emptyVersion

The version that is semantically less then all other versions.

Constructor Detail

Version

public Version()

Method Detail

compile

public static IVersionFormat compile(java.lang.String format)
                              throws VersionFormatException

Compile a version format string into a compiled format..

Parameters:

format - The format to compile.

Returns:

The compiled format

Throws:

VersionFormatException - If the format could not be compiled

create

public static Version create(java.lang.String version)

Parses a version identifier from the specified string.

Note that this method performs a non thread-safe object pooling. Instances are stored in a weak cache, i.e. for multiple calls with the same input it is likely but not guaranteed that the same instance is retrieved. Same holds for concurrent access on this method. Clients must not assume to get the same instance for subsequent calls.

Parameters:

version - String representation of the version identifier. Leading and trailing whitespace will be ignored.

Returns:

A Version object representing the version identifier or null if version is null or an empty string.

Throws:

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

createOSGi

public static Version createOSGi(int major,
                                 int minor,
                                 int micro)

Creates an OSGi version identifier from the specified numerical components.

The qualifier is set to the empty string.

Parameters:

major - Major component of the version identifier.

minor - Minor component of the version identifier.

micro - Micro component of the version identifier.

Throws:

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

createOSGi

public static Version createOSGi(int major,
                                 int minor,
                                 int micro,
                                 java.lang.String qualifier)

Creates an OSGi version identifier from the specified components.

Parameters:

major - Major component of the version identifier.

minor - Minor component of the version identifier.

micro - Micro component of the version identifier.

qualifier - Qualifier component of the version identifier. If null is specified, then the qualifier will be set to the empty string.

Throws:

java.lang.IllegalArgumentException - If the numerical components are negative or the qualifier string is invalid.

parseVersion

public static Version parseVersion(java.lang.String version)

Parses a version identifier from the specified string. This method is for backward compatibility with OSGi and will return the OSGi "0.0.0" version when the provided string is empty or null.

Parameters:

version - String representation of the version identifier. Leading and trailing whitespace will be ignored.

Returns:

A Version object representing the version identifier. If version is null or the empty string then the OSGi emptyVersion will be returned.

Throws:

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

See Also:

create(String)

getFormat

public abstract IVersionFormat getFormat()

Returns the optional format.

getOriginal

public abstract java.lang.String getOriginal()

Returns the original part of the string for this version or null if no such part was provided when the version was created. An OSGi type version will always return the OSGi string representation.

Returns:

The original part of the version string or null if that part was missing.

getPad

public abstract java.lang.Comparable<?> getPad()

Returns the pad value used when comparing this versions to versions that has a larger number of segments

Returns:

The pad value or null if not set.

getSegment

public abstract java.lang.Comparable<?> getSegment(int index)

An element from the raw vector representation of this version.

Parameters:

index - The zero based index of the desired element

Returns:

An element from the raw vector

getSegmentCount

public abstract int getSegmentCount()

Returns the number of elements in the raw vector representation of this version.

Returns:

The number of elements in the raw vector.

isOSGiCompatible

public abstract boolean isOSGiCompatible()

Checks if this version is in compliance with the OSGi version spec.

Returns:

A flag indicating whether the version is OSGi compatible or not.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

toString

public abstract void toString(java.lang.StringBuffer sb)

Appends the string representation of this version onto the sb StringBuffer.

Parameters:

sb - The buffer that will receive the version string