net.sf.mmm.util.version.api

Interface VersionIdentifier

All Superinterfaces:

AttributeReadValue<String>, Comparable<VersionIdentifier>, Datatype, Serializable, SimpleDatatype<String>

All Known Implementing Classes:

AbstractVersionIdentifier, VersionIdentifierImpl

public interface VersionIdentifier
extends Comparable<VersionIdentifier>, SimpleDatatype<String>

A VersionIdentifier is a version identifying a particular state of an object under version control. Such object can be an atomic asset like a single file but also a complex composition of many input artifacts like an entire software product.

Since:

3.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Field Summary

Fields

Modifier and Type	Field and Description
static int	COMPARE_TO_INCOMPARABLE
static int	COMPARE_TO_STRICT_PREDECESSOR The inverse relation to COMPARE_TO_STRICT_SUCCESSOR.
static int	COMPARE_TO_STRICT_SUCCESSOR This value indicates that a VersionIdentifier is a strict successor of another VersionIdentifier.
static String	SNAPSHOT The default indicator for a snapshot version.
static int	VERSION_SEGMENT_INDEX_MAJOR The segment index of the major version number.
static int	VERSION_SEGMENT_INDEX_MICRO The segment index of the micro version number.
static int	VERSION_SEGMENT_INDEX_MILLI The segment index of the milli version number.
static int	VERSION_SEGMENT_INDEX_MINOR The segment index of the minor version number.
static int	VERSION_SEGMENT_INDEX_NANNO The segment index of the nanno version-number.
static int	VERSION_SEGMENT_INDEX_PICO The segment index of the pico version number.

Method Summary

Modifier and Type	Method and Description
int	compareTo(VersionIdentifier otherVersion) This method determines a (non-linear) distance from this version to the given otherVersion.
String	getLabel() This method gets the optional label of the VersionIdentifier.
DevelopmentPhase	getPhase() This method gets the DevelopmentPhase of this VersionIdentifier.
String	getPhaseAlias() This method gets the string representation of the phase for this VersionIdentifier.
Integer	getPhaseNumber() This method gets the subsequent number of this VersionIdentifier within a particular phase.
Long	getRevision() This method gets the revision of the VersionIdentifier.
Date	getTimestamp() This method gets the timestamp of the VersionIdentifier.
int	getVersionMajorSegment() This method gets the major segment of this VersionIdentifier.
int	getVersionMicroSegment() This method gets the micro segment of this VersionIdentifier.
int	getVersionMilliSegment() This method gets the milli segment of this VersionIdentifier.
int	getVersionMinorSegment() This method gets the minor segment of this VersionIdentifier.
int	getVersionSegment(int index) This method gets an arbitrary segment of the version number.
int	getVersionSegmentCount() This method gets the number of segments of this VersionIdentifier .
boolean	isSnapshot() This method determines if this VersionIdentifier indicates a snapshot release.
String	toString() This method gets a unique string representation of this VersionIdentifier.

Methods inherited from interface net.sf.mmm.util.lang.api.SimpleDatatype

getValue

Field Detail

SNAPSHOT

static final String SNAPSHOT

The default indicator for a snapshot version.

See Also:

Constant Field Values

COMPARE_TO_STRICT_SUCCESSOR

static final int COMPARE_TO_STRICT_SUCCESSOR

This value indicates that a VersionIdentifier is a strict successor of another VersionIdentifier. A strict successor of VersionIdentifier V1 is a VersionIdentifier V2 that identifies a potential next release after V1.
ATTENTION:
An implementation can NOT predict the version history of a particular artifact. Therefore this is only an indicator whether a VersionIdentifier is a legal successor.
E.g. for the version "1.2.3-RC4" strict successors are "1.2.3-RC5", "1.2.3-GA", "1.2.4", etc. while "1.2.3-RC6" or "1.2.4-RC2" are NOT.

See Also:

compareTo(VersionIdentifier), Constant Field Values

COMPARE_TO_STRICT_PREDECESSOR

static final int COMPARE_TO_STRICT_PREDECESSOR

The inverse relation to COMPARE_TO_STRICT_SUCCESSOR.

See Also:

Constant Field Values

COMPARE_TO_INCOMPARABLE

static final int COMPARE_TO_INCOMPARABLE

See Also:

compareTo(VersionIdentifier), Constant Field Values

VERSION_SEGMENT_INDEX_MAJOR

static final int VERSION_SEGMENT_INDEX_MAJOR

The segment index of the major version number.

See Also:

Constant Field Values

VERSION_SEGMENT_INDEX_MINOR

static final int VERSION_SEGMENT_INDEX_MINOR

The segment index of the minor version number.

See Also:

Constant Field Values

VERSION_SEGMENT_INDEX_MILLI

static final int VERSION_SEGMENT_INDEX_MILLI

The segment index of the milli version number.

See Also:

Constant Field Values

VERSION_SEGMENT_INDEX_MICRO

static final int VERSION_SEGMENT_INDEX_MICRO

The segment index of the micro version number.

See Also:

Constant Field Values

VERSION_SEGMENT_INDEX_NANNO

static final int VERSION_SEGMENT_INDEX_NANNO

The segment index of the nanno version-number.

See Also:

Constant Field Values

VERSION_SEGMENT_INDEX_PICO

static final int VERSION_SEGMENT_INDEX_PICO

The segment index of the pico version number.

See Also:

Constant Field Values

Method Detail

getVersionSegment

int getVersionSegment(int index)
               throws IndexOutOfBoundsException

This method gets an arbitrary segment of the version number. The version number is a part of the VersionIdentifier represented by the concatenation of all segments separated by a separator (typically the dot sign).
This method will return 0 if a segment is not available. However it will not throw an IndexOutOfBoundsException if the index is non negative.
Here are some examples

version number	getVersionSegmentCount()	index	getSegment(index)
1.2.3.42	4	0	1
1.2.3.42	4	3	42
1.2.3.42	4	4	0
4.0	2	0	4
4.0	2	1	0
4.0	2	2	0
4.0	2	3	0

E.g. if the version number is "1.2.3.42", then getSegment()

Parameters:

index - is the 0-based index of the requested segment. It shall not be negative.

Returns:

the requested segment. If not available (in other words if index is greater or equal to getVersionSegmentCount()) the value 0 is returned.

Throws:

IndexOutOfBoundsException - if the given index is negative.

See Also:

VERSION_SEGMENT_INDEX_MAJOR, VERSION_SEGMENT_INDEX_MINOR, VERSION_SEGMENT_INDEX_MILLI, VERSION_SEGMENT_INDEX_MICRO, VERSION_SEGMENT_INDEX_NANNO, VERSION_SEGMENT_INDEX_PICO

getVersionSegmentCount

int getVersionSegmentCount()

This method gets the number of segments of this VersionIdentifier .

Returns:

the number of segments.

getVersionMajorSegment

int getVersionMajorSegment()

This method gets the major segment of this VersionIdentifier. This is the most significant segment of the version. It only gets updated on significant functional and/or structural changes of the versioned artifact. An upgrade can cause appreciable manual effort and will often cause compatibility problems and require migration of data or configuration.

Returns:

the major version segment.

See Also:

VERSION_SEGMENT_INDEX_MAJOR

getVersionMinorSegment

int getVersionMinorSegment()

This method gets the minor segment of this VersionIdentifier. This is the second most significant segment of the version. It only gets updated on functional and/or structural changes of the versioned artifact. An upgrade should be supported but may cause compatibility problems and require migration of data or configuration.

Returns:

the minor version segment.

See Also:

VERSION_SEGMENT_INDEX_MINOR

getVersionMilliSegment

int getVersionMilliSegment()

This method gets the milli segment of this VersionIdentifier. This is the third most significant segment of the version. It only gets updated on small functional and/or structural changes of the versioned artifact. An upgrade should not cause problems but needs to be tested.

Returns:

the milli version segment.

See Also:

VERSION_SEGMENT_INDEX_MILLI

getVersionMicroSegment

int getVersionMicroSegment()

This method gets the micro segment of this VersionIdentifier. This is the fourth most significant segment of the version. It only gets updated on small internal changes (e.g. bugfixes) of the versioned artifact. An upgrade should not cause problems.

Returns:

the milli version segment.

See Also:

VERSION_SEGMENT_INDEX_MICRO

getPhase

DevelopmentPhase getPhase()

This method gets the DevelopmentPhase of this VersionIdentifier.
ATTENTION:
If the phase is undefined (null), DevelopmentPhase.RELEASE will be assumed for compareTo(VersionIdentifier).

Returns:

the DevelopmentPhase or null if NOT defined.

getPhaseAlias

String getPhaseAlias()

This method gets the string representation of the phase for this VersionIdentifier. This is ideally getPhase().toString() but may also be any other legal alias for the phase.
E.g. for DevelopmentPhase.RELEASE the phase name may also be "final", "GA", "RTM", "REL", "gold", or "stable".

Returns:

the alias of the phase.

getPhaseNumber

Integer getPhaseNumber()

This method gets the subsequent number of this VersionIdentifier within a particular phase. It is typically null and will then be omitted in the string-representation. However release-candidates and updates are often numbered (e.g. like "u1", "u2", ... in Java-releases or "RC1"/"SR1", ... in Eclipse-releases).
If getPhase() returns null also this method should return null. Also if getPhase() is DevelopmentPhase.RELEASE this method should return null (there is just one official release - after that there are updates).
ATTENTION:
If the phase is undefined (null), 0 will be assumed for compareTo(VersionIdentifier).

Returns:

the phase number or null if NOT defined.

isSnapshot

boolean isSnapshot()

This method determines if this VersionIdentifier indicates a snapshot release. A snapshot is an informal pre-release. Multiple snapshot releases with different content can be published for snapshot versions while this is strictly prohibited for non-snapshot versions. A snapshot version is a strict predecessor of the same VersionIdentifier without the snapshot.
E.g. multiple "1.0.0-SNAPSHOT" versions can be published for testers. After all tests pass, the version "1.0.0" gets released. This approach is orthogonal to the phase and can be combined (e.g. "1.0.0-beta2-SNAPSHOT").

Returns:

true if this VersionIdentifier represents a snapshot release, false in case of an official release.

getRevision

Long getRevision()

This method gets the revision of the VersionIdentifier. It typically has a technical nature and might be derived from the underlying version control system.

Returns:

the revision or null if NOT defined.

getTimestamp

Date getTimestamp()

This method gets the timestamp of the VersionIdentifier. It indicates the point in time when this VersionIdentifier was assigned to the associated object. The timestamp may also called release date. The value is optional but is best practice to assign a timestamp to a VersionIdentifier.

Returns:

the timestamp or null if NOT defined.

getLabel

String getLabel()

This method gets the optional label of the VersionIdentifier. A label is a non-technical identifier also called code name (e.g. "Tiger" or "Dolphin").

Returns:

the label or null if NOT defined.

compareTo

int compareTo(VersionIdentifier otherVersion)

This method determines a (non-linear) distance from this version to the given otherVersion. It will return

• COMPARE_TO_INCOMPARABLE if both versions are incompatible to each other (e.g. ).
• 0 if both versions are historically equivalent (but may NOT be equal)
• a negative value if this version is a predecessor of otherVersion. The value -1 indicates a strict predecessor.
• a positive value if this version is a successor of otherVersion. The value +1 indicates a strict successor.

The following table gives some examples:

version	otherVersion	version.compareTo(otherVersion)
1.0.0-SNAPSHOT	1.0.0-SNAPSHOT	0
1.0.0	1.0.0-SNAPSHOT	1 (COMPARE_TO_STRICT_SUCCESSOR)
1.0.1	1.0.0	1 (COMPARE_TO_STRICT_SUCCESSOR)
1.0.1	1.0.0-SNAPSHOT	>1
1.6.0u23	1.6.0u24	-1 (COMPARE_TO_STRICT_PREDECESSOR)
3.7-SR1-indigo	4.1.1-201109121510	<-1
3.7.1-helios	3.7.1-indigo	COMPARE_TO_INCOMPARABLE
1.0-20000101T000000Z	1.0-19991231T235959Z	COMPARE_TO_INCOMPARABLE
1.0-20000101T000000Z	1.1-19991231T235959Z	COMPARE_TO_INCOMPARABLE

Specified by:

compareTo in interface Comparable<VersionIdentifier>

toString

String toString()

This method gets a unique string representation of this VersionIdentifier. Returns the official String representation of this Datatype. While the general contract of Object.toString() is very weak and mainly used for debugging, the contract here is very strong. The returned String has to be suitable for end-users and official output to any kind of sink.
ATTENTION:
This method is not supposed to do internationalization (I18N). See NlsMessage for this purpose and implement NlsObject if you want to support I18N/L10N.

Specified by:

toString in interface Datatype

Overrides:

toString in class Object

Returns:

the official String representation to display the value of this Datatype.