Package io.ocfl.api

Interface OcflObjectUpdater

public interface OcflObjectUpdater
Exposes methods for selectively updating a specific OCFL object.

Implementations are thread safe, and you can concurrently use the same updater to add multiple files to the same object version.

  • Method Details

    • addPath

      OcflObjectUpdater addPath(Path sourcePath, OcflOption... options)
      Adds a file or directory to the object. If the path is a file, it is inserted in the object using its filename. If it's a directory, the contents of the directory are inserted into the object's root.

      By default, files are copied into the OCFL repository. If OcflOption.MOVE_SOURCE is specified, then files will be moved instead. Warning: If an exception occurs and the new version is not created, the files that will be lost. This operation is more efficient but less safe than the default copy.

      By default, the change will be rejected if there is an existing file in an object at a logical path. To overwrite, specify OcflOption.OVERWRITE.

      Parameters:
      sourcePath - the local file or directory to add to the object
      options - optional config options. Use OcflOption.MOVE_SOURCE to move files into the repo instead of copying. Use OcflOption.OVERWRITE to overwrite existing files within an object
      Returns:
      this
      Throws:
      OverwriteException - if there is already a file at the destinationPath and OcflOption.OVERWRITE was not specified

    • addPath

      OcflObjectUpdater addPath(Path sourcePath, String destinationPath, OcflOption... options)
      Adds a file or directory to the object at the specified destinationPath. The destinationPath is the logical path to the file within the object. Forward slashes MUST be used as filename separators in the path. It is important to keep this in mind on Windows systems, where backslashes MUST be converted to forward slashes.

      By default, files are copied into the OCFL repository. If OcflOption.MOVE_SOURCE is specified, then files will be moved instead. Warning: If an exception occurs and the new version is not created, the files that were will be lost. This operation is more efficient but less safe than the default copy.

      By default, the change will be rejected if there is already a file in the object at the destinationPath. To overwrite, specify OcflOption.OVERWRITE.

      Parameters:
      sourcePath - the local file or directory to add to the object
      destinationPath - the logical path to store the sourcePath at within the object, an empty string indicates the object root
      options - optional config options. Use OcflOption.MOVE_SOURCE to move files into the repo instead of copying. Use OcflOption.OVERWRITE to overwrite existing files within an object
      Returns:
      this
      Throws:
      OverwriteException - if there is already a file at the destinationPath and OcflOption.OVERWRITE was not specified

    • unsafeAddPath

      OcflObjectUpdater unsafeAddPath(String digest, Path sourcePath, String destinationPath, OcflOption... options)
      Adds a file to the object at the specified destinationPath. The destinationPath is the logical path to the file within the object. Forward slashes MUST be used as filename separators in the path. It is important to keep this in mind on Windows systems, where backslashes MUST be converted to forward slashes.

      This method differs from addPath() in that it DOES NOT calculate the file's digest. The digest must be provided and it MUST use the same algorithm as the object's content digest algorithm. If a different algorithm is used or the digest is wrong, then the OCFL object will be corrupted. This method should only be used when performance is critical and the necessary digest was already calculated elsewhere.

      By default, files are copied into the OCFL repository. If OcflOption.MOVE_SOURCE is specified, then files will be moved instead. Warning: If an exception occurs and the new version is not created, the files that were will be lost. This operation is more efficient but less safe than the default copy.

      By default, the change will be rejected if there is already a file in the object at the destinationPath. To overwrite, specify OcflOption.OVERWRITE.

      Parameters:
      digest - the digest of the file. The digest MUST use the same algorithm as the object's content digest algorithm
      sourcePath - the local file to add to the object
      destinationPath - the logical path to store the sourcePath at within the object, an empty string indicates the object root
      options - optional config options. Use OcflOption.MOVE_SOURCE to move files into the repo instead of copying. Use OcflOption.OVERWRITE to overwrite existing files within an object
      Returns:
      this
      Throws:
      OverwriteException - if there is already a file at the destinationPath and OcflOption.OVERWRITE was not specified

    • writeFile

      OcflObjectUpdater writeFile(InputStream input, String destinationPath, OcflOption... options)
      Writes the contents of the InputStream to the object at the specified destinationPath. The destinationPath is the logical path to the file within the object. Forward slashes MUST be used as filename separators in the path. It is important to keep this in mind on Windows systems, where backslashes MUST be converted to forward slashes.

      Pass a FixityCheckInputStream to ensure transmission fixity.

      By default, the change will be rejected if there is already a file in the object at the destinationPath. To overwrite, specify OcflOption.OVERWRITE.

      Parameters:
      input - InputStream containing the content of a file to add to an object
      destinationPath - the logical path to store the file at within the object
      options - optional config options. Use OcflOption.OVERWRITE to overwrite existing files within an object
      Returns:
      this
      Throws:
      OverwriteException - if there is already a file at the destinationPath and OcflOption.OVERWRITE was not specified
      FixityCheckException - if the a FixityCheckInputStream is used and the digest does not match the expected value

    • removeFile

      OcflObjectUpdater removeFile(String path)
      Removes a file from the object. An exception is not thrown if there is nothing at the path.
      Parameters:
      path - the logical path of the file to remove
      Returns:
      this

    • renameFile

      OcflObjectUpdater renameFile(String sourcePath, String destinationPath, OcflOption... options)
      Renames an existing file within the object. Use OcflOption.OVERWRITE to overwrite an existing file at the destinationPath. The destinationPath is the logical path to the file within the object. Forward slashes MUST be used as filename separators in the path. It is important to keep this in mind on Windows systems, where backslashes MUST be converted to forward slashes.
      Parameters:
      sourcePath - the logical path to the file to be renamed
      destinationPath - the local path to rename the file to
      options - optional config options. Use OcflOption.OVERWRITE to overwrite existing files within an object
      Returns:
      this
      Throws:
      OverwriteException - if there is already a file at the destinationPath and OcflOption.OVERWRITE was not specified

    • reinstateFile

      OcflObjectUpdater reinstateFile(VersionNum sourceVersionNum, String sourcePath, String destinationPath, OcflOption... options)
      Reinstates a file that existed in any version of the object into the current version. This is useful when recovering a prior version of a file or adding back a file that was deleted. Use OcflOption.OVERWRITE to overwrite an existing file at the destinationPath. The destinationPath is the logical path to the file within the object. Forward slashes MUST be used as filename separators in the path. It is important to keep this in mind on Windows systems, where backslashes MUST be converted to forward slashes.
      Parameters:
      sourceVersionNum - the version number of the version to reinstate the sourcePath from. Cannot be the current version
      sourcePath - the logical path to the file to be reinstated
      destinationPath - the logical path to reinstate the file to
      options - optional config options. Use OcflOption.OVERWRITE to overwrite existing files within an object
      Returns:
      this
      Throws:
      OverwriteException - if there is already a file at the destinationPath and OcflOption.OVERWRITE was not specified

    • clearVersionState

      OcflObjectUpdater clearVersionState()
      The state of the current version of the object is cleared so that it does not reference any files. No files are deleted. This can be useful to simulate OcflRepository.putObject(io.ocfl.api.model.ObjectVersionId, java.nio.file.Path, io.ocfl.api.model.VersionInfo, io.ocfl.api.OcflOption...) like behavior.
      Returns:
      this

    • addFileFixity

      OcflObjectUpdater addFileFixity(String logicalPath, DigestAlgorithm algorithm, String value)
      Adds an entry to the object's fixity block. The fixity block is purely for informational and migration purposes. It is entirely optional, and is not OCFL's primary fixity mechanism.

      NOTE: This method should only be called for files that are added in the same OcflRepository.updateObject(io.ocfl.api.model.ObjectVersionId, io.ocfl.api.model.VersionInfo, java.util.function.Consumer<io.ocfl.api.OcflObjectUpdater>) call. If it's called for a file that was not newly added, it will check to see if the file already has an associated fixity digest with the same algorithm and compare the digest values. If the file does not have a pre-existing value, an exception is thrown.

      The digest of the file is calculated using the specified algorithm, and, if it doesn't match the expected value, a FixityCheckException is thrown.

      Parameters:
      logicalPath - the logical path of the file to add fixity information for
      algorithm - the digest algorithm
      value - the expected digest value
      Returns:
      this
      Throws:
      FixityCheckException - if the computed digest of the file does not match the expected value

    • clearFixityBlock

      OcflObjectUpdater clearFixityBlock()
      Clears the object's fixity block. The fixity block is primarily used for legacy migrations, and is not the primary OCFL fixity mechanism. The fixity block can be cleared when it is no longer needed.
      Returns:
      this