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 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.
      • 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.

      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