001/*
002 * The contents of this file are subject to the license and copyright
003 * detailed in the LICENSE and NOTICE files at the root of the source
004 * tree.
005 */
006package org.fcrepo.persistence.ocfl.api;
007
008import javax.annotation.Nonnull;
009
010import org.fcrepo.kernel.api.Transaction;
011import org.fcrepo.kernel.api.identifiers.FedoraId;
012import org.fcrepo.persistence.ocfl.impl.FedoraOcflMapping;
013
014/**
015 * @author dbernstein
016 * @since 6.0.0
017 */
018public interface FedoraToOcflObjectIndex {
019
020    /**
021     * Retrieve identification information for the OCFL object which either contains, or is identified by,
022     * the provided fedora resource id. In other words the method will find the closest resource that is persisted
023     * as an OCFL object and returns its identifiers.
024     *
025     * If you pass fedora identifier that is not part of an archival group such as
026     * "my/fedora/binary/fcr:metadata"  the  fedora resource returned in the mapping will be "my/fedora/binary".
027     *
028     * Contrast this  with an Archival Group example:  if you pass in "my/archival-group/binary/fcr:metadata" the
029     * resource returned in the mapping would be "my/archival-group".
030     *
031     * @param session the current session, or null for read-only.
032     * @param fedoraResourceIdentifier the fedora resource identifier
033     *
034     * @return the mapping
035     * @throws FedoraOcflMappingNotFoundException when no mapping exists for the specified identifier.
036     */
037    FedoraOcflMapping getMapping(final Transaction session, final FedoraId fedoraResourceIdentifier)
038            throws FedoraOcflMappingNotFoundException;
039
040    /**
041     * Adds a mapping to the index
042     *
043     * @param session the current session.
044     * @param fedoraResourceIdentifier The fedora resource
045     * @param fedoraRootObjectIdentifier   The identifier of the root fedora object resource
046     * @param ocflObjectId             The ocfl object id
047     * @return  The newly created mapping
048     */
049    FedoraOcflMapping addMapping(@Nonnull Transaction session, final FedoraId fedoraResourceIdentifier,
050                                 final FedoraId fedoraRootObjectIdentifier, final String ocflObjectId);
051
052    /**
053     * Removes a mapping
054     *
055     * @param session the current session.
056     * @param fedoraResourceIdentifier The fedora resource to remove the mapping for
057     */
058    void removeMapping(@Nonnull final Transaction session, final FedoraId fedoraResourceIdentifier);
059
060    /**
061     * Remove all persistent state associated with the index.
062     */
063    void reset();
064
065    /**
066     * Commit mapping changes for the session.
067     *
068     * @param session the session to commit.
069     */
070    void commit(@Nonnull final Transaction session);
071
072    /**
073     * Rollback mapping changes for the session.
074     *
075     * @param session the session to rollback.
076     */
077    void rollback(@Nonnull final Transaction session);
078
079}
080