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 Summary

Modifier and Type	Method	Description
OcflObjectUpdater	addFileFixity(String logicalPath, DigestAlgorithm algorithm, String value)	Adds an entry to the object's fixity block.
OcflObjectUpdater	addPath(Path sourcePath, OcflOption... options)	Adds a file or directory to the object.
OcflObjectUpdater	addPath(Path sourcePath, String destinationPath, OcflOption... options)	Adds a file or directory to the object at the specified destinationPath.
OcflObjectUpdater	clearFixityBlock()	Clears the object's fixity block.
OcflObjectUpdater	clearVersionState()	The state of the current version of the object is cleared so that it does not reference any files.
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.
OcflObjectUpdater	removeFile(String path)	Removes a file from the object.
OcflObjectUpdater	renameFile(String sourcePath, String destinationPath, OcflOption... options)	Renames an existing file within the object.
OcflObjectUpdater	unsafeAddPath(String digest, Path sourcePath, String destinationPath, OcflOption... options)	Adds a file to the object at the specified destinationPath.
OcflObjectUpdater	writeFile(InputStream input, String destinationPath, OcflOption... options)	Writes the contents of the InputStream to the object at the specified destinationPath.

Method Detail

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