net.sf.mmm.util.version.api

Interface VersionUtil

All Known Implementing Classes:

VersionUtilImpl

@ComponentSpecification
public interface VersionUtil

This is the interface for a collection of utility functions that help to deal with versions. E.g. you can parse a a version String to a VersionIdentifier.

Since:

3.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Method Summary

Modifier and Type	Method and Description
VersionIdentifierFormatter	createFormatter(String formatPattern) Variant of createFormatter(String, boolean) with strict mode.
VersionIdentifierFormatter	createFormatter(String formatPattern, boolean strict) This method creates a VersionIdentifierFormatter for the given formatPattern.
VersionIdentifier	createVersionIdentifier(String versionString) This method parses the given versionString and builds an according VersionIdentifier instance.
VersionIdentifier	createVersionIdentifier(String versionString, boolean normalizeFormat) This method parses the given versionString and builds an according VersionIdentifier instance.
VersionIdentifierFormatter	getDefaultFormatter()

Method Detail

createVersionIdentifier

VersionIdentifier createVersionIdentifier(String versionString)
                                   throws NlsParseException

This method parses the given versionString and builds an according VersionIdentifier instance. It delegates to createFormatter(String, boolean) using false for normalizeFormat.

Parameters:

versionString - is the string representation of a VersionIdentifier.

Returns:

the parsed VersionIdentifier.

Throws:

NlsParseException - if the given versionString is invalid and could not be parsed.

createVersionIdentifier

VersionIdentifier createVersionIdentifier(String versionString,
                                          boolean normalizeFormat)
                                   throws NlsParseException

This method parses the given versionString and builds an according VersionIdentifier instance.

Parameters:

versionString - is the string representation of a VersionIdentifier.

normalizeFormat - - if true the returned VersionIdentifier will return a normalized string representation that may differ from the given versionString. Otherwise the original versionString will be used.

Returns:

the parsed VersionIdentifier.

Throws:

NlsParseException - if the given versionString is invalid and could not be parsed.

getDefaultFormatter

VersionIdentifierFormatter getDefaultFormatter()

Returns:

the default VersionIdentifierFormatter.

Since:

6.0.0

createFormatter

VersionIdentifierFormatter createFormatter(String formatPattern)

Variant of createFormatter(String, boolean) with strict mode.

Parameters:

formatPattern - is the format string.

Returns:

the according VersionIdentifierFormatter.

See Also:

createFormatter(String, boolean)

createFormatter

VersionIdentifierFormatter createFormatter(String formatPattern,
                                           boolean strict)

This method creates a VersionIdentifierFormatter for the given formatPattern. Similar to SimpleDateFormat the format pattern is parsed and there are particular letter symbols that have a specific meaning.

letter	meaning	comment
V	version segments	Needs to be of the form V«separator»[{«min»,«max»,«padding»}] where «separator» is a character used to separate the version segments (typically the dot sign '.'). Further, «min» and «max» are the minimum and maximum number of segments to format and «padding» is the minimum number of digits to pad each segment.
P	phase	The official phase name - typically you want to use "A" instead. May be followed by {«max»} to limit (truncate) to a maximum number of characters.
A	alias	The phase alias. May be followed by {«max»} to limit (truncate) to a maximum number of characters.
N	phase number	The phase number. May be followed by {«padding»} to pad to a minimum number of digits.
S	snapshot indicator	The snapshot indicator. May be followed by {«indicator»} to override the default snapshot indicator with {«indicator»}.
L	label	The label. May be followed by {«max»} to limit (truncate) to a maximum number of characters.
R	revision	The revision. May be followed by {«padding»} to pad to a minimum number of digits.
T	timestamp	The timestamp by default in basic ISO-8601 format. May be followed by {«format»} to use the given format instead as SimpleDateFormat pattern (e.g. "T{yyyy-MM-dd}").

As all ASCII letters are reserved for existing letter symbol definitions (see table above) or further extensions, you need to enclose static text in braces (e.g. "(rev)" to represent the static String "rev" as infix for a format pattern).
Further, infix text (no matter if enclosed in braces or not) is omitted if the following letter symbol is resolved as undefined. To prevent this add the dollar character ($) to terminate a static infix that should always occur.

segment count	major	minor	milli	micro	phase	alias	phase number	snapshot	label	revision	timestamp	formatPattern	format
4	1	2	3	4	null	null	null	false	null	null	null	"V.-AN-S-L-(rev)R-T"	"1.2.3.4-GA"
4	1	2	3	4	"update"	"SR"	2	false	null	654321	null	"V.-AN-S-L-(rev)R-T"	"1.2.3.4-SR2-rev654321"
4	1	2	3	4	"update"	"SR"	2	true	kassiopeia	654321	31.12.1999 23:59:59 UTC	"V.-AN-S-L-(rev)R-T"	"1.2.3.4-SR2-SNAPSHOT-kassiopeia-rev654321-19991231T23:59:59Z"
4	1	2	3	4	"update"	"SR"	2	true	null	654321	31.12.1999 23:59:59 UTC	"V.{0,3,2}P{2}N{2}-S{snap}_$-L-(rev)R-T"	"01.02.03up02-snap_-rev654321-19991231T23:59:59Z"

Parameters:

formatPattern - is the format string.

strict - - if true then the given formatPattern has to include at least the version segments, the phase (in any form including alias), phase number, and snapshot.

Returns:

the according VersionIdentifierFormatter.