com.ptc.windchill.instassm
Class ReleaseId

java.lang.Object
  com.ptc.windchill.instassm.ReleaseId

All Implemented Interfaces:

Comparable

public class ReleaseId

extends Object

implements Comparable

A ReleaseId is an assembly name plus set of five numbers that looks like: assmbly-id.major.minor.servicePack.dsu.build.

Assembly names (or ids) are short strings that match the regular expression:

    [a-zA-Z][a-zA-Z0-9]+

While they are not constrained in length they should be three or four characters long. Assembly ids should be treated as case-insensitive strings in all comparisons.

The version class is Comparable. Versions are expected be monotonically increasing over time for a given assembly id where each field is compared placing greater significance on the fields to the left. Thus:

     wnc.2.0.0.0.0 > wnc.1.0.0.0.0
     wnc.1.1.0.0.0 > wnc.1.0.0.0.0
     wnc.1.1.1.0.0 > wnc.1.1.0.0.0
     wnc.1.1.1.1.0 > wnc.1.1.1.0.0
     wnc.1.1.1.1.1 > wnc.1.1.1.1.1
 

Versions with different assembly ids will always report inequality via the equals method. However, if the compareTo() methods are used, the assembly ids will be compared lexicographically and then the version numbers will be compared left-to-right.

Background on a Format Change

Prior to 6.2.3 version numbers did not have an assembly id. They were added to allow for differing release rates of the Windchill Platform and each Solution that depends on the Platform.

Prior to Windchill 6.2 versions were major.minor.dsu.build. ServicePack number was added during the 6.0 maintenance cycle. Because there was a need to support specification of service pack level in 6.0 and Version did not have the extra field, the dsu part was encoded with the service pack number times 1000. So 6.2 service pack 1 DSU 3 would look like 6.2.1003.

Also prior to Windchill 6.2 versions were allowed to be specified with fewer than four numbers. Doing so would result in a version that only contains the specified numbers. Now five numbers are required in the string representation of a version. Thus all versions will in string form will have five fields, with zeros for fields that are not specified. For example, if you create a version with Version.createFrom("6.2"), the string form of this version will be 6.2.0.0.0.

6.2-to-6.2.3Backward Compatibility(String Representation)

For backward compatibility all version numbers are automatically assigned the wnc assembly id, unless a AssemblyIdResolver is provided to the createFrom(String,AssemblyResolver) method. The AssemblyIdResolver will be given an opportunity to determine an alternative assembly id through whatever means it chooses.

Pre-6.2 Backward Compatibility(String Representation)

Versions that are specified without all five fields are assumed to not contain the service pack value. If the dsu value is specified and is contains an encoded service pack number, then the service pack number will be set by dividing the dsu number by 1000, and the dsu number will be set by mod'ing the dsu number with 1000.

If a five digit number is specified, each field is interpreted verbatim. No decoding will occur.

Whenever possible, code should not manipulate version strings directly. Rather, it should create a Version instance from the String and use the Version instead.

6.2-to-6.2.3 Backward Compatibility(XML Representation)

As of 6.2 version numbers should be stored in a single string as an attribute or text element. Therefore, backward compatibility is the same as when parsing version in their string representation.

Pre-6.2 Backward Compatibility(XML Representation)

The Version class has always been able to "read" and "write" itself as a DOM Element. The representation for this element was:

where the element name could be tailored if desired, and the minor, micro, and build attributes weren't required.

Because of the change in version number representation, the XML structure has been changed. Rather than add another attribute for service pack, versions will now be represented in the format:

where the version's string representation is in the number attribute. This has been don't to reduce coupling between version number format and the XML structure, allowing us more room in the future to handle format changes.

The current version class can handle decoding XML Elements in either form. So as long as code that uses XML version represetations always creates a ReleaseId instance from the Element and uses the ReleaseId class rather than directly querying the Element, this code will be isolated from format changes.

Example Mappings

    1             =>  wnc.1.0.0.0.0
    1.2           =>  wnc.1.2.0.0.0
    1.2.3         =>  wnc.1.2.0.3.0
    1.2.3.4       =>  wnc.1.2.0.3.4
    1.2.3.4.5     =>  wnc.1.2.3.4.5
    1.2.3004      =>  wnc.1.2.3.4.0
    1.2.3004.5    =>  wnc.1.2.3.4.5
    1.2.0.3004.5  =>  wnc.1.2.0.3004.5
    1.2.6.3004.5  =>  wnc.1.2.6.3004.5
 

Important Note

The version 6.0.2 is always treated as 6.0.0.1000.0 / 6.0.1.0.0. This is because it was meant to be a service pack. However, the service pack-numbering scheme could not be introduced because the version classes were unable to handle numbers of 1000 or greater properly. There wasn't sufficient time to correct the problem for the 6.0 service pack 1 release, so it's version number was changed to 6.0.2.0 even though this release wasn't a DSU release. The problem was corrected immediately, and support for automatically mapping from 6.0.2 to 6.0.1.0.0 was added to later product versions, giving the appearances of correct numbering and preventing future problems.

Supported API: true

Extendable: false

See Also:

createFrom(java.lang.String), createFrom(org.w3c.dom.Element)

Nested Class Summary

static interface

ReleaseId.AssemblyIdResolver Produce an assembly id for a release identifier that contains no assembly id.

Field Summary

private String	assemblyId_
private int	build_
private Integer	cachedHashCode_
private static String	CLASSNAME
private String	dateCode_
private int	dsu_
private int	major_
private int	minor_
static ReleaseId	NEGATIVE_INFINITY
static String	NUMBER_ATTR
private static String	OLD_BUILD_ATTR
private static String	OLD_MAJOR_ATTR
private static String	OLD_MICRO_ATTR
private static String	OLD_MINOR_ATTR
static ReleaseId	POSITIVE_INFINITY
private String	releaseIdentifier_
private static String	RESOURCE
private int	servicePack_
private String	shortenedReleaseIdComponent_
private static DecimalFormat	twoPadFormat__
(package private) static String	VERSION_SEPARATOR
static String	VERSION_TAG
private String	versionComponent_
private static ReleaseId.AssemblyIdResolver	WNC_ASSEMBLY_ID_RESOLVER
private static Integer	ZERO

Constructor Summary

private	ReleaseId() Constructor to support infinities.
	ReleaseId(String assembly_id, Integer major, Integer minor, Integer service_pack, Integer dsu, Integer build) Constructs a version from all numeric values Supported API: true Extendable: false
	ReleaseId(String assembly_id, int major, int minor, int service_pack, int dsu, int build) Supported API: true Extendable: false

Method Summary

Element	asDOM(Document doc) Creates a Element and sets its attributes to this ReleaseId's values.
Element	asDOM(Document doc, String element_name) Creates a Element and sets its attributes to this ReleaseId's values.
private static int	asIntZeroIfNull(Integer value)
private static int	compareIntValues(int source, int target)
int	compareTo(Object other_) Compares the argument to this ReleaseId.
int	compareTo(ReleaseId other) Compares the argument to this ReleaseId.
static ReleaseId	createFrom(Element element) Constructs a ReleaseId object from a DOM element.
static ReleaseId	createFrom(String version_string) Constructs a ReleaseId object from a String.
static ReleaseId	createFrom(String version_string, ReleaseId.AssemblyIdResolver assm_id_resolver) Constructs a ReleaseId object from a String.
boolean	equals(Object other) Returns true if the argument is a ReleaseId object and have equal major, minor, dsu, and build levels.
String	getAssemblyId() Returns the assembly identifier.
private static String	getAttr(Element element, String attr_name, String fallback_value) Gets from the provided element the named attribute, returning the fallback value if the attribute is missing or is an empty string.
int	getBuild() Returns the build number.
private int	getCombinedSpAndDsu()
int	getDsu() Returns the dsu number.
int	getMajor() Returns the major number.
int	getMinor() Returns the minor number.
String	getReleaseIdComponent() Returns the version.
int	getServicePack() Returns the service pack number.
String	getShortenedMajorMinorServicePackComponent() Returns the sortened version which is the concatenation of just the major and minor verison numbers separated by period.
String	getShortenedReleaseIdComponent() Returns the sortened version which is the concatenation of the major, minor, and dsu without the build number separated by periods and stripping any insignificant zeros off of the right-hand portion of the string.
String	getThreePartVersionString() Returns the first three parts of the version number.
String	getTwoPartVersionString() Returns the first two parts of the version number.
static String	getVersionSeparator()
boolean	hasAssemblyId(String assembly_id) Compares the ReleaseId's assembly id to that passed in as a parameter.
int	hashCode() Supported API: true Extendable: false
boolean	hasSameAssemblyIdAs(ReleaseId other_version) Compares the ReleaseId's assembly id to that of the other version.
static void	main(String[] args) Usage: java -cp /Windchill/srclib/CommonCore.jar com.ptc.windchill.instassm.ReleaseId <release_id> ...
String	toString() returns a String representation of this ReleaseId.
private String	twoPad(int number)
private static void	validateAssemblyId(String potential_assembly_id)

Methods inherited from class java.lang.Object

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

Field Detail

twoPadFormat__

private static final DecimalFormat twoPadFormat__

ZERO

private static final Integer ZERO

VERSION_SEPARATOR

static final String VERSION_SEPARATOR

See Also:

Constant Field Values

VERSION_TAG

public static final String VERSION_TAG

See Also:

Constant Field Values

NUMBER_ATTR

public static final String NUMBER_ATTR

See Also:

Constant Field Values

OLD_MAJOR_ATTR

private static final String OLD_MAJOR_ATTR

See Also:

Constant Field Values

OLD_MINOR_ATTR

private static final String OLD_MINOR_ATTR

See Also:

Constant Field Values

OLD_MICRO_ATTR

private static final String OLD_MICRO_ATTR

See Also:

Constant Field Values

OLD_BUILD_ATTR

private static final String OLD_BUILD_ATTR

See Also:

Constant Field Values

RESOURCE

private static final String RESOURCE

See Also:

Constant Field Values

CLASSNAME

private static final String CLASSNAME

POSITIVE_INFINITY

public static final ReleaseId POSITIVE_INFINITY

NEGATIVE_INFINITY

public static final ReleaseId NEGATIVE_INFINITY

WNC_ASSEMBLY_ID_RESOLVER

private static final ReleaseId.AssemblyIdResolver WNC_ASSEMBLY_ID_RESOLVER

assemblyId_

private String assemblyId_

major_

private int major_

minor_

private int minor_

servicePack_

private int servicePack_

dsu_

private int dsu_

build_

private int build_

releaseIdentifier_

private String releaseIdentifier_

dateCode_

private String dateCode_

cachedHashCode_

private Integer cachedHashCode_

versionComponent_

private String versionComponent_

shortenedReleaseIdComponent_

private String shortenedReleaseIdComponent_

Constructor Detail

ReleaseId

private ReleaseId()

Constructor to support infinities.

ReleaseId

public ReleaseId(String assembly_id,
                 Integer major,
                 Integer minor,
                 Integer service_pack,
                 Integer dsu,
                 Integer build)
          throws ReleaseIdException

Constructs a version from all numeric values

Supported API: true

Extendable: false

Parameters:

assembly_id - String

major - Integer

minor - Integer

service_pack - Integer

dsu - Integer

build - Integer

Throws:

ReleaseIdException

ReleaseId

public ReleaseId(String assembly_id,
                 int major,
                 int minor,
                 int service_pack,
                 int dsu,
                 int build)
          throws ReleaseIdException

Supported API: true

Extendable: false

Method Detail

getVersionSeparator

public static final String getVersionSeparator()

asIntZeroIfNull

private static final int asIntZeroIfNull(Integer value)

getAssemblyId

public final String getAssemblyId()

Returns the assembly identifier.

Supported API: true

Extendable: false

Returns:

a non-null String

hasAssemblyId

public final boolean hasAssemblyId(String assembly_id)

Compares the ReleaseId's assembly id to that passed in as a parameter.

Returns:

true if they are the same string ignoring case.

hasSameAssemblyIdAs

public final boolean hasSameAssemblyIdAs(ReleaseId other_version)

Compares the ReleaseId's assembly id to that of the other version.

Returns:

true if they are the same string ignoring case.

getReleaseIdComponent

public final String getReleaseIdComponent()

Returns the version. A version is the concatenation of the major, minor, dsu, and build levels, separated by periods. If the version is 6.2.x then the value could be four parts and include the service pack and DSU as separate fields. If major.minor is anything else, then the service pack and DSU will be combined into a single number.

Supported API: true

Extendable: false

Returns:

non-null String in the form of "major.minor.servicePack.dsu.build", e.g. 6.1.01.01

getCombinedSpAndDsu

private int getCombinedSpAndDsu()

getShortenedReleaseIdComponent

public final String getShortenedReleaseIdComponent()

Returns the sortened version which is the concatenation of the major, minor, and dsu without the build number separated by periods and stripping any insignificant zeros off of the right-hand portion of the string. If the version is 6.2.x then the value could be four parts and include the service pack and DSU as separate fields. If major.minor is anything else, then the service pack and DSU will be combined into a single number.

Supported API: true

Extendable: false

Returns:

non-null String

getTwoPartVersionString

public final String getTwoPartVersionString()

Returns the first two parts of the version number.

Supported API: true

Extendable: false

Returns:

non-null String

getThreePartVersionString

public final String getThreePartVersionString()

Returns the first three parts of the version number. The third number will ALWAYS be the combined servicepack-DSU value.

Supported API: true

Extendable: false

Returns:

non-null String

getShortenedMajorMinorServicePackComponent

public final String getShortenedMajorMinorServicePackComponent()

Returns the sortened version which is the concatenation of just the major and minor verison numbers separated by period. The minor number will be stripped if it is zero.

Supported API: true

Extendable: false

Returns:

non-null String

getMajor

public final int getMajor()

Returns the major number.

Supported API: true

Extendable: false

Returns:

a value greater than or equal to zero

getMinor

public final int getMinor()

Returns the minor number.

Supported API: true

Extendable: false

Returns:

a value greater than or equal to zero

getServicePack

public final int getServicePack()

Returns the service pack number.

Supported API: true

Extendable: false

Returns:

a value greater than or equal to zero

getDsu

public final int getDsu()

Returns the dsu number.

Supported API: true

Extendable: false

Returns:

a value greater than or equal to zero

getBuild

public final int getBuild()

Returns the build number.

Supported API: true

Extendable: false

Returns:

a value greater than or equal to zero

toString

public String toString()

returns a String representation of this ReleaseId. If the version is 6.2.x then the value of the service pack and DSU will be output as separate fields (e.g. wnc.6.2.6.0.20). Otherwise, the service pack and DSU numbers will be combined into a single number (e.g. 6.1.1001.5).

Supported API: true

Extendable: false

Returns:

a non-null String

hashCode

public int hashCode()

Supported API: true

Extendable: false

equals

public boolean equals(Object other)

Returns true if the argument is a ReleaseId object and have equal major, minor, dsu, and build levels.

Supported API: true

Extendable: false

Returns:

boolean true if the both ReleaseIds have equal version Strings

compareTo

public int compareTo(Object other_)

Compares the argument to this ReleaseId. If they are equal, return zero. If this ReleaseId is less than the argument, returns a negative number. If this ReleaseId is greater than the argument, returns a positive number. If other_ is not a ReleaseId instance, returns -1.

Supported API: true

Extendable: false

Specified by:

compareTo in interface Comparable

Parameters:

other_ - Object ReleaseId to be compared with this.

Returns:

int

compareTo

public int compareTo(ReleaseId other)

Compares the argument to this ReleaseId.

Parameters:

other - ReleaseId ReleaseId to be compared with this.

Returns:

If they are equal, return zero. If this ReleaseId is less than the argument, returns a negative number. If this ReleaseId is greater than the argument, returns a positive number.

compareIntValues

private static final int compareIntValues(int source,
                                          int target)

asDOM

public Element asDOM(Document doc)

Creates a Element and sets its attributes to this ReleaseId's values.

Parameters:

doc - w3c.org.dom.Document The document used to instantiate the Element.

Returns:

an element containing each version number part as an attribute

Supported API: false

Extendable: false

asDOM

public Element asDOM(Document doc,
                     String element_name)

Creates a Element and sets its attributes to this ReleaseId's values.

Supported API: false

Extendable: false

Parameters:

doc - w3c.org.dom.Document The document used to instantiate the Element.

element_name - String The String to be used for the element tag.

Returns:

w3c.org.doc.Element

createFrom

public static ReleaseId createFrom(Element element)
                            throws ReleaseIdException

Constructs a ReleaseId object from a DOM element. Examples: => 1.2.4.0.3 => 1.2.0.0.3 => 1.2.0.0.3 => 1.0.0.0.3 => 1.2.3.4.0 => 1.2.5.3004.0

Supported API: false

Extendable: false

Returns:

ReleaseId

Throws:

ReleaseIdException

getAttr

private static String getAttr(Element element,
                              String attr_name,
                              String fallback_value)

Gets from the provided element the named attribute, returning the fallback value if the attribute is missing or is an empty string.

createFrom

public static final ReleaseId createFrom(String version_string)
                                  throws ReleaseIdException

Constructs a ReleaseId object from a String. Assembly id will be wnc if it is not specified in the string.

Supported API: true

Extendable: false

Parameters:

version_string - String Non-null string in any of the acceptable forms(see class javadocs)

Returns:

a non-null ReleaseId

Throws:

ReleaseIdException - if version_string is not in an acceptable form

createFrom

public static final ReleaseId createFrom(String version_string,
                                         ReleaseId.AssemblyIdResolver assm_id_resolver)
                                  throws ReleaseIdException

Constructs a ReleaseId object from a String. Assembly id will obtained from the AssemblyIdResolver if it is not specified in the string.

Supported API: false

Extendable: false

Parameters:

version_string - String Non-null string in any of the acceptable forms(see class javadocs)

Returns:

a non-null ReleaseId

Throws:

ReleaseIdException - if version_string is not in an acceptable form

validateAssemblyId

private static final void validateAssemblyId(String potential_assembly_id)
                                      throws ReleaseIdException

Throws:

ReleaseIdException

twoPad

private final String twoPad(int number)

main

public static void main(String[] args)

Usage: java -cp /Windchill/srclib/CommonCore.jar com.ptc.windchill.instassm.ReleaseId <release_id> ... 

Example: java -cp /Windchill/srclib/CommonCore.jar com.ptc.windchill.instassm.ReleaseId wnc.7.0.2 7.1.0.3.4