Package rife.bld.extension.tools

Class Sandbox

java.lang.Object
rife.bld.extension.tools.Sandbox
@NullMarked public final class Sandbox extends Object
Manages an isolated, per-extension sandbox for downloading dependencies, rooted at lib/bld/.sandbox/<extensionName>.

Dependencies can be downloaded into the extension's sandbox root or into an explicit subdirectory of it (see the subDirectory overloads); each location is tracked independently. A download is skipped and the cached artifacts reused when a snapshot recorded in lib/bld/.sandbox/sandbox.snapshot is still valid — validity requires both the resolution inputs (dependencies, repositories, version overrides/boms) and the current on-disk content of the target directory to match what was recorded, so external changes to either force a re-download. Snapshot updates are written atomically.

Concurrent downloads for the same extension are serialized; downloads for different extensions may proceed in parallel while still safely sharing the snapshot file.

Since:
1.4
Author:
Erik C. Thauvin

  • Constructor Summary

    Constructors
    Constructor
    Description
    Sandbox(String extensionName, rife.bld.BaseProject project)
    Creates a new sandbox manager for the given extension.

  • Method Summary

    Modifier and Type
    Method
    Description
    Path
    downloadDependencies(List<rife.bld.dependencies.Dependency> dependencies, List<rife.bld.dependencies.Repository> repositories)
    Downloads the given dependencies using the provided repositories and a default VersionResolution.
    Path
    downloadDependencies(List<rife.bld.dependencies.Dependency> dependencies, List<rife.bld.dependencies.Repository> repositories, @Nullable File subDirectory)
    Downloads dependencies into the sandbox, optionally under a subdirectory specified as a File.
    Path
    downloadDependencies(List<rife.bld.dependencies.Dependency> dependencies, List<rife.bld.dependencies.Repository> repositories, @Nullable Path subDirectory)
    Downloads dependencies into the sandbox, optionally under a subdirectory.
    Path
    downloadDependencies(List<rife.bld.dependencies.Dependency> dependencies, List<rife.bld.dependencies.Repository> repositories, rife.bld.dependencies.VersionResolution resolution)
    Downloads the given dependencies using the provided repositories and version resolution.
    Path
    downloadDependencies(List<rife.bld.dependencies.Dependency> dependencies, List<rife.bld.dependencies.Repository> repositories, rife.bld.dependencies.VersionResolution resolution, @Nullable File subDirectory)
    Downloads the given dependencies using the provided repositories and version resolution into an optional subdirectory specified as a File.
    Path
    downloadDependencies(List<rife.bld.dependencies.Dependency> dependencies, List<rife.bld.dependencies.Repository> repositories, rife.bld.dependencies.VersionResolution resolution, @Nullable Path subDirectory)
    Downloads dependencies into the sandbox, optionally under a subdirectory.
    Path
    getSandboxDirectory()
    Returns the root sandbox directory.
    File
    getSandboxDirectoryAsFile()
    Returns the root sandbox directory as a File.
    Path
    getSandboxExtensionDirectory()
    Returns the extension-specific sandbox directory.
    File
    getSandboxExtensionDirectoryAsFile()
    Returns the extension-specific sandbox directory as a File.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Sandbox

      public Sandbox(String extensionName, rife.bld.BaseProject project)
      Creates a new sandbox manager for the given extension.
      Parameters:
      extensionName - the unique name of the extension; must be a single, non-blank path segment
      project - the bld project used to resolve lib/bld; must not be null
      Throws:
      NullPointerException - if any argument is null
      IllegalArgumentException - if extensionName is blank or is not a single path segment (for example, if it contains a separator, .. or is absolute)

  • Method Details

    • downloadDependencies

      public Path downloadDependencies(List<rife.bld.dependencies.Dependency> dependencies, List<rife.bld.dependencies.Repository> repositories)
      Downloads the given dependencies using the provided repositories and a default VersionResolution.
      Parameters:
      dependencies - the dependencies to resolve; must not be null
      repositories - the repositories to resolve from; must not be null
      Returns:
      the path to the extension sandbox directory where artifacts were (or would be) downloaded
      Throws:
      NullPointerException - if any argument is null or contain null elements
      IllegalArgumentException - if any argument is empty or contain empty elements
      See Also:

    • downloadDependencies

      public Path downloadDependencies(List<rife.bld.dependencies.Dependency> dependencies, List<rife.bld.dependencies.Repository> repositories, rife.bld.dependencies.VersionResolution resolution)
      Downloads the given dependencies using the provided repositories and version resolution.

      If a valid snapshot already exists, the download is skipped.

      Parameters:
      dependencies - the dependencies to resolve; must not be null or empty
      repositories - the repositories to resolve from; must not be null or empty
      resolution - the version resolution strategy; must not be null
      Returns:
      the path to the extension sandbox directory where artifacts were (or would be) downloaded
      Throws:
      NullPointerException - if any argument is null or contain null elements
      IllegalArgumentException - if any argument is empty or contain empty elements
      See Also:

    • downloadDependencies

      public Path downloadDependencies(List<rife.bld.dependencies.Dependency> dependencies, List<rife.bld.dependencies.Repository> repositories, rife.bld.dependencies.VersionResolution resolution, @Nullable Path subDirectory)
      Downloads dependencies into the sandbox, optionally under a subdirectory.
      Parameters:
      dependencies - the direct dependencies to resolve; must not be null or empty
      repositories - the repositories to resolve from; must not be null or empty
      resolution - the version resolution strategy; must not be null
      subDirectory - optional subdirectory within the extension sandbox to place artifacts; may be null to use the extension root
      Returns:
      the path to the directory where artifacts were downloaded
      Throws:
      NullPointerException - if any argument is null or contain null elements
      IllegalArgumentException - if any argument is empty or contain empty elements, or if subDirectory resolves outside the extension sandbox
      IllegalStateException - if an existing download directory cannot be deleted
      UncheckedIOException - if the download directory cannot be created or the snapshot cannot be written

    • downloadDependencies

      public Path downloadDependencies(List<rife.bld.dependencies.Dependency> dependencies, List<rife.bld.dependencies.Repository> repositories, rife.bld.dependencies.VersionResolution resolution, @Nullable File subDirectory)
      Downloads the given dependencies using the provided repositories and version resolution into an optional subdirectory specified as a File.
      Parameters:
      dependencies - the dependencies to resolve; must not be null or empty
      repositories - the repositories to resolve from; must not be null or empty
      resolution - the version resolution strategy; must not be null
      subDirectory - optional subdirectory as a File; may be null
      Returns:
      the path to the directory where artifacts were downloaded
      Throws:
      NullPointerException - if any argument is null or contain null elements
      IllegalArgumentException - if any argument is empty or contain empty elements, or if subDirectory resolves outside the extension sandbox
      IllegalStateException - if an existing download directory cannot be deleted
      UncheckedIOException - if the download directory cannot be created or the snapshot cannot be written
      See Also:

    • downloadDependencies

      public Path downloadDependencies(List<rife.bld.dependencies.Dependency> dependencies, List<rife.bld.dependencies.Repository> repositories, @Nullable Path subDirectory)
      Downloads dependencies into the sandbox, optionally under a subdirectory.
      Parameters:
      dependencies - the direct dependencies to resolve; must not be null or empty
      repositories - the repositories to resolve from; must not be null or empty
      subDirectory - optional subdirectory within the extension sandbox to place artifacts; may be null to use the extension root
      Returns:
      the path to the directory where artifacts were downloaded
      Throws:
      NullPointerException - if any argument is null or contain null elements
      IllegalArgumentException - if any argument is empty or contain empty elements, or if subDirectory resolves outside the extension sandbox
      IllegalStateException - if an existing download directory cannot be deleted
      UncheckedIOException - if the download directory cannot be created or the snapshot cannot be written
      See Also:

    • downloadDependencies

      public Path downloadDependencies(List<rife.bld.dependencies.Dependency> dependencies, List<rife.bld.dependencies.Repository> repositories, @Nullable File subDirectory)
      Downloads dependencies into the sandbox, optionally under a subdirectory specified as a File.
      Parameters:
      dependencies - the dependencies to resolve; must not be null or empty
      repositories - the repositories to resolve from; must not be null or empty
      subDirectory - optional subdirectory as a File; may be null
      Returns:
      the path to the directory where artifacts were downloaded
      See Also:

    • getSandboxDirectory

      public Path getSandboxDirectory()
      Returns the root sandbox directory.
      Returns:
      the path to lib/bld/.sandbox

    • getSandboxDirectoryAsFile

      public File getSandboxDirectoryAsFile()
      Returns the root sandbox directory as a File.
      Returns:
      the root sandbox directory file

    • getSandboxExtensionDirectory

      public Path getSandboxExtensionDirectory()
      Returns the extension-specific sandbox directory.
      Returns:
      the path to lib/bld/.sandbox/<extensionName>

    • getSandboxExtensionDirectoryAsFile

      public File getSandboxExtensionDirectoryAsFile()
      Returns the extension-specific sandbox directory as a File.
      Returns:
      the extension sandbox directory file