Class ResourceInstaller

java.lang.Object
opennlp.tools.util.ResourceInstaller
public final class ResourceInstaller extends Object
Fetches a third-party resource, such as a training corpus, a dictionary archive, or a lexicon, into a local directory. The caller supplies the location and thereby accepts that resource's license; no locations are built in and no data is bundled. Only 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:

  • Method Details

    • install

      public static Path install(URI source, Path targetDirectory) throws IOException
      Unpacks a resource without checksum verification, under ResourceInstaller.Limits.DEFAULT. This overload treats the source as trusted caller input and performs no cryptographic integrity verification, so it accepts only file sources; an http or https source must go through an overload that takes its checksum.
      Parameters:
      source - The resource location, a file URI. Not null.
      targetDirectory - The directory to install into; created when absent. Must not be null.
      Returns:
      The target directory. Not null.
      Throws:
      IOException - Thrown if fetching or unpacking fails.
      IllegalArgumentException - Thrown if source or targetDirectory is null, source contains a scheme other than file, or its last path segment is not a valid local file name.

    • install

      public static Path install(URI source, Path targetDirectory, String checksum) throws IOException
      Fetches, verifies, and unpacks a resource under ResourceInstaller.Limits.DEFAULT.
      Parameters:
      source - The resource location, an http, https, or file URI. Not null.
      targetDirectory - The directory to install into; created when absent. Must not be null.
      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; pass null to skip verification for a file source.
      Returns:
      The target directory. Not null.
      Throws:
      IOException - Thrown if fetching fails, the checksum does not match, or unpacking fails.
      IllegalArgumentException - Thrown if source or targetDirectory is null, source contains a scheme other than http, https, or file, checksum is 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 given ResourceInstaller.Limits.
      Parameters:
      source - The resource location, an http, https, or file URI. Not null.
      targetDirectory - The directory to install into; created when absent. Must not be null.
      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; pass null to skip verification for a file source.
      limits - The timeouts, redirect allowance, and size and entry limits to enforce. Not null.
      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 if source, targetDirectory, or limits is null, source contains a scheme other than http, https, or file, checksum is 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.