001/*
002 * Licensed to DuraSpace under one or more contributor license agreements.
003 * See the NOTICE file distributed with this work for additional information
004 * regarding copyright ownership.
005 *
006 * DuraSpace licenses this file to you under the Apache License,
007 * Version 2.0 (the "License"); you may not use this file except in
008 * compliance with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.fcrepo.persistence.api;
019
020import java.io.InputStream;
021import java.time.Instant;
022import java.util.List;
023
024import org.fcrepo.kernel.api.RdfStream;
025import org.fcrepo.kernel.api.identifiers.FedoraId;
026import org.fcrepo.kernel.api.models.ResourceHeaders;
027import org.fcrepo.kernel.api.operations.ResourceOperation;
028import org.fcrepo.persistence.api.exceptions.PersistentStorageException;
029
030/**
031 * An interface that mediates CRUD operations to and from persistence storage.
032 *
033 * @author dbernstein
034 * @author whikloj
035 */
036public interface PersistentStorageSession {
037
038    /**
039     * Return the ID for this session, or null for a read-only session.
040     *
041     * @return the session id.
042     */
043    String getId();
044
045    /**
046     * Perform a persistence operation on a resource
047     *
048     * @param operation The persistence operation to perform
049     * @throws PersistentStorageException Error persisting the resource.
050     */
051    void persist(final ResourceOperation operation)
052            throws PersistentStorageException;
053
054    /**
055     * Get the header information for the identified resource.
056     *
057     * @param identifier identifier of the resource
058     * @param version instant identifying the version of the resource to read from.
059     *      If null, then the head version is used.
060     * @return header information
061     * @throws PersistentStorageException  Either a PersistentItemNotFoundException or PersistentSessionClosedException
062     */
063    ResourceHeaders getHeaders(final FedoraId identifier, final Instant version)
064            throws PersistentStorageException;
065
066    /**
067     * Get the client managed triples 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 triples as an RdfStream.
073     * @throws PersistentStorageException  Either a PersistentItemNotFoundException or PersistentSessionClosedException
074     */
075    RdfStream getTriples(final FedoraId identifier, final Instant version)
076            throws PersistentStorageException;
077
078    /**
079     * Get the persisted binary content for the provided resource.
080     *
081     * @param identifier identifier for the resource.
082     * @param version instant identifying the version of the resource to read from. If null, then the head version is
083     *        used.
084     * @return the binary content.
085     * @throws PersistentStorageException  Either a PersistentItemNotFoundException or PersistentSessionClosedException
086     */
087    InputStream getBinaryContent(final FedoraId identifier, final Instant version)
088            throws PersistentStorageException;
089
090    /**
091     * Returns a list of immutable versions associated with the specified fedora identifier in ascending order
092     * by creation time of the version.
093     *
094     * @param identifier identifier for the resource.
095     * @return The list of instants that map to the underlying versions, ordered by time created
096     * @throws PersistentStorageException  Either a PersistentItemNotFoundException or PersistentSessionClosedException
097     */
098    List<Instant> listVersions(final FedoraId identifier)
099            throws PersistentStorageException;
100
101    /**
102     * Does anything that's necessary to prepare the session to be committed, for example committing database
103     * changes. This method MUST be called before commit(). If prepare() fails, then the session should be rolled back.
104     * @throws PersistentStorageException if an error is encountered
105     */
106    void prepare() throws PersistentStorageException;
107
108    /**
109     * Commits any changes in the current session to persistent storage.
110     * @throws PersistentStorageException Error during commit.
111     */
112    void commit() throws PersistentStorageException;
113
114    /**
115     * Rolls back any changes in the current session.
116     *
117     * @throws PersistentStorageException Error completing rollback.
118     */
119    void rollback() throws PersistentStorageException;
120
121}