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