com.virtuosotechnologies.lib.plugin
Class APIVersion

java.lang.Object
  extended bycom.virtuosotechnologies.lib.plugin.APIVersion
All Implemented Interfaces:
Comparable, Comparator

public class APIVersion
extends Object
implements Comparator, Comparable

Version number of an API and API implementation.

The version has the form major.minor.impl. The three parts have well-defined semantics as follows.

For example, a client may request version 1.2 of a particular API. That client should be compatible with an implementation of version 1.2.0, 1.2.1, or 1.3.0, but not 1.1.0 or 2.0.0. A client may also request a particular minimum implementation version, by requesting version 1.2.2 for example. (This may be because, for example, it knows that earlier implementations have bugs that affect its operation.) That client would then be compatible with implementation version 1.2.2, 1.2.3 or 1.3.0, but not 1.2.1.

There is also a notion of "how well" an implementation version fits a client's request. Minor revisions closer to the requested revision are better fits, and later implementation versions are considered better fits. For example, if version 1.2.2 is requested then implementation 1.2.5 is a better fit than either implementations 1.3.5 or 1.2.2. This "fit quality" can be queried by using the request APIVersion as a Comparator for implementation APIVersions.


Constructor Summary
APIVersion(int majorVersion, int minorVersion)
          Constructor.
APIVersion(int majorVersion, int minorVersion, int implVersion)
          Constructor
 
Method Summary
 int compare(Object obj1, Object obj2)
          Implementation of Comparator.
 int compareTo(Object obj)
          Implementation of Comparable.
 boolean equals(Object obj)
          equals
 APIVersion getBestProvidingVersion(Collection collection)
          Get the APIVersion out of a Collection that best provides what this version requests.
 int hashCode()
          hashCode
 boolean isSatisfiedBy(APIVersion provider)
          Is this version satisfied by the given provider?
static APIVersion parse(String str)
          Parse from a string.
 String toString()
          Unparses the version to a string form suitable for reparsing using the parse() method.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

APIVersion

public APIVersion(int majorVersion,
                  int minorVersion,
                  int implVersion)
Constructor

Parameters:
majorVersion - major version number
minorVersion - minor version number
implVersion - implementation version number

APIVersion

public APIVersion(int majorVersion,
                  int minorVersion)
Constructor. Automatically uses an implementation version of 0.

Parameters:
majorVersion - major version number
minorVersion - minor version number
Method Detail

isSatisfiedBy

public boolean isSatisfiedBy(APIVersion provider)
Is this version satisfied by the given provider? That is, if this APIVersion is a request, and the given provider is suggested, is it compatible?

Parameters:
provider - the provided API version
Returns:
true if it is compatible

compareTo

public int compareTo(Object obj)
Implementation of Comparable. This establishes a canonical ordering of version numbers.

Specified by:
compareTo in interface Comparable
Parameters:
obj - other object
Throws:
ClassCastException - one of the parameters is not an APIVersion.

compare

public int compare(Object obj1,
                   Object obj2)
Implementation of Comparator. This allows APIVersions to "rate" other APIVersions on how well they do or do not provide what this version requests. This implementation is consistent with equals(). That is, if this returns 0 for two values obj1 and obj2, then obj1.equals(obj2). Generally, this is only useful when isSatisfiedBy both obj1 and obj2, to determine which provider is better suited. However, it is well-defined for other cases.

Specified by:
compare in interface Comparator
Parameters:
obj1 - first object
obj2 - second object
Returns:
a positive integer if obj1 is better, a negative integer if obj2 is better, or 0 if they are equivalent
Throws:
ClassCastException - one of the parameters is not an APIVersion.

getBestProvidingVersion

public APIVersion getBestProvidingVersion(Collection collection)
Get the APIVersion out of a Collection that best provides what this version requests. Returns null if no version is compatible.

Parameters:
collection - collection of APIVersions
Returns:
the best providing version, or null if no version is compatible

parse

public static APIVersion parse(String str)
Parse from a string. Well-formed version numbers will be of the form major.minor.impl or the form major.minor

Parameters:
str - string to parse
Returns:
the APIVersion, or null if couldn't parse

equals

public boolean equals(Object obj)
equals

Specified by:
equals in interface Comparator
Parameters:
obj - object to compare to
Returns:
true if equal

hashCode

public int hashCode()
hashCode

Returns:
hash code

toString

public String toString()
Unparses the version to a string form suitable for reparsing using the parse() method.

Returns:
string representation