VersionRange
Date: 2016-06-24

org.osgi.framework

## Class VersionRange

- java.lang.Object
- - org.osgi.framework.VersionRange

-     public class VersionRange
      extends java.lang.Object

  Version range. A version range is an interval describing a set of `versions`.

  A range has a left (lower) endpoint and a right (upper) endpoint. Each endpoint can be open (excluded from the set) or closed (included in the set).

  `VersionRange` objects are immutable.

  Since:
    1.7

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static char` | `LEFT_CLOSED` The left endpoint is closed and is included in the range.
    `static char` | `LEFT_OPEN` The left endpoint is open and is excluded from the range.
    `static char` | `RIGHT_CLOSED` The right endpoint is closed and is included in the range.
    `static char` | `RIGHT_OPEN` The right endpoint is open and is excluded from the range.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `VersionRange(char leftType, Version leftEndpoint, Version rightEndpoint, char rightType)` Creates a version range from the specified versions.
    `VersionRange(java.lang.String range)` Creates a version range from the specified string.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(java.lang.Object object)` Compares this `VersionRange` object to another object.
    `Version` | `getLeft()` Returns the left endpoint of this version range.
    `char` | `getLeftType()` Returns the type of the left endpoint of this version range.
    `Version` | `getRight()` Returns the right endpoint of this version range.
    `char` | `getRightType()` Returns the type of the right endpoint of this version range.
    `int` | `hashCode()` Returns a hash code value for the object.
    `boolean` | `includes(Version version)` Returns whether this version range includes the specified version.
    `VersionRange` | `intersection(VersionRange... ranges)` Returns the intersection of this version range with the specified version ranges.
    `boolean` | `isEmpty()` Returns whether this version range is empty.
    `boolean` | `isExact()` Returns whether this version range contains only a single version.
    `java.lang.String` | `toFilterString(java.lang.String attributeName)` Returns the filter string for this version range using the specified attribute name.
    `java.lang.String` | `toString()` Returns the string representation of this version range.
    `static VersionRange` | `valueOf(java.lang.String range)` Returns a `VersionRange` object holding the version range in the specified `String`.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### LEFT_OPEN

          public static final char LEFT_OPEN

      The left endpoint is open and is excluded from the range.

      The value of `LEFT_OPEN` is `'('`.

      See Also:
        Constant Field Values

    - #### LEFT_CLOSED

          public static final char LEFT_CLOSED

      The left endpoint is closed and is included in the range.

      The value of `LEFT_CLOSED` is `'['`.

      See Also:
        Constant Field Values

    - #### RIGHT_OPEN

          public static final char RIGHT_OPEN

      The right endpoint is open and is excluded from the range.

      The value of `RIGHT_OPEN` is `')'`.

      See Also:
        Constant Field Values

    - #### RIGHT_CLOSED

          public static final char RIGHT_CLOSED

      The right endpoint is closed and is included in the range.

      The value of `RIGHT_CLOSED` is `']'`.

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### VersionRange

          public VersionRange(char leftType,
                      Version leftEndpoint,
                      Version rightEndpoint,
                      char rightType)

      Creates a version range from the specified versions.
      Parameters:
        `leftType` - Must be either `LEFT_CLOSED` or `LEFT_OPEN` .
        `leftEndpoint` - Left endpoint of range. Must not be `null`.
        `rightEndpoint` - Right endpoint of range. May be `null` to indicate the right endpoint is Infinity.
        `rightType` - Must be either `RIGHT_CLOSED` or `RIGHT_OPEN`.
      Throws:
        `java.lang.IllegalArgumentException` - If the arguments are invalid.

    - #### VersionRange

          public VersionRange(java.lang.String range)

      Creates a version range from the specified string.

      Version range string grammar:

           range ::= interval | atleast
           interval ::= ( '[' | '(' ) left ',' right ( ']' | ')' )
           left ::= version
           right ::= version
           atleast ::= version

      Parameters:
        `range` - String representation of the version range. The versions in the range must contain no whitespace. Other whitespace in the range string is ignored. Must not be `null`.
      Throws:
        `java.lang.IllegalArgumentException` - If `range` is improperly formatted.

  - ### Method Detail

    - #### getLeft

          public Version getLeft()

      Returns the left endpoint of this version range.
      Returns:
        The left endpoint.

    - #### getRight

          public Version getRight()

      Returns the right endpoint of this version range.
      Returns:
        The right endpoint. May be `null` which indicates the right endpoint is Infinity.

    - #### getLeftType

          public char getLeftType()

      Returns the type of the left endpoint of this version range.
      Returns:
        `LEFT_CLOSED` if the left endpoint is closed or `LEFT_OPEN` if the left endpoint is open.

    - #### getRightType

          public char getRightType()

      Returns the type of the right endpoint of this version range.
      Returns:
        `RIGHT_CLOSED` if the right endpoint is closed or `RIGHT_OPEN` if the right endpoint is open.

    - #### includes

          public boolean includes(Version version)

      Returns whether this version range includes the specified version.
      Parameters:
        `version` - The version to test for inclusion in this version range.
      Returns:
        `true` if the specified version is included in this version range; `false` otherwise.

    - #### intersection

          public VersionRange intersection(VersionRange... ranges)

      Returns the intersection of this version range with the specified version ranges.
      Parameters:
        `ranges` - The version ranges to intersect with this version range.
      Returns:
        A version range representing the intersection of this version range and the specified version ranges. If no version ranges are specified, then this version range is returned.

    - #### isEmpty

          public boolean isEmpty()

      Returns whether this version range is empty. A version range is empty if the set of versions defined by the interval is empty.
      Returns:
        `true` if this version range is empty; `false` otherwise.

    - #### isExact

          public boolean isExact()

      Returns whether this version range contains only a single version.
      Returns:
        `true` if this version range contains only a single version; `false` otherwise.

    - #### toString

          public java.lang.String toString()

      Returns the string representation of this version range.

      The format of the version range string will be a version string if the right end point is Infinity (`null`) or an interval string.

      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        The string representation of this version range.

    - #### hashCode

          public int hashCode()

      Returns a hash code value for the object.
      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        An integer which is a hash code value for this object.

    - #### equals

          public boolean equals(java.lang.Object object)

      Compares this `VersionRange` object to another object.

      A version range is considered to be equal to another version range if both the endpoints and their types are equal or if both version ranges are `empty`.

      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `object` - The `VersionRange` object to be compared.
      Returns:
        `true` if `object` is a `VersionRange` and is equal to this object; `false` otherwise.

    - #### toFilterString

          public java.lang.String toFilterString(java.lang.String attributeName)

      Returns the filter string for this version range using the specified attribute name.
      Parameters:
        `attributeName` - The attribute name to use in the returned filter string.
      Returns:
        A filter string for this version range using the specified attribute name.
      Throws:
        `java.lang.IllegalArgumentException` - If the specified attribute name is not a valid attribute name.
      See Also:
        "Core Specification, Filters, for a description of the filter string syntax."

    - #### valueOf

          public static VersionRange valueOf(java.lang.String range)

      Returns a `VersionRange` object holding the version range in the specified `String`.

      See `VersionRange(String)` for the format of the version range string.

      Parameters:
        `range` - String representation of the version range. The versions in the range must contain no whitespace. Other whitespace in the range string is ignored. Must not be `null`.
      Returns:
        A `VersionRange` object representing the version range.
      Throws:
        `java.lang.IllegalArgumentException` - If `range` is improperly formatted.
      Since:
        1.8