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 a 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     * Acquire a lock on the specified resource and any ghost nodes above it for this transaction.
134     *
135     * @param resourceId the resource to lock
136     * @throws ConcurrentUpdateException if the lock cannot be acquired
137     */
138    void lockResourceAndGhostNodes(final FedoraId resourceId);
139
140    /**
141     * Releases any resource locks held by the transaction if the session is short-lived. This method should always be
142     * called after handling a request, regardless of the outcome, so that any held locks are released immediately
143     * without having to wait for the short-lived transaction to expire.
144     */
145    void releaseResourceLocksIfShortLived();
146
147    /**
148     * Executes the runnable within the tx. While there are active runnables being executed, the tx may not be
149     * committed or rolledback. Runnables may only be executed when the tx is in an OPEN state and has not expired.
150     *
151     * @param runnable the code to execute within the tx
152     */
153    void doInTx(final Runnable runnable);
154
155    /**
156     * Sets the baseUri on the transaction
157     * @param baseUri the baseUri of the requests
158     */
159    void setBaseUri(final String baseUri);
160
161    /**
162     * Sets the user-agent on the transaction
163     * @param userAgent the request's user-agent
164     */
165    void setUserAgent(final String userAgent);
166
167    /**
168     * After invoking, any accumulated events will be suppressed.
169     */
170    void suppressEvents();
171
172}