Package io.ocfl.api

Interface OcflRepository

  • All Known Subinterfaces:
    MutableOcflRepository
    public interface OcflRepository
    Interface for interacting with an OCFL repository.

    • Method Detail

      • putObject

        ObjectVersionId putObject​(ObjectVersionId objectVersionId,
                          Path path,
                          VersionInfo versionInfo,
                          OcflOption... options)
        Adds the object rooted at the given path to the OCFL repository under the given objectVersionId. If their is an existing object with the id, then a new version of the object is created.

        It is important to note that this is NOT an additive operation. An existing object's state is NOT carried forward into the new version. The only files that are included in the new version are the files that are present in the supplied directory. However, files are still deduped against files present in prior versions.

        This method should only be used when writing new or fully composed objects.

        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.

        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.

        Parameters:
        objectVersionId - the id to store the object under. If set to a specific version, then the update will only occur if the specified version matches the head object version in the repository.
        path - the path to the object content
        versionInfo - information about the changes to the object. Can be null.
        options - optional config options. Use OcflOption.MOVE_SOURCE to move files into the repo instead of copying.
        Returns:
        The objectId and version of the new object version
        Throws:
        ObjectOutOfSyncException - when the object was modified by another process before these changes could be committed

      • updateObject

        ObjectVersionId updateObject​(ObjectVersionId objectVersionId,
                             VersionInfo versionInfo,
                             Consumer<OcflObjectUpdater> objectUpdater)
        Updates an existing object OR create a new object by selectively adding, removing, moving files within the object, and creating a new version that encapsulates all of the changes. It always operates on the HEAD version of an object, but a specific version can be specified to ensure no intermediate changes were made to the object.

        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:
        objectVersionId - the id of the object. If set to a specific version, then the update will only occur if the specified 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 objectVersionId
        ObjectOutOfSyncException - when the object was modified by another process before these changes could be committed

      • getObject

        void getObject​(ObjectVersionId objectVersionId,
               Path outputPath)
        Returns the entire contents of the object at the specified version. The outputPath MUST NOT exist, but its parent MUST exist.
        Parameters:
        objectVersionId - the id and version of an object to retrieve
        outputPath - the directory to write the object files to, must NOT exist
        Throws:
        NotFoundException - when no object can be found for the specified objectVersionId

      • getObject

        OcflObjectVersion getObject​(ObjectVersionId objectVersionId)
        Returns the details about a specific version of an object along with lazy-loading handles to all of the files in the object.
        Parameters:
        objectVersionId - the id and version of an object to retrieve
        Returns:
        lazy-loading object version
        Throws:
        NotFoundException - when no object can be found for the specified objectVersionId

      • describeObject

        ObjectDetails describeObject​(String objectId)
        Returns all of the details about an object and all of its versions.
        Parameters:
        objectId - the id of the object to describe
        Returns:
        details about the object
        Throws:
        NotFoundException - when no object can be found for the specified objectId

      • describeVersion

        VersionDetails describeVersion​(ObjectVersionId objectVersionId)
        Returns the details about a specific version of an object.
        Parameters:
        objectVersionId - the id and version of the object to describe
        Returns:
        details about the object version
        Throws:
        NotFoundException - when no object can be found for the specified objectVersionId

      • fileChangeHistory

        FileChangeHistory fileChangeHistory​(String objectId,
                                    String logicalPath)
        Retrieves the complete change history for a logical path within an object. Each entry in the change history marks an object version where the contents at the logical path were changed or the logical path was removed. Object versions where there were no changes to the logical path are not included.
        Parameters:
        objectId - the id of the object
        logicalPath - the logical path
        Returns:
        the change history for the logical path
        Throws:
        NotFoundException - when object or logical path cannot be found

      • containsObject

        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

      • listObjectIds

        Stream<String> listObjectIds()
        Returns a stream of OCFL object ids for all of the objects stored in the repository. This stream is populated on demand. Warning: Iterating over every object id may be quite slow. Remember to close the stream when you are done with it.
        Returns:
        steam of all OCFL object ids

      • purgeObject

        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.
        Parameters:
        objectId - the id of the object to purge

      • validateObject

        ValidationResults validateObject​(String objectId,
                                 boolean contentFixityCheck)
        Validates an existing object against the OCFL spec and returns a report containing all of the issues that were found with their accompanying validation code.

        The validation does NOT lock the object, which means that if an object is updated while the object is in the process of being validated, then the results may be inaccurate.

        If a fixity check is requested, then this call may be quite expensive as it will have to calculate the digests of every file in the object.

        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
        Throws:
        NotFoundException - if the object does not exist.

      • replicateVersionAsHead

        ObjectVersionId replicateVersionAsHead​(ObjectVersionId objectVersionId,
                                       VersionInfo versionInfo)
        Creates a new head version by copying the state of the specified version. This is a non-destructive way to roll an object back to a prior version without altering its version history.

        Use rollbackToVersion(io.ocfl.api.model.ObjectVersionId) instead if you want to roll an object back to a prior version by purging all intermediary versions.

        Parameters:
        objectVersionId - the id of the object and version to replicate
        versionInfo - information about the changes to the object. Can be null.
        Returns:
        The objectId and version of the new object version
        Throws:
        NotFoundException - when no object can be found for the specified objectVersionId

      • rollbackToVersion

        void rollbackToVersion​(ObjectVersionId objectVersionId)
        Rolls an object back to the specified version. The specified version must exist and is made the head version. Any intermediary versions are PURGED. There is no way to recover versions that are purged as part of rolling back to a previous version.

        Use replicateVersionAsHead(io.ocfl.api.model.ObjectVersionId, io.ocfl.api.model.VersionInfo) instead if you want to roll an object back to a prior version but do not want to delete intermediary versions.

        Using this method is NOT recommended unless necessary as it is inconsistent with the OCFL paradigm of version permanence.

        Parameters:
        objectVersionId - the id of the object and version to rollback to
        Throws:
        NotFoundException - when no object can be found for the specified objectVersionId

      • exportVersion

        void exportVersion​(ObjectVersionId objectVersionId,
                   Path outputPath,
                   OcflOption... options)
        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.

        Mutable HEAD versions cannot be exported

        This method WILL NOT cleanup files left in the output directory if it fails.

        Parameters:
        objectVersionId - the id of the object and version to export
        outputPath - the directory to write the exported version to, if it does not exist it will be created
        options - optional config options.
        Throws:
        NotFoundException - when no object can be found for the specified objectVersionId

      • exportObject

        void exportObject​(String objectId,
                  Path outputPath,
                  OcflOption... options)
        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.

        This method WILL NOT cleanup files left in the output directory if it fails.

        Parameters:
        objectId - the id of the object to export
        outputPath - the directory to write the exported object to, if it does not exist it will be created
        options - optional config options. Use OcflOption.NO_VALIDATION to disable export validation.
        Throws:
        NotFoundException - when no object can be found for the specified objectId
        ValidationException - when the exported object fails validation

      • importVersion

        void importVersion​(Path versionPath,
                   OcflOption... options)
        Imports the OCFL object version at the specified path into the repository. In order to successfully import the version the following conditions must be met:
        • The import version must be valid
        • The import version must be the next sequential version of the current version of the object in the repository
        • The version history of in the import version must be identical to the existing version history
        • Inventory level properties such as digest algorithm and type cannot change
        Parameters:
        versionPath - path to the OCFL object version to import on disk
        options - optional config options. Use OcflOption.MOVE_SOURCE to move files into the repo instead of copying. Use OcflOption.NO_VALIDATION to disable file validation, version inventory is still validated.
        Throws:
        OcflStateException - if the version number of the import is not the next sequential version for the object

      • importObject

        void importObject​(Path objectPath,
                  OcflOption... options)
        Imports an entire OCFL object into the repository. The object cannot already exist in the repository, and the object must be valid. The object is validated extensively as part of the import process.
        Parameters:
        objectPath - path to the OCFL object to import on disk
        options - optional config options. Use OcflOption.MOVE_SOURCE to move files into the repo instead of copying. Use OcflOption.NO_VALIDATION to disable file validation, root inventory is still validated.
        Throws:
        AlreadyExistsException - if the object trying to be imported is already in the repository

      • close

        void close()
        Closes any resources the OcflRepository 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.

      • config

        OcflConfig config()
        Returns a copy of the OCFL configuration.
        Returns:
        copy of the OCFL configuration

      • invalidateCache

        void invalidateCache​(String objectId)
        If the OcflRepository is using an inventory cache, then this method invalidates the cache entry for the specified object. Otherwise, nothing happens.
        Parameters:
        objectId - the ID of the object to invalidate in the cache

      • invalidateCache

        void invalidateCache()
        If the OcflRepository is using an inventory cache, then this method invalidates all entries in the cache. Otherwise, nothing happens.