Package org.stianloader.picoresolve.repo

# Interface RepositoryNegotiatior

All Known Implementing Classes:
  `MavenLocalRepositoryNegotiator`

public interface RepositoryNegotiatior
The purpose of a repository negotiator is to negotiate which repository should be used when a file is requested. Furthermore caching and file locking fall under the tasks performed by the negotiator.

## Method Summary

Modifier and Type
Method
Description
`@NotNull RepositoryNegotiatior`
`addRepository(@NotNull MavenRepository repo)`
`@NotNull CompletableFuture<List<RepositoryAttachedValue<Path>>>`
`resolveMavenMeta(@NotNull String path, @NotNull Executor executor)`
Resolve all relevant maven-metadata.xml files from the repositories and cache them into files.
`@NotNull CompletableFuture<RepositoryAttachedValue<Path>>`
`resolveStandard(@NotNull String path, @NotNull Executor executor)`
Resolve a "standard" non-metadata file from the repositories and store it into a file.
`@NotNull RepositoryNegotiatior`
`setWriteCacheMetadata(boolean writeMetadata)`
Set whether the `RepositoryNegotiatior` is permitted to write metadata files for caching or repository tracking purposes.

## Method Details

### resolveStandard

@NotNull @NotNull CompletableFuture<RepositoryAttachedValue<Path>> resolveStandard(@NotNull @NotNull String path, @NotNull @NotNull Executor executor)
Resolve a "standard" non-metadata file from the repositories and store it into a file.

- Exceptional completion CAN occur if a maven-metadata.xml is requested.
- The returned `CompletableFuture` WILL complete exceptionally if the requested file does not exist in any repository known to this instance of the `RepositoryNegotiatior` and if the file was not cached locally beforehand.
- The `CompletableFuture` CAN complete exceptionally if the requested file does not exist in the repositories but was cached locally previously (Maven 3 behaviour, Maven 4.0.0-rc.5 would complete normally here, but that might be a bug on Maven's side).
- However it SHOULD complete normally if the file was cached recently by a repository known to this negotiator - that is before the repository refresh interval, irrespective of other factors.
- Normal completion MUST occur if any repository contains the file. (It may complete exceptionally if needed file IO is not possible for the caching, but that is an ignored edge-case scenario here)
- Normal completion SHOULD occur if the file exists locally at the right path, even though it was never stored beforehand through caching mechanism known to the negotiator. More specifically, certain internal metadata files used by the negotiator can be absent.

Reason as to why maven-metadata.xml and other files have their own resolve methods is that MavenLocal stores metadata files a bit different to non-metadata files and therefore it makes sense to separate the two methods.

Parameters:
  `path` - The path relative to the repository root where the file is located.
  `executor` - The executor with whom asynchronous operations should be performed.
Returns:
  A `CompletableFuture` which upon non-exceptional `completion` stores the path where the resolved file is stored locally.

### resolveMavenMeta

@NotNull @NotNull CompletableFuture<List<RepositoryAttachedValue<Path>>> resolveMavenMeta(@NotNull @NotNull String path, @NotNull @NotNull Executor executor)
Resolve all relevant maven-metadata.xml files from the repositories and cache them into files.

- This method MUST throw directly if something else but a maven-metadata.xml is requested.
- The returned `CompletableFuture` WILL complete exceptionally if the requested file does not exist in any repository known to this instance of the `RepositoryNegotiatior` and if the file was not cached locally beforehand.
- The `CompletableFuture` CAN complete exceptionally if the requested file does not exist in the repositories but was cached locally previously.
- However it SHOULD complete normally if the file was cached recently - that is before the repository refresh interval.
- Normal completion MUST occur if any repository contains the file. (It may complete exceptionally if needed file IO is not possible for the caching, but that is an ignored edge-case scenario here)
- Normal completion SHOULD occur if the file exists locally at the right path, even though it was never stored beforehand through caching mechanism known to the negotiator. More specifically, certain internal metadata files used by the negotiator can be absent.

Reason as to why maven-metadata.xml and other files have their own resolve methods is that MavenLocal stores metadata files a bit different to non-metadata files and therefore it makes sense to separate the two methods.

Furthermore it makes sense to basically merge all the maven-metadata.xml files instead of only fetching a single one.

Parameters:
  `path` - The path relative to the repository root where the file is located.
  `executor` - The executor with whom asynchronous operations should be performed.
Returns:
  A `CompletableFuture` which upon non-exceptional `completion` stores the path where the resolved file is stored locally.
Throws:
  `IllegalArgumentException` - If the requested file is not a maven-metadata.xml.

### addRepository

@NotNull @Contract(mutates="this", pure=false, value="null -> fail; !null -> this") @NotNull RepositoryNegotiatior addRepository(@NotNull @NotNull MavenRepository repo)

### setWriteCacheMetadata

@NotNull @Contract(mutates="this", pure=false, value="-> this") @NotNull RepositoryNegotiatior setWriteCacheMetadata(boolean writeMetadata)
Set whether the `RepositoryNegotiatior` is permitted to write metadata files for caching or repository tracking purposes. If the instance is not permitted to write such files, then it is likely to be necessitated to give up the ability to attach a repository to an artifact through `RepositoryAttachedValue`, that is it's `repository value` will more often than not be null.

The state of this flag has no effect on whether the negotiator is permitted to fetch artifacts from remote repositories. Nor should it have a direct effect on other policies, such as the repository refresh interval. However, as the refresh interval can only be handled with great difficult in the absence of metadata files, the refresh behaviour is likely either going to be completely absent or be always present. `MavenLocalRepositoryNegotiator` will still proceed reading metadata files and handling them accordingly if they are present if writing is disabled; however it will not write any new ones nor update any existing ones.

Disabling metadata is strongly discouraged. It should only be turned off if reducing clutter is absolutely crucial (e.g. in public-facing maven repositories) and read latencies are low. Furthermore it is recommended to have no remote repositories, in which case cache metadata files are of little use.

Parameters:
  `writeMetadata` - True to allow writing metadata, false otherwise
Returns:
  The current `RepositoryNegotiatior` instance, for chaining