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.kernel.api;
019
020import org.fcrepo.kernel.api.exception.ConcurrentUpdateException;
021import org.fcrepo.kernel.api.exception.TransactionRuntimeException;
022import org.fcrepo.kernel.api.identifiers.FedoraId;
023
024import java.time.Duration;
025import java.time.Instant;
026
027/**
028 * The Fedora Transaction abstraction
029 *
030 * @author mohideen
031 */
032public interface Transaction {
033
034    /**
035     * Commit the transaction
036     */
037    void commit();
038
039    /**
040     * Commit the transaction only if the transaction is shortLived
041     */
042    void commitIfShortLived();
043
044    /**
045     * @return returns true if this transaction has already been committed
046     */
047    boolean isCommitted();
048
049    /**
050     * Rollback the transaction
051     */
052    void rollback();
053
054    /**
055     * Marks the transaction as failed. Failed transactions cannot be committed but may be rolledback.
056     */
057    void fail();
058
059    /**
060     * @return true if this transaction has been rolled back
061     */
062    boolean isRolledBack();
063
064    /**
065     * @return true if the tx is a long-running tx that has not expired and is not in a
066     * COMMITTED, ROLLEDBACK, or FAILED state
067     */
068    boolean isOpenLongRunning();
069
070    /**
071     * @return true if the tx is in an OPEN state and has not expired
072     */
073    boolean isOpen();
074
075    /**
076     * Throws an exception if the tx is not in a COMMITTING state
077     * @throws TransactionRuntimeException when not in committing
078     */
079    void ensureCommitting();
080
081    /**
082     * @return true the tx is read-only
083     */
084    boolean isReadOnly();
085
086    /**
087     * Get the transaction id
088     *
089     * @return the transaction id.
090     */
091    String getId();
092
093    /**
094     * Check if the transaction is short-lived.
095     *
096     * @return is the transaction short-lived.
097     */
098    boolean isShortLived();
099
100    /**
101     * Set transaction short-lived state.
102     *
103     * @param shortLived boolean true (short-lived) or false (not short-lived)
104     */
105    void setShortLived(final boolean shortLived);
106
107    /**
108     * Expire a transaction
109     */
110    void expire();
111
112    /**
113     * Has the transaction expired?
114     * @return true if expired
115     */
116    boolean hasExpired();
117
118    /**
119    * Update the expiry by the provided amount
120    * @param amountToAdd the amount of time to add
121    * @return the new expiration date
122    */
123    Instant updateExpiry(final Duration amountToAdd);
124
125    /**
126     * Get the date this session expires
127     * @return expiration date, if one exists
128     */
129    Instant getExpires();
130
131    /**
132     * Refresh the transaction to extend its expiration window.
133     */
134    void refresh();
135
136    /**
137     * Acquires a lock on the specified resource for this transaction.
138     *
139     * @param resourceId the resource to lock
140     * @throws ConcurrentUpdateException if the lock cannot be acquired
141     */
142    void lockResource(final FedoraId resourceId);
143
144    /**
145     * Releases any resource locks held by the transaction if the session is short-lived. This method should always be
146     * called after handling a request, regardless of the outcome, so that any held locks are released immediately
147     * without having to wait for the short-lived transaction to expire.
148     */
149    void releaseResourceLocksIfShortLived();
150
151    /**
152     * Executes the runnable within the tx. While there are active runnables being executed, the tx may not be
153     * committed or rolledback. Runnables may only be executed when the tx is in an OPEN state and has not expired.
154     *
155     * @param runnable the code to execute within the tx
156     */
157    void doInTx(final Runnable runnable);
158
159    /**
160     * Sets the baseUri on the transaction
161     * @param baseUri the baseUri of the requests
162     */
163    void setBaseUri(final String baseUri);
164
165    /**
166     * Sets the user-agent on the transaction
167     * @param userAgent the request's user-agent
168     */
169    void setUserAgent(final String userAgent);
170
171}