Package io.ocfl.api

Interface MutableOcflRepository

All Superinterfaces:

OcflRepository

public interface MutableOcflRepository
extends OcflRepository

Defines APIs for implementing the OCFL Mutable HEAD Extension. These APIs are outside of the scope of the core OCFL specification, and provide additional functionality for staging object content within the OCFL storage root before committing it to a version. It is imperative to understand that staged content is NOT part of the core OCFL object, and it CANNOT be interpreted by an OCFL client that does not implement the Mutable HEAD Extension.

Method Summary

Modifier and Type	Method	Description
ObjectVersionId	commitStagedChanges(String objectId, VersionInfo versionInfo)	Converts the staged changes in the mutable HEAD into an immutable core OCFL version that can be read by any OCFL client.
boolean	hasStagedChanges(String objectId)	Returns true if the object has staged changes (mutable HEAD).
void	purgeStagedChanges(String objectId)	Deletes the staged changes (mutable HEAD) of the specified object.
ObjectVersionId	stageChanges(ObjectVersionId objectId, VersionInfo versionInfo, Consumer<OcflObjectUpdater> objectUpdater)	Stages changes to the mutable HEAD of the specified object.

Methods inherited from interface io.ocfl.api.OcflRepository

close, config, containsObject, describeObject, describeVersion, exportObject, exportVersion, fileChangeHistory, getObject, getObject, importObject, importVersion, invalidateCache, invalidateCache, listObjectIds, purgeObject, putObject, replicateVersionAsHead, rollbackToVersion, updateObject, validateObject

Method Detail

stageChanges

ObjectVersionId stageChanges(ObjectVersionId objectId,
                             VersionInfo versionInfo,
                             Consumer<OcflObjectUpdater> objectUpdater)

Stages changes to the mutable HEAD of the specified object. If the object does not already have a mutable HEAD, a new one is created. Otherwise, the changes are applied on top of the existing mutable HEAD, without creating a new version.

The changes contained in the mutable HEAD are NOT part of the core OCFL object. Use commitStagedChanges(java.lang.String, io.ocfl.api.model.VersionInfo) to convert the mutable version into an immutable version that's part of the core OCFL object. This should be done whenever possible.

If the current HEAD version of the object does not match the version specified in the request, the update will be rejected. If the request specifies the HEAD version, then no version check will be preformed.

Parameters:

objectId - the id of the object. If set to a specific version, then the update will only occur if this version matches the head object version in the repository.

versionInfo - information about the changes to the object. Can be null.

objectUpdater - code block within which updates to an object may be made

Returns:

The objectId and version of the new object version

Throws:

NotFoundException - when no object can be found for the specified objectId

ObjectOutOfSyncException - when the object was modified by another process before these changes could be committed

commitStagedChanges

ObjectVersionId commitStagedChanges(String objectId,
                                    VersionInfo versionInfo)

Converts the staged changes in the mutable HEAD into an immutable core OCFL version that can be read by any OCFL client.

This operation will fail if any object versions were created between the time changes were staged and when they were committed. To resolve this problem, the staged changes must either be purged using purgeStagedChanges(java.lang.String), or the object must be manually edited to resolve the version conflict.

If the object does not have staged changes, then nothing happens.

Parameters:

objectId - the id of the object

versionInfo - information about the changes to the object. Can be null.

Returns:

The objectId and version of the committed version

Throws:

NotFoundException - when no object can be found for the specified objectId

ObjectOutOfSyncException - when the object was modified by another process before these changes could be committed

purgeStagedChanges

void purgeStagedChanges(String objectId)

Deletes the staged changes (mutable HEAD) of the specified object. If the object does not have staged changes, then nothing happens.

Parameters:

objectId - the id of the object

Throws:

NotFoundException - when no object can be found for the specified objectId

hasStagedChanges

boolean hasStagedChanges(String objectId)

Returns true if the object has staged changes (mutable HEAD).

Parameters:

objectId - the id of the object

Returns:

if the object has staged changes or does not exist