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}