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.identifiers.FedoraId;
022
023import java.time.Duration;
024import java.time.Instant;
025
026/**
027 * The Fedora Transaction abstraction
028 *
029 * @author mohideen
030 */
031public interface Transaction {
032
033    /**
034     * Commit the transaction
035     */
036    void commit();
037
038    /**
039     * Commit the transaction only if the transaction is shortLived
040     */
041    void commitIfShortLived();
042
043    /**
044     * @return returns true if this transaction has already been committed
045     */
046    boolean isCommitted();
047
048    /**
049     * Rollback the transaction
050     */
051    void rollback();
052
053    /**
054     * @return true if this transaction has been rolled back
055     */
056    boolean isRolledBack();
057
058    /**
059     * Get the transaction id
060     *
061     * @return the transaction id.
062     */
063    String getId();
064
065    /**
066     * Check if the transaction is short-lived.
067     *
068     * @return is the transaction short-lived.
069     */
070    boolean isShortLived();
071
072    /**
073     * Set transaction short-lived state.
074     *
075     * @param shortLived boolean true (short-lived) or false (not short-lived)
076     */
077    void setShortLived(boolean shortLived);
078
079    /**
080     * Expire a transaction
081     */
082    void expire();
083
084    /**
085     * Has the transaction expired?
086     * @return true if expired
087     */
088    boolean hasExpired();
089
090    /**
091    * Update the expiry by the provided amount
092    * @param amountToAdd the amount of time to add
093    * @return the new expiration date
094    */
095    Instant updateExpiry(Duration amountToAdd);
096
097    /**
098     * Get the date this session expires
099     * @return expiration date, if one exists
100     */
101    Instant getExpires();
102
103    /**
104     * Refresh the transaction to extend its expiration window.
105     */
106    void refresh();
107
108    /**
109     * Acquires a lock on the specified resource for this transaction.
110     *
111     * @param resourceId the resource to lock
112     * @throws ConcurrentUpdateException if the lock cannot be acquired
113     */
114    void lockResource(final FedoraId resourceId);
115
116    /**
117     * Releases any resource locks held by the transaction if the session is short-lived. This method should always be
118     * called after handling a request, regardless of the outcome, so that any held locks are released immediately
119     * without having to wait for the short-lived transaction to expire.
120     */
121    void releaseResourceLocksIfShortLived();
122
123    /**
124     * Sets the baseUri on the transaction
125     * @param baseUri the baseUri of the requests
126     */
127    void setBaseUri(String baseUri);
128
129    /**
130     * Sets the user-agent on the transaction
131     * @param userAgent the request's user-agent
132     */
133    void setUserAgent(String userAgent);
134
135}