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

Interface OcflStorage

    • Method Detail

      • initializeStorage

        void initializeStorage​(OcflVersion ocflVersion,
                       OcflExtensionConfig layoutConfig,
                       InventoryMapper inventoryMapper,
                       ExtensionSupportEvaluator supportEvaluator)
        Initializes the OCFL root. If it is an existing OCFL repository and the root has already been initialized, then this method should do nothing. This method must be called before the object may be used.

        layoutConfig may be null if the OCFL repository already exists, in which case the existing configuration is used. If layoutConfig is specified for an existing repository, initialization will fail if the configurations do not match.

        Parameters:
        ocflVersion - the OCFL version
        layoutConfig - the storage layout configuration, may be null to auto-detect existing configuration
        inventoryMapper - the mapper to use for inventory serialization
        supportEvaluator - the evaluator that determines what to do when unsupported extensions are encountered

      • loadInventory

        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
        Throws:
        FixityCheckException - if the inventory fails its fixity check

      • getInventoryBytes

        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
        Throws:
        NotFoundException - if object or version cannot be found

      • storeNewVersion

        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
        Throws:
        ObjectOutOfSyncException - if the version cannot be created because it already exists
        FixityCheckException - if one of the files in the version fails its fixity check

      • getObjectStreams

        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

        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
        Throws:
        FixityCheckException - if one of the files fails its fixity check

      • 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.

        DefaultOcflRepository calls this method from a write lock.

        Parameters:
        objectId - the id of the object to purge

      • commitMutableHead

        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

        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

      • rollbackToVersion

        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

      • 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

      • objectRootPath

        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

      • listObjectIds

        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

      • exportVersion

        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
        Throws:
        NotFoundException - when no object can be found for the specified objectVersionId

      • exportObject

        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
        Throws:
        NotFoundException - when no object can be found for the specified objectId

      • importObject

        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

      • close

        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.

      • validateObject

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

      • invalidateCache

        void invalidateCache​(String objectId)
        If the OcflStorage 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 OcflStorage is using an inventory cache, then this method invalidates all entries in the cache. Otherwise, nothing happens.