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.api;
007
008import java.io.InputStream;
009import java.time.Instant;
010import java.util.List;
011
012import org.fcrepo.kernel.api.RdfStream;
013import org.fcrepo.kernel.api.identifiers.FedoraId;
014import org.fcrepo.kernel.api.models.ResourceHeaders;
015import org.fcrepo.kernel.api.operations.ResourceOperation;
016import org.fcrepo.persistence.api.exceptions.PersistentStorageException;
017
018/**
019 * An interface that mediates CRUD operations to and from persistence storage.
020 *
021 * @author dbernstein
022 * @author whikloj
023 */
024public interface PersistentStorageSession {
025
026    /**
027     * Return the ID for this session, or null for a read-only session.
028     *
029     * @return the session id.
030     */
031    String getId();
032
033    /**
034     * Perform a persistence operation on a resource
035     *
036     * @param operation The persistence operation to perform
037     * @throws PersistentStorageException Error persisting the resource.
038     */
039    void persist(final ResourceOperation operation)
040            throws PersistentStorageException;
041
042    /**
043     * Get the header information for the identified resource.
044     *
045     * @param identifier identifier of the resource
046     * @param version instant identifying the version of the resource to read from.
047     *      If null, then the head version is used.
048     * @return header information
049     * @throws PersistentStorageException  Either a PersistentItemNotFoundException or PersistentSessionClosedException
050     */
051    ResourceHeaders getHeaders(final FedoraId identifier, final Instant version)
052            throws PersistentStorageException;
053
054    /**
055     * Get the client managed triples for the provided resource.
056     *
057     * @param identifier identifier for the resource.
058     * @param version instant identifying the version of the resource to read from. If null, then the head version is
059     *        used.
060     * @return the triples as an RdfStream.
061     * @throws PersistentStorageException  Either a PersistentItemNotFoundException or PersistentSessionClosedException
062     */
063    RdfStream getTriples(final FedoraId identifier, final Instant version)
064            throws PersistentStorageException;
065
066    /**
067     * Get the persisted binary content for the provided resource.
068     *
069     * @param identifier identifier for the resource.
070     * @param version instant identifying the version of the resource to read from. If null, then the head version is
071     *        used.
072     * @return the binary content.
073     * @throws PersistentStorageException  Either a PersistentItemNotFoundException or PersistentSessionClosedException
074     */
075    InputStream getBinaryContent(final FedoraId identifier, final Instant version)
076            throws PersistentStorageException;
077
078    /**
079     * Returns a list of immutable versions associated with the specified fedora identifier in ascending order
080     * by creation time of the version.
081     *
082     * @param identifier identifier for the resource.
083     * @return The list of instants that map to the underlying versions, ordered by time created
084     * @throws PersistentStorageException  Either a PersistentItemNotFoundException or PersistentSessionClosedException
085     */
086    List<Instant> listVersions(final FedoraId identifier)
087            throws PersistentStorageException;
088
089    /**
090     * Does anything that's necessary to prepare the session to be committed, for example committing database
091     * changes. This method MUST be called before commit(). If prepare() fails, then the session should be rolled back.
092     * @throws PersistentStorageException if an error is encountered
093     */
094    void prepare() throws PersistentStorageException;
095
096    /**
097     * Commits any changes in the current session to persistent storage.
098     * @throws PersistentStorageException Error during commit.
099     */
100    void commit() throws PersistentStorageException;
101
102    /**
103     * Rolls back any changes in the current session.
104     *
105     * @throws PersistentStorageException Error completing rollback.
106     */
107    void rollback() throws PersistentStorageException;
108
109}