Package edu.wisc.library.ocfl.core.storage

Class DefaultOcflStorage

java.lang.Object

edu.wisc.library.ocfl.core.storage.AbstractOcflStorage

edu.wisc.library.ocfl.core.storage.DefaultOcflStorage

All Implemented Interfaces:

OcflStorage

public class DefaultOcflStorage
extends AbstractOcflStorage

Implements the core logic for manipulating OCFL objects.

Field Summary

Fields inherited from class edu.wisc.library.ocfl.core.storage.AbstractOcflStorage

inventoryMapper, ocflVersion, supportEvaluator

Constructor Summary

Constructors

Constructor	Description
DefaultOcflStorage(Storage storage, boolean verifyInventoryDigest, OcflStorageInitializer initializer)	Creates a new DefaultOcflStorage object.

Method Summary

Modifier and Type	Method	Description
static OcflStorageBuilder	builder()	Create a new builder.
void	close()	Shutsdown any resources the OclfStorage may have open, such as ExecutorServices.
void	commitMutableHead(Inventory oldInventory, Inventory newInventory, Path stagingDir)	Moves the mutable HEAD of any object into the object root and into an immutable version.
boolean	containsObject(String objectId)	Returns true if an object with the specified id exists in the repository.
protected void	doInitialize(OcflExtensionConfig layoutConfig)	Does whatever is necessary to initialize OCFL repository storage.
void	exportObject(String objectId, Path outputPath)	Copies a raw OCFL object to the specified directory.
void	exportVersion(ObjectVersionId objectVersionId, Path outputPath)	Copies a raw OCFL object version to the specified directory.
byte[]	getInventoryBytes(String objectId, VersionNum versionNum)	Returns the raw inventory bytes for the specified object version
Map<String,OcflFileRetriever>	getObjectStreams(Inventory inventory, VersionNum versionNum)	Returns a map of OcflFileRetriever objects that are used to lazy-load object files.
void	importObject(String objectId, Path objectPath)	Moves an entire OCFL object into the repository.
Stream<String>	listObjectIds()	Returns a stream of object ids for all of the OCFL objects stored in a repository.
Inventory	loadInventory(String objectId)	Returns a verified copy of the most recent object inventory.
String	objectRootPath(String objectId)	Returns the path from the storage root to the object root.
void	purgeMutableHead(String objectId)	Permanently removes the mutable HEAD of an object.
void	purgeObject(String objectId)	Permanently removes an object from the repository.
void	reconstructObjectVersion(Inventory inventory, VersionNum versionNum, Path stagingDir)	Reconstructs a complete object at the specified version in the stagingDir.
void	rollbackToVersion(Inventory inventory, VersionNum versionNum)	Sets the head object version to the specified version by reinstating that version's inventory into the object root, and purging all intermediary versions.
void	storeNewVersion(Inventory inventory, Path stagingDir)	Persists a fully composed object version.
ValidationResults	validateObject(String objectId, boolean contentFixityCheck)	Validates the specified object against the OCFL 1.0 spec.

Methods inherited from class edu.wisc.library.ocfl.core.storage.AbstractOcflStorage

ensureOpen, initializeStorage, invalidateCache, invalidateCache

Methods inherited from class java.lang.Object

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

Constructor Detail

DefaultOcflStorage

public DefaultOcflStorage(Storage storage,
                          boolean verifyInventoryDigest,
                          OcflStorageInitializer initializer)

Creates a new DefaultOcflStorage object.

AbstractOcflStorage.initializeStorage(edu.wisc.library.ocfl.api.model.OcflVersion, edu.wisc.library.ocfl.core.extension.OcflExtensionConfig, edu.wisc.library.ocfl.core.inventory.InventoryMapper, edu.wisc.library.ocfl.core.extension.ExtensionSupportEvaluator) must be called before using this object.

Parameters:

storage - the abstraction over the underlying storage system that contains the OCFL repository

verifyInventoryDigest - true if inventory digests should be verified on read

initializer - initializes a new OCFL repo

See Also:

OcflStorageBuilder

Method Detail

builder

public static OcflStorageBuilder builder()

Create a new builder.

Returns:

builder

loadInventory

public Inventory loadInventory(String objectId)

Returns a verified copy of the most recent object inventory. Null is returned if the object is not found.

DefaultOcflRepository calls this method within a read lock and caches the result.

Parameters:

objectId - the id of the object to load

Returns:

the deserialized inventory or null if the object was not found

getInventoryBytes

public byte[] getInventoryBytes(String objectId,
                                VersionNum versionNum)

Returns the raw inventory bytes for the specified object version

Parameters:

objectId - the id of the object

versionNum - the version number

Returns:

the raw inventory bytes

listObjectIds

public Stream<String> listObjectIds()

Returns a stream of object ids for all of the OCFL objects stored in a repository. This stream is populated on demand, and it may be quite slow. Remember to close the stream when you are done with it.

Returns:

stream of object ids

storeNewVersion

public void storeNewVersion(Inventory inventory,
                            Path stagingDir)

Persists a fully composed object version. The contents of the stagingDir are the contents of the new version, including a serialized copy of the updated inventory. It is safe to move the entire stagingDir to object-root/version.

DefaultOcflRepository calls this method from a write lock.

This method MUST ensure that the version to be persisted is not out of sync with the current object state, and reject the request if it is.

After persisting the new version directory, the new inventory file is installed in the object root.

Parameters:

inventory - the updated object inventory

stagingDir - the directory that contains the composed contents of the new object version

getObjectStreams

public Map<String,OcflFileRetriever> getObjectStreams(Inventory inventory,
                                                            VersionNum versionNum)

Returns a map of OcflFileRetriever objects that are used to lazy-load object files. The map keys are the object relative file paths of all of the files in the specified version of the object.

Parameters:

inventory - the object's inventory

versionNum - the id of the version to load

Returns:

a map of OcflFileRetriever objects keyed off the object relative file paths of all of the files in the object

reconstructObjectVersion

public void reconstructObjectVersion(Inventory inventory,
                                     VersionNum versionNum,
                                     Path stagingDir)

Reconstructs a complete object at the specified version in the stagingDir.

The fixity of every file must be checked after copying it to the stagingDir.

Parameters:

inventory - the deserialized object inventory

versionNum - the id of the version to reconstruct

stagingDir - the location the reconstructed object should be assembled in

purgeObject

public void purgeObject(String objectId)

Permanently removes an object from the repository. Objects that have been purged are NOT recoverable. If an object with the specified id cannot be found it is considered purged and no exception is thrown.

DefaultOcflRepository calls this method from a write lock.

Parameters:

objectId - the id of the object to purge

rollbackToVersion

public void rollbackToVersion(Inventory inventory,
                              VersionNum versionNum)

Sets the head object version to the specified version by reinstating that version's inventory into the object root, and purging all intermediary versions.

Parameters:

inventory - the deserialized object inventory

versionNum - the id of the version to rollback to

commitMutableHead

public void commitMutableHead(Inventory oldInventory,
                              Inventory newInventory,
                              Path stagingDir)

Moves the mutable HEAD of any object into the object root and into an immutable version. The mutable HEAD does not exist at the end of the operation.

DefaultOcflRepository calls this method from a write lock.

Parameters:

oldInventory - the deserialized inventory of the object BEFORE it was rewritten for the commit

newInventory - the deserialized inventory of the object AFTER it was rewritten for the commit

stagingDir - the path to the staging directory that contains the inventory files

purgeMutableHead

public void purgeMutableHead(String objectId)

Permanently removes the mutable HEAD of an object. If the object does not have a mutable HEAD nothing happens.

DefaultOcflRepository calls this method from a write lock.

Parameters:

objectId - the id of the object to purge the mutable HEAD of

containsObject

public boolean containsObject(String objectId)

Returns true if an object with the specified id exists in the repository.

Parameters:

objectId - the id of the object

Returns:

true if the object exists and false otherwise

objectRootPath

public String objectRootPath(String objectId)

Returns the path from the storage root to the object root.

Parameters:

objectId - the id of the object

Returns:

the relative path from the storage root to the object root

exportVersion

public void exportVersion(ObjectVersionId objectVersionId,
                          Path outputPath)

Copies a raw OCFL object version to the specified directory. For example, if you export version 2 of an object, then the entire contents of the object's v2 directory will be exported the output directory. This is primarily useful for backing up OCFL versions, as an isolated OCFL object version is not usable in and of itself.

The outputPath MUST NOT exist, but its parent MUST exist.

Mutable HEAD versions cannot be exported

Parameters:

objectVersionId - the id of the object and version to export

outputPath - the directory to write the exported version to, must NOT exist

exportObject

public void exportObject(String objectId,
                         Path outputPath)

Copies a raw OCFL object to the specified directory. The output is a complete copy of everything that's contained in the object's root directory.

The outputPath MUST NOT exist, but its parent MUST exist.

Parameters:

objectId - the id of the object to export

outputPath - the directory to write the exported object to, must NOT exist

importObject

public void importObject(String objectId,
                         Path objectPath)

Moves an entire OCFL object into the repository. This object cannot already exist.

Parameters:

objectId - the id of the object to import

objectPath - the directory that contains the object to import

validateObject

public ValidationResults validateObject(String objectId,
                                        boolean contentFixityCheck)

Validates the specified object against the OCFL 1.0 spec.

Parameters:

objectId - the id of the object to validate

contentFixityCheck - true if the fixity of the content files should be verified

Returns:

the validation results

close

public void close()

Shutsdown any resources the OclfStorage may have open, such as ExecutorServices. Once closed, additional requests will be rejected. Calling this method is optional, and it is more efficient to just let the shutdown hooks take care of closing the resources.

Specified by:

close in interface OcflStorage

Overrides:

close in class AbstractOcflStorage

doInitialize

protected void doInitialize(OcflExtensionConfig layoutConfig)

Description copied from class: AbstractOcflStorage

Does whatever is necessary to initialize OCFL repository storage.

Specified by:

doInitialize in class AbstractOcflStorage

Parameters:

layoutConfig - the storage layout configuration, may be null to auto-detect existing configuration