Class ResourceInstaller
http, https, and file locations are accepted.
A checksum is required for http and https sources and optional for file sources.
It is verified against the downloaded bytes before anything is unpacked: a
64-character hex digest selects SHA-256, a 128-character one SHA-512.
The content format is detected from the bytes, not from the name: gzip-compressed
tar archives and zip archives are unpacked with their relative structure. Invalid,
escaping, and duplicate file paths are rejected. Plain gzip files are decompressed,
and other content is stored as a file under the source name. One name rule overrides
byte detection: a *.bin source is always stored packed because an OpenNLP
model file is itself a zip archive that its consumers load packed.
Each installation is bounded by ResourceInstaller.Limits: http and https fetches use
connection and read timeouts, follow at most a fixed number of redirects, reject
redirects that leave the http and https schemes or downgrade https to http, and
abort once the download or the expanded content crosses its size limit or the
archive crosses its entry limit. Compressed content, gzip and zip alike, may
expand to at most ResourceInstaller.Limits.maxExpansionRatio() times its compressed size,
with a floor of 1048576L bytes for small sources. The defaults in
ResourceInstaller.Limits.DEFAULT apply when no limits are given, and ResourceInstaller.Limits.builder()
starts from them.
Installation is staged: content is unpacked into a hidden staging directory on the same filesystem and moved into the target only after the download was verified and every entry unpacked cleanly. A fetch, verification, or unpacking failure promotes no files into the target directory. Promotion does not replace a file that already exists in the target and detects the collision before moving anything, so refreshing a resource means removing its old files first. Work files left in the target by an installation that was killed are removed at the start of the next installation into that target, so concurrent installations into one target directory are not supported.
- Since:
- 3.0.0
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final recordSafety limits and network behavior for one installation.static interfaceWrites content into the staging directory ofinstallSelected(Path, StagingStep, Function). -
Method Summary
Modifier and TypeMethodDescriptionstatic PathUnpacks a resource without checksum verification, underResourceInstaller.Limits.DEFAULT.static PathFetches, verifies, and unpacks a resource underResourceInstaller.Limits.DEFAULT.static Pathinstall(URI source, Path targetDirectory, String checksum, ResourceInstaller.Limits limits) Fetches, verifies, and unpacks a resource under the givenResourceInstaller.Limits.static intinstallSelected(Path targetDirectory, ResourceInstaller.StagingStep step, Function<Path, Path> selector) Installs a selection of the files that a caller-supplied step writes into a staging directory.
-
Method Details
-
install
Unpacks a resource without checksum verification, underResourceInstaller.Limits.DEFAULT. This overload treats the source as trusted caller input and performs no cryptographic integrity verification, so it accepts onlyfilesources; an http or https source must go through an overload that takes its checksum.- Parameters:
source- The resource location, afileURI. Notnull.targetDirectory- The directory to install into; created when absent. Must not benull.- Returns:
- The target directory. Not
null. - Throws:
IOException- Thrown if fetching or unpacking fails.IllegalArgumentException- Thrown ifsourceortargetDirectoryisnull,sourcecontains a scheme other thanfile, or its last path segment is not a valid local file name.
-
install
Fetches, verifies, and unpacks a resource underResourceInstaller.Limits.DEFAULT.- Parameters:
source- The resource location, anhttp,https, orfileURI. Notnull.targetDirectory- The directory to install into; created when absent. Must not benull.checksum- The expected digest of the downloaded bytes as a hex string, compared case-insensitively and ignoring leading and trailing whitespace: 64 characters select SHA-256, 128 characters SHA-512. Required for an http or https source; passnullto skip verification for afilesource.- Returns:
- The target directory. Not
null. - Throws:
IOException- Thrown if fetching fails, the checksum does not match, or unpacking fails.IllegalArgumentException- Thrown ifsourceortargetDirectoryisnull,sourcecontains a scheme other thanhttp,https, orfile,checksumis not a 64-character or 128-character hex string, an http or https source contains no checksum, or the source does not provide a valid local file name.
-
install
public static Path install(URI source, Path targetDirectory, String checksum, ResourceInstaller.Limits limits) throws IOException Fetches, verifies, and unpacks a resource under the givenResourceInstaller.Limits.- Parameters:
source- The resource location, anhttp,https, orfileURI. Notnull.targetDirectory- The directory to install into; created when absent. Must not benull.checksum- The expected digest of the downloaded bytes as a hex string, compared case-insensitively and ignoring leading and trailing whitespace: 64 characters select SHA-256, 128 characters SHA-512. Required for an http or https source; passnullto skip verification for afilesource.limits- The timeouts, redirect allowance, and size and entry limits to enforce. Notnull.- Returns:
- The target directory. Not
null. - Throws:
IOException- Thrown if fetching fails, a limit is exceeded, the checksum does not match, or unpacking fails.IllegalArgumentException- Thrown ifsource,targetDirectory, orlimitsisnull,sourcecontains a scheme other thanhttp,https, orfile,checksumis not a 64-character or 128-character hex string, an http or https source contains no checksum, or the source does not provide a valid local file name.
-
installSelected
@Internal public static int installSelected(Path targetDirectory, ResourceInstaller.StagingStep step, Function<Path, Path> selector) throws IOExceptionInstalls a selection of the files that a caller-supplied step writes into a staging directory. The step runs against an empty hidden staging directory beneath the target, typically by callinginstall(URI, Path, String)with the staging directory as its target. The selector then maps each staged regular file, by its path relative to the staging directory, to its path relative to the target, or tonullto leave it out. The selected files are promoted under the same rules asinstall(URI, Path, String): nothing is promoted when the step fails, and an existing destination aborts the promotion before the first move.- Parameters:
targetDirectory- The directory to install into; created when absent. Must not benull.step- Writes the content into the staging directory. Must not benull.selector- Maps a staged file's relative path to its relative destination beneath the target, or tonullto skip the file. A destination must be relative and normalized. Must not benull.- Returns:
- The number of files installed.
- Throws:
IOException- Thrown if the step fails, a destination is absolute or not normalized, two staged files map to the same destination, a destination already exists, or moving fails.IllegalArgumentException- Thrown if a parameter isnull.
-