BundleIdentifier

public final class BundleIdentifier implements Comparable<BundleIdentifier>, Externalizable

saker.nest.bundle.BundleIdentifier

java.lang.Object

java.lang.Comparable<BundleIdentifier>

java.io.Externalizable

java.io.Serializable

Unique identifier in canonical format representing a bundle identifier in the Nest repository.

The class holds a canonicalized name of a bundle in the Nest repository. A bundle identifier consists of all lower-case parts which are the following:

Name: The name of the bundle. It contains one or more alphabetical (a-z), numeric (0-9), underscore (_) or dot (.) characters. In general, it should be in the some.bundle.name format, similar to Java package naming.
Qualifiers: Bundle qualifiers are arbitrary attributes attached to the bundle name. Qualifiers can contain the same characters as the name. They can be used to differentiate different bundles under the same enclosing bundle name.
Meta-qualifiers: Same as bundle qualifiers, but they are specially handled by the implementation. Currently the following bundle qualifiers are recognized:
- Bundle version: Version meta-qualifiers are in the format of v<num>[.<num>]*. They are used to distinguish different versions of the same bundles. It is ensured that a bundle identifier may contain either none, or at most one version qualifier.
  For more information about version numbers, see compareVersionNumbers(String, String).

The different parts of the bundle identifiers are display in a dash (-) separated form when normalized:

 some.bundle.name-q1-q2-v1.0

When a bundle identifer is constructed, its parts will be normalized, meaning that the order of qualifiers and meta qualifiers will not be kept, and they will be stored in alphabetical order. Duplicate qualifiers will be removed. This means that the following bundle identifiers are considered to be equal:

 some.bundle.name-q1-q2-v1.0
 some.bundle.name-q2-q1-v1.0
 some.bundle.name-q1-v1.0-q2-q1
 SOME.BuNdLe.name-Q1-q2-V1.0-q1

When bundle identifiers are converted back to string representation, they will have the following format:

 name[-qualifiers]*[-metaqualifiers]*

If there are not qualifiers, or no meta qualifiers, the separating dash character will be omitted.

Constructors

public	BundleIdentifier() For Externalizable.

Methods

public int	compareTo(BundleIdentifier o) Compares this object with the specified object for order.
public static int	compareVersionNumbers(String l, String r) Compares two version numbers in ascending order.
public static int	compareVersionQualifiers(String l, String r) Comparator function for two version qualifiers.
public boolean	equals(Object obj) Indicates whether some other object is "equal to" this one.
public NavigableSet<String>	getAllQualifiers() Gets all qualifiers in this bundle identifier.
public NavigableSet<String>	getBundleQualifiers() Gets the qualifier part of the bundle identifier.
public NavigableSet<String>	getMetaQualifiers() Gets the meta-qualifier part of the bundle identifier.
public String	getName() Gets the name part of the bundle identifier.
public String	getVersionNumber() Gets the version number in this bundle identifier if any.
public static int	getVersionNumberComponentCount(String version) Counts the number compontents in the argument version number.
public String	getVersionQualifier() Gets the version qualifier in this bundle identifier if any.
public static <S extends CharSequence> S	getVersionQualifier(Iterable<S> qualifiers) Utility function to retrieve the version qualifier from the argument qualifiers.
public static String	getVersionQualifierVersionNumberPart(String versionqualfier) Gets the version number part of a version qualifier argument.
public boolean	hasAnyQualifiers() Checks if this bundle identifier has any normal or meta qualifiers.
public boolean	hasMetaQualifiers() Checks if this bundle identifier has any meta qualifiers.
public boolean	hasNormalQualifiers() Checks if this bundle identifier has any normal qualifiers.
public static boolean	hasVersionQualifier(Iterable<? extends CharSequence> qualifiers) Utility function to check if the argument contains any valid version qualifiers.
public int	hashCode() Returns a hash code value for the object.
public static boolean	isMetaQualifier(String qualifier) Checks if the argument is a valid version qualifier recognized by this class.
public static boolean	isValidBundleIdentifier(String bundleidstr) Checks if the argument has a valid bundle identifier format.
public static boolean	isValidBundleName(String name) Checks if the argument is a valid bundle name.
public static boolean	isValidVersionNumber(String version) Checks if the argument string represents a valid version number.
public static boolean	isValidVersionQualifier(String qualifier) Checks if the argument has a valid version qualifier format.
public static String	makeVersionQualifier(String versionnum) Creates a new version qualifier.
public static String	nextVersionNumberInNaturalOrder(String version) Gets the strictly next version number that will compare to be greater than the argument.
public void	readExternal(ObjectInput in) The object implements the readExternal method to restore its contents by calling the methods of DataInput for primitive types and readObject for objects, strings and arrays.
public String	toString() Returns a string representation of the object.
public static BundleIdentifier	valueOf(String input) Converts the argument to a BundleIdentifier.
public BundleIdentifier	withoutAnyQualifiers() Gets a bundle identifier derived from `this` that doesn't contain any normal or meta qualifiers.
public BundleIdentifier	withoutMetaQualifiers() Gets a bundle identifier derived from `this` that doesn't contain any meta qualifiers.
public BundleIdentifier	withoutQualifiers() Gets a bundle identifier derived from `this` that doesn't contain any (normal) qualifiers.
public void	writeExternal(ObjectOutput out) The object implements the writeExternal method to save its contents by calling the methods of DataOutput for its primitive values or calling the writeObject method of ObjectOutput for objects, strings, and arrays.

Inherited methods
From: Object clone, finalize, getClass, notify, notifyAll, wait, wait, wait
From: Comparable<BundleIdentifier> compareTo

public BundleIdentifier()

For Externalizable.

public int compareTo(BundleIdentifier o)

Overridden from: Comparable

Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

The implementor must ensure sgn(x.compareTo(y)) == -sgn(y.compareTo(x)) for all x and y. (This implies that x.compareTo(y) must throw an exception iff y.compareTo(x) throws an exception.)

The implementor must also ensure that the relation is transitive: (x.compareTo(y)>0 && y.compareTo(z)>0) implies x.compareTo(z)>0.

Finally, the implementor must ensure that x.compareTo(y)==0 implies that sgn(x.compareTo(z)) == sgn(y.compareTo(z)), for all z.

It is strongly recommended, but not strictly required that (x.compareTo(y)==0) == (x.equals(y)). Generally speaking, any class that implements the Comparable interface and violates this condition should clearly indicate this fact. The recommended language is "Note: this class has a natural ordering that is inconsistent with equals."

In the foregoing description, the notation sgn(expression) designates the mathematical signum function, which is defined to return one of -1, 0, or 1 according to whether the value of expression is negative, zero or positive.

othe object to be compared.

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

public static int compareVersionNumbers(String l, String r) throws NullPointerException, IllegalArgumentException

Compares two version numbers in ascending order.

Version numbers consist of one or more dot (.) separated numbers. Each consecutive number component in the version number have less significance than the preceeding one. This method compares them by comparing each number component in ascending order. Shorter version numbers are ordered first.

The first recognized version number is simply 0. The following version number examples are in strictly ascending order:

 0
 0.0
 0.1
 0.1.0
 0.9
 0.10
 0.10.0
 0.11
 1.0
 1.1
 1.1.0
 1.2
 1.2.3.4.5
 1.2.4
 2.0
 3
 3.0
 3.1
 4
 4.1

Any succeeding .0 number parts are still considered to be part of the version number, and they are not to be emitted. Any version number appended with the string ".0" is considered to be strictly the next in order. (See nextVersionNumberInNaturalOrder(String).)

lThe left version number.

rThe right version number.

The comparison result. Negative if left is less than right, zero if they equal, and positive if the right is greater than left.

NullPointerExceptionIf any of the arguments are null.

IllegalArgumentExceptionIf the version numbers have invalid format.

public static int compareVersionQualifiers(String l, String r) throws NullPointerException, IllegalArgumentException

Comparator function for two version qualifiers.

This method compares the numbers in the argument version qualifiers using the rules specified by compareVersionNumbers(String, String).

The arguments are expected to be version numbers preceeded by a single 'v' or 'V' character.

lThe left version qualifier.

rThe right version qualifier.

The comparison result. Negative if left is less than right, zero if they equal, and positive if the right is greater than left.

NullPointerExceptionIf any of the arguments are null.

IllegalArgumentExceptionIf the version qualifiers have invalid format.

public boolean equals(Object obj)

Overridden from: Object

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

It is reflexive: for any non-null reference value x, x.equals(x) should return true.
It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
For any non-null reference value x, x.equals(null) should return false.

The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any non-null reference values x and y, this method returns true if and only if x and y refer to the same object (x == y has the value true).

Note that it is generally necessary to override the hashCode method whenever this method is overridden, so as to maintain the general contract for the hashCode method, which states that equal objects must have equal hash codes.

objthe reference object with which to compare.

true if this object is the same as the obj argument; false otherwise.

Object.hashCode()

HashMap

public NavigableSet<String> getAllQualifiers()

Gets all qualifiers in this bundle identifier.

Meta-qualfiers and normal qualifiers both included.

This method is the same as constructing a new set that includes both getBundleQualifiers() and getMetaQualifiers().

A (possibly immutable) set of bundle qualifiers, never null.

public final NavigableSet<String> getBundleQualifiers()

Gets the qualifier part of the bundle identifier.

Meta-qualifiers are not included.

An immutable set of bundle qualifiers, never null.

public NavigableSet<String> getMetaQualifiers()

Gets the meta-qualifier part of the bundle identifier.

An immutable set of bundle qualifiers, never null.

public final String getName()

Gets the name part of the bundle identifier.

The name.

public String getVersionNumber()

Gets the version number in this bundle identifier if any.

This method gets the version qualifier, and strips the preceeding 'v' from it.

The version number or null if not present.

public static int getVersionNumberComponentCount(String version) throws NullPointerException, IllegalArgumentException

Counts the number compontents in the argument version number.

This method will count the number segments in the argument version number. It is expected that the argument is already a valid version number, and this method will not verify its format.

E.g.:

1: 1 component
1.0: 2 components
3.0.5.0: 4 components
1.invalid.5.format: 4 components (even though invalid format)

This method effectively counts the number of dot (.) occurrences in the argument.

versionThe version number

The component count.

NullPointerExceptionIf the argument is null.

IllegalArgumentExceptionIf the argument is the empty string.

public String getVersionQualifier()

Gets the version qualifier in this bundle identifier if any.

The returned string contains the preceeding 'v' in it. Use getVersionNumber() to automatically strip it.

The version qualifier or null if not present.

public static <S extends CharSequence> S getVersionQualifier(Iterable<S> qualifiers)

Utility function to retrieve the version qualifier from the argument qualifiers.

If the argument is null, or multiple possible version qualifiers are found, null is returned.

SThe type of character sequence elements.

qualifiersThe iterable of qualifier char sequences.

The version qualifier element if and only if one valid version qualifier is found.

public static String getVersionQualifierVersionNumberPart(String versionqualfier) throws NullPointerException, IllegalArgumentException

Gets the version number part of a version qualifier argument.

This method will return the version number from a valid version qualifier. It will not check the argument if it is actually a valid version qualifier.

The method effectively removes the preceeding 'v' character in the version qualifier.

versionqualfierThe version qualifier.

The version number part.

NullPointerExceptionIf the argument is null.

IllegalArgumentExceptionIf the argument is the empty string.

public boolean hasAnyQualifiers()

Checks if this bundle identifier has any normal or meta qualifiers.

This method is the same as the following:

 !hasNormalQualifiers() && !hasMetaQualifiers()

true if there are any qualifiers present.

hasNormalQualifiers()

hasMetaQualifiers()

public boolean hasMetaQualifiers()

Checks if this bundle identifier has any meta qualifiers.

true if there are any meta qualifiers present.

hasAnyQualifiers()

hasNormalQualifiers()

saker.nest 0.8.3

public boolean hasNormalQualifiers()

Checks if this bundle identifier has any normal qualifiers.

This check doesn't include the meta qualifiers.

true if there are any normal qualifiers present.

hasAnyQualifiers()

hasMetaQualifiers()

saker.nest 0.8.3

public static boolean hasVersionQualifier(Iterable<? extends CharSequence> qualifiers)

Utility function to check if the argument contains any valid version qualifiers.

qualifiersThe iterable of qualifier char sequences.

true if the argument is non-null, and at least one element is recognized to be a valid version qualifier defined by this class.

public int hashCode()

Overridden from: Object

Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided by HashMap.

The general contract of hashCode is:

Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
It is not required that if two objects are unequal according to the Object.equals(Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the Java™ programming language.)

a hash code value for this object.

Object.equals(Object)

System.identityHashCode(Object)

public static boolean isMetaQualifier(String qualifier)

Checks if the argument is a valid version qualifier recognized by this class.

Currently only version qualifiers are considered to be meta-qualifiers.

qualifierThe qualifier string.

true if the argument is a valid meta-qualifier.

public static boolean isValidBundleIdentifier(String bundleidstr)

Checks if the argument has a valid bundle identifier format.

If this method returns true, valueOf(String) will accept it as a valid input. However, it still may throw IllegalArgumentException if the argument contains multiple version qualifiers.

This method doesn't semantically check the qualifier consistency, only the bundle identifier format.

bundleidstrThe string representation of a bundle identifier.

true if it has a valid bundle identifier format.

public static boolean isValidBundleName(String name)

Checks if the argument is a valid bundle name.

The argument should only contain the name part of a bundle identifier. If it contains any qualifiers, the method will return false.

nameThe bundle name.

true if the argument is a valid bundle name.

public static boolean isValidVersionNumber(String version)

Checks if the argument string represents a valid version number.

Valid version numbers are one or more dot (.) separated non-negative numbers. E.g.:

 0
 1
 0.1
 1.0
 1.0.0
 1.2.3

versionThe version number string.

true if the argument is non-null and has a valid version number format.

compareVersionNumbers(String, String)

public static boolean isValidVersionQualifier(String qualifier)

Checks if the argument has a valid version qualifier format.

Version qualifiers consist of a preceeding 'v' character and a version number. See isValidVersionNumber(String) for version number format.

qualifierThe version qualifier.

true if the argument is non-null and has a valid version qualifier format.

compareVersionNumbers(String, String)

public static String makeVersionQualifier(String versionnum) throws NullPointerException

Creates a new version qualifier.

This method simply prepends the argument with "v". The method doesn't check if the argument is a valid version number.

versionnumThe version number part of the resulting version qualifier.

The created qualifier.

NullPointerExceptionIf the argument is null.

public static String nextVersionNumberInNaturalOrder(String version) throws NullPointerException, IllegalArgumentException

Gets the strictly next version number that will compare to be greater than the argument.

The following will be true for any valid version number argument v and created next version number n:

 compareVersionNumbers(v, n) < 0

There exists no version number x that is greater than v and less than n.

This method will not check if the argument is already a valid version number.

versionThe version number.

The strictly next version number in ascending order.

NullPointerExceptionIf the argument is null.

IllegalArgumentExceptionIf the argument is empty.

public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException

Overridden from: Externalizable

The object implements the readExternal method to restore its contents by calling the methods of DataInput for primitive types and readObject for objects, strings and arrays. The readExternal method must read the values in the same sequence and with the same types as were written by writeExternal.

inthe stream to read data from in order to restore the object

IOExceptionif I/O errors occur

ClassNotFoundExceptionIf the class for an object being restored cannot be found.

public String toString()

Overridden from: Object

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())

a string representation of the object.

public static BundleIdentifier valueOf(String input) throws NullPointerException, IllegalArgumentException

Converts the argument to a BundleIdentifier.

The input is expected to start with the bundle name, and have any qualifiers appended with separating dash ('-') characters:

 [bundle.name][-qualifier]*

The input will be converted to a lower-case representation as required by this class.

inputThe input string.

The created task identifier.

NullPointerExceptionIf the argument is null.

IllegalArgumentExceptionIf the input has invalid bundle identifier format, or multiple version qualifiers are found.

public BundleIdentifier withoutAnyQualifiers()

Gets a bundle identifier derived from this that doesn't contain any normal or meta qualifiers.

If this bundle identifier already has no normal or meta qualifiers, this is returned.

A bundle identifier that only contains the same name as this.

public BundleIdentifier withoutMetaQualifiers()

Gets a bundle identifier derived from this that doesn't contain any meta qualifiers.

If this bundle identifier already has no meta-qualifiers, this is returned.

A bundle identifier with the same name and qualifiers as this, but without any meta-qualifiers.

public BundleIdentifier withoutQualifiers()

Gets a bundle identifier derived from this that doesn't contain any (normal) qualifiers.

If this bundle identifier already has no (normal) qualifiers, this is returned.

A bundle identifier with the same name and meta-qualifiers as this, but without any (normal) qualifiers.

public void writeExternal(ObjectOutput out) throws IOException

Overridden from: Externalizable

The object implements the writeExternal method to save its contents by calling the methods of DataOutput for its primitive values or calling the writeObject method of ObjectOutput for objects, strings, and arrays.

outthe stream to write the object to

IOExceptionIncludes any I/O exceptions that may occur