Package org.stianloader.picoresolve.version

# Class VersionRange

java.lang.Object
org.stianloader.picoresolve.version.VersionRange

public class VersionRange extends Object

## Field Summary

Fields
Modifier and Type
Field
Description
`static final @NotNull VersionRange`
`FREE_RANGE`
Sentinel value marking a version range which allows any value - corresponding to the string ','.
`static final @NotNull VersionRange`
`RELEASE`
Sentinel value marking a version range which accepts the latest versions defined by the 'release' field of the A-level metadata.xml file.

## Method Summary

Modifier and Type
Method
Description
`boolean`
`containsVersion(@NotNull MavenVersion version)`
`@Nullable MavenVersion`
`getRecommended()`
Obtains the newest ("highest") recommended version that is within the version range.
`List<@NotNull MavenVersion>`
`getRecommendedVersions()`
`@NotNull VersionRange`
`intersect(@NotNull VersionRange version)`
`static @NotNull VersionRange`
`parse(@NotNull String string)`
`@Nullable MavenVersion`
`selectFrom(@Nullable Collection<@NotNull MavenVersion> knownAvailable, @Nullable MavenVersion releaseVersion)`
Deprecated.
Use `selectFrom(Collection, MavenVersion, VersionSelectionPreference)` instead.
`@Nullable MavenVersion`
`selectFrom(@Nullable Collection<@NotNull MavenVersion> knownAvailable, @Nullable MavenVersion releaseVersion, @NotNull VersionSelectionPreference preference)`
Select the `MavenVersion` that best applies to this `VersionRange`, making use of a list of all available versions (`knownAvailable`) using the provided `VersionSelectionPreference`.
`String`
`toString()`

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

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

## Field Details

### FREE_RANGE

@NotNull public static final @NotNull VersionRange FREE_RANGE
Sentinel value marking a version range which allows any value - corresponding to the string ','.

Note that for the maven artifact resolver, this concept does not exist. This concept does exist under picoresolve though as a convenience method to always select the newest version. Unlike `RELEASE`, `FREE_RANGE` works by selecting the newest version from the maven-metadata.xml while `RELEASE` works by selecting the advertised release version from the maven-metadata.xml file.

Implementation Note:
  The difference between `FREE_RANGE` and `RELEASE` is wholly based on identity. Behaviour between the two instances only differs for the `selectFrom(Collection, MavenVersion)` method.

### RELEASE

@NotNull public static final @NotNull VersionRange RELEASE
Sentinel value marking a version range which accepts the latest versions defined by the 'release' field of the A-level metadata.xml file. This generally corresponds to the newest non-snapshjot version published to the repositories.

This field corresponds to the strings 'RELEASE' as well as '[RELEASE]' as the value of this field will be returned when trying to parse these values using `parse(String)`. Usage of the 'RELEASE' string is not permitted in version ranges - if this occurs, picoresolve will treat it as a `MavenVersion` version string - that is a string literal with no meaning, but other resolver implementations might throw an error in that case.

When using `parse(String)` the case of the characters matters - that is the literal 'RELEASE' corresponds to this field, where as the literal 'release' would correspond to a `MavenVersion` without any special meaning.

Note: The usage of this field is discouraged as it follows against the principle of reproducibility and stability, which for back-end software is generally not favourable.

Implementation Note:
  The difference between `FREE_RANGE` and `RELEASE` is wholly based on identity. Where as behaviour between the two instances only differs for the `selectFrom(Collection, MavenVersion)` method.

  Further, `RELEASE` like `FREE_RANGE` accepts any values for a call to `containsVersion(MavenVersion)`.

## Method Details

### parse

@NotNull public static @NotNull VersionRange parse(@NotNull @NotNull String string)

### containsVersion

public boolean containsVersion(@NotNull @NotNull MavenVersion version)

### getRecommended

@Nullable public @Nullable MavenVersion getRecommended()
Obtains the newest ("highest") recommended version that is within the version range. If there are no recommended versions or if none of these versions match the constraints set up by the version range, null is returned.

Note: In the absence of any explicit range rules, as is the case when a `VersionRange` is a plain version, then the recommended version will implicitly be treated as "pins". That is, they are the only allowed versions.

Returns:
  The highest recommended version that lies within the bounds of the version range.

### getRecommendedVersions

public List<@NotNull MavenVersion> getRecommendedVersions()

### intersect

@NotNull public @NotNull VersionRange intersect(@NotNull @NotNull VersionRange version)

### selectFrom

@Nullable @AvailableSince("1.1.0-a20260531") @Contract(pure=true) public @Nullable MavenVersion selectFrom(@Nullable @Nullable Collection<@NotNull MavenVersion> knownAvailable, @Nullable @Nullable MavenVersion releaseVersion, @NotNull @NotNull VersionSelectionPreference preference)
Select the `MavenVersion` that best applies to this `VersionRange`, making use of a list of all available versions (`knownAvailable`) using the provided `VersionSelectionPreference`.

However, even if no versions are known as available, the `VersionRange` will prefer to select from `getRecommendedVersions()`.

For `VersionSelectionPreference.DECLARATION_ORDER`, the artifact declaration order is determined using the order in which `VersionRange` instances are intersected with each other, i.e. the order of the `intersect(VersionRange)` calls. More specifically, it is defined using the order of `getRecommendedVersions()`.

Parameters:
  `knownAvailable` - All known-available versions that this `VersionRange` can resolve to. This list is usually resolved from the A-level `maven-metadata.xml` file.
  `releaseVersion` - The version corresponding to the RELEASE version (see `RELEASE`).
  `preference` - The method by which the selected version should be determined.
Returns:
  The selected `MavenVersion`, or `null` if it doesn't apply.
Since:
  1.1.0-a20260531

### selectFrom

@Nullable @Deprecated @ScheduledForRemoval(inVersion="2.0.0-a0") @Contract(pure=true) public @Nullable MavenVersion selectFrom(@Nullable @Nullable Collection<@NotNull MavenVersion> knownAvailable, @Nullable @Nullable MavenVersion releaseVersion)
Deprecated.
Use `selectFrom(Collection, MavenVersion, VersionSelectionPreference)` instead. This method remains for ABI compatibility and uses the outdated `VersionSelectionPreference.NEWEST_FIRST` selection preference.

Parameters:
  `knownAvailable` - All known-available versions that this `VersionRange` can resolve to. This list is usually resolved from the A-level `maven-metadata.xml` file.
  `releaseVersion` - The version corresponding to the RELEASE version (see `RELEASE`).
Returns:
  The selected `MavenVersion`, or `null` if it doesn't apply.

### toString

public String toString()

Overrides:
  `toString` in class `Object`