001/*
002 * Copyright 2015-2022 Transmogrify LLC, 2022-2026 Revetware LLC.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.pyranid;
018
019import org.jspecify.annotations.NonNull;
020import org.jspecify.annotations.Nullable;
021
022import javax.annotation.concurrent.ThreadSafe;
023import javax.sql.DataSource;
024import java.sql.Connection;
025import java.sql.SQLException;
026import java.sql.SQLFeatureNotSupportedException;
027import java.sql.Savepoint;
028import java.time.Duration;
029import java.util.Collections;
030import java.util.Deque;
031import java.util.IdentityHashMap;
032import java.util.List;
033import java.util.Optional;
034import java.util.Set;
035import java.util.concurrent.CopyOnWriteArrayList;
036import java.util.concurrent.atomic.AtomicBoolean;
037import java.util.concurrent.atomic.AtomicLong;
038import java.util.concurrent.locks.ReentrantLock;
039import java.util.function.Consumer;
040import java.util.logging.Logger;
041
042import static java.lang.String.format;
043import static java.lang.System.nanoTime;
044import static java.util.Objects.requireNonNull;
045
046/**
047 * Represents a database transaction.
048 * <p>
049 * Note that commit and rollback operations are controlled internally by {@link Database}.
050 *
051 * @author <a href="https://www.revetkn.com">Mark Allen</a>
052 * @since 1.0.0
053 */
054@ThreadSafe
055public final class Transaction {
056        @NonNull
057        private static final AtomicLong ID_GENERATOR;
058        @NonNull
059        private static final Logger LOGGER;
060
061        static {
062                ID_GENERATOR = new AtomicLong(0);
063                LOGGER = Logger.getLogger(Transaction.class.getName());
064        }
065
066        @NonNull
067        private final Long id;
068        @NonNull
069        private final DataSource dataSource;
070        @NonNull
071        private final TransactionOptions transactionOptions;
072        @NonNull
073        private final TransactionIsolation transactionIsolation;
074        @NonNull
075        private final MetricsCollectorDispatcher metricsCollectorDispatcher;
076        @NonNull
077        private final DatabaseType databaseType;
078        @NonNull
079        private final List<@NonNull Consumer<TransactionResult>> postTransactionOperations;
080        @NonNull
081        private final ReentrantLock connectionLock;
082        private final TransactionRetrySafety retrySafety;
083        // Guarded by connectionLock. JDBC savepoints affect the whole connection, so a scoped savepoint must exclude
084        // JDBC work from other participants without holding the lock while application callbacks run.
085        @Nullable
086        private Thread savepointScopeOwner;
087        private int savepointScopeDepth;
088        @NonNull
089        private final AtomicBoolean rollbackOnly;
090        // Lifecycle coordination never holds this lock across JDBC or application callbacks.
091        private final ReentrantLock lifecycleLock;
092        private volatile CompletionPhase completionPhase;
093        @NonNull
094        private final AtomicBoolean commitSerializationFailure;
095        // Set at the actual JDBC dispatch and acknowledgment boundaries, independently of completion diagnostics.
096        private volatile boolean physicalCommitAttempted;
097        private volatile boolean physicalCommitSucceeded;
098        private volatile boolean physicalRollbackSucceeded;
099        // Guarded by connectionLock. These describe the existing physical connection, never ambient work.
100        @Nullable
101        private Throwable firstSuspectFailure;
102        @Nullable
103        private Throwable metadataProtectionFailure;
104        private boolean completionValidationRequired;
105        @NonNull
106        private volatile PhysicalTransactionBeginState physicalTransactionBeginState;
107        @Nullable
108        private volatile Throwable physicalTransactionBeginFailure;
109        private volatile boolean physicalRollbackPermitted;
110        @Nullable
111        private volatile Connection connection;
112        @Nullable
113        private volatile Boolean initialAutoCommit;
114        @Nullable
115        private volatile Boolean initialReadOnly;
116        @Nullable
117        private volatile Integer initialTransactionIsolationJdbcLevel;
118        @Nullable
119        private volatile Long connectionAcquiredAtNanos;
120        @NonNull
121        private final AtomicBoolean transactionIsolationWasChanged;
122        @NonNull
123        private final AtomicBoolean readOnlyWasChanged;
124
125        Transaction(@NonNull DataSource dataSource,
126                                                                @NonNull TransactionOptions transactionOptions,
127                                                                @NonNull MetricsCollectorDispatcher metricsCollectorDispatcher,
128                                                                @NonNull DatabaseType databaseType) {
129                requireNonNull(dataSource);
130                requireNonNull(transactionOptions);
131                requireNonNull(metricsCollectorDispatcher);
132                requireNonNull(databaseType);
133
134                this.id = generateId();
135                this.dataSource = dataSource;
136                this.transactionOptions = transactionOptions;
137                this.transactionIsolation = transactionOptions.getIsolation();
138                this.metricsCollectorDispatcher = metricsCollectorDispatcher;
139                this.databaseType = databaseType;
140                this.connection = null;
141                this.rollbackOnly = new AtomicBoolean(false);
142                this.lifecycleLock = new ReentrantLock();
143                this.completionPhase = CompletionPhase.ACTIVE;
144                this.commitSerializationFailure = new AtomicBoolean(false);
145                this.physicalTransactionBeginState = PhysicalTransactionBeginState.NOT_STARTED;
146                this.physicalTransactionBeginFailure = null;
147                this.physicalRollbackPermitted = false;
148                this.initialAutoCommit = null;
149                this.initialReadOnly = null;
150                this.connectionAcquiredAtNanos = null;
151                this.transactionIsolationWasChanged = new AtomicBoolean(false);
152                this.readOnlyWasChanged = new AtomicBoolean(false);
153                this.postTransactionOperations = new CopyOnWriteArrayList();
154                this.connectionLock = new ReentrantLock();
155                this.retrySafety = TransactionRetrySafety.currentOrNew();
156        }
157
158        @Override
159        @NonNull
160        public String toString() {
161                return format("%s{id=%s, transactionIsolation=%s, hasConnection=%s, isRollbackOnly=%s}",
162                                getClass().getSimpleName(), id(), getTransactionIsolation(), hasConnection(), isRollbackOnly());
163        }
164
165        /**
166         * Creates a transaction savepoint that can be rolled back to via {@link #rollback(Savepoint)}.
167         * <p>
168         * For most application code, prefer {@link #withSavepoint(TransactionalOperation)} or
169         * {@link #withSavepoint(ReturningTransactionalOperation)} so rollback and release cleanup are handled automatically.
170         *
171         * @return a transaction savepoint
172         * @throws IllegalStateException if this transaction has already completed or another thread owns an active savepoint scope
173         */
174        @NonNull
175        public Savepoint createSavepoint() {
176                lockConnectionInterruptibly("create a savepoint");
177                boolean acquired = false;
178
179                try {
180                        assertNotCompleted("create a savepoint");
181                        Connection connection = getConnection();
182                        acquired = true;
183                        Savepoint savepoint = connection.setSavepoint();
184                        getMetricsCollectorDispatcher().didCreateSavepoint(this, getDatabaseType());
185                        return savepoint;
186                } catch (SavepointScopeConflictException e) {
187                        throw e;
188                } catch (SQLException e) {
189                        DatabaseException wrapped = databaseException("Unable to create savepoint", e);
190                        if (acquired) recordSuspectFailure(wrapped);
191                        throw wrapped;
192                } catch (RuntimeException | Error e) {
193                        if (acquired) recordSuspectFailure(e);
194                        throw e;
195                } finally {
196                        getConnectionLock().unlock();
197                }
198        }
199
200        /**
201         * Rolls back to the provided transaction savepoint.
202         *
203         * @param savepoint the savepoint to roll back to
204         * @throws IllegalStateException if this transaction has already completed or another thread owns an active savepoint scope
205         */
206        public void rollback(@NonNull Savepoint savepoint) {
207                requireNonNull(savepoint);
208                boolean connectionLockAcquired = false;
209                boolean acquired = false;
210
211                try {
212                        lockConnectionInterruptibly("roll back to a savepoint");
213                        connectionLockAcquired = true;
214                        assertNotCompleted("roll back to a savepoint");
215                        Connection connection = getConnection();
216                        acquired = true;
217                        connection.rollback(savepoint);
218                        clearSuspectFailure();
219                        getMetricsCollectorDispatcher().didRollbackToSavepoint(this, getDatabaseType());
220                } catch (SavepointScopeConflictException e) {
221                        // No JDBC rollback was attempted. A caller may handle this ownership conflict and retry after the scope ends.
222                        throw e;
223                } catch (SQLException e) {
224                        markRollbackOnlyIfActive();
225                        DatabaseException wrapped = databaseException("Unable to roll back to savepoint", e);
226                        if (acquired) recordSuspectFailure(wrapped);
227                        throw wrapped;
228                } catch (RuntimeException | Error e) {
229                        markRollbackOnlyIfActive();
230                        if (acquired) recordSuspectFailure(e);
231                        throw e;
232                } finally {
233                        if (connectionLockAcquired)
234                                getConnectionLock().unlock();
235                }
236        }
237
238        /**
239         * Releases the provided transaction savepoint.
240         * <p>
241         * For most application code, prefer {@link #withSavepoint(TransactionalOperation)} or
242         * {@link #withSavepoint(ReturningTransactionalOperation)} so rollback and release cleanup are handled automatically.
243         *
244         * @param savepoint the savepoint to release
245         * @throws IllegalStateException if this transaction has already completed or another thread owns an active savepoint scope
246         * @since 4.1.0
247         */
248        public void releaseSavepoint(@NonNull Savepoint savepoint) {
249                requireNonNull(savepoint);
250                assertNotCompleted("release a savepoint");
251                releaseSavepointJdbc(savepoint);
252        }
253
254        /**
255         * Performs an operation inside a transaction savepoint.
256         * <p>
257         * If {@code transactionalOperation} completes successfully, the savepoint is released when the driver supports release.
258         * If an exception bubbles out, Pyranid rolls back to the savepoint, attempts to release it, and preserves cleanup failures
259         * as suppressed exceptions on the thrown exception.
260         * If rollback cleanup fails or release cleanup reports a terminal failure, the surrounding transaction is marked
261         * rollback-only even when the caller handles the body failure.
262         * <p>
263         * Nested savepoint usage should be stack-like: finish inner savepoints before manually releasing or rolling back outer
264         * savepoints.
265         * <p>
266         * While this scope is active, only the thread running its callback may use this transaction's JDBC connection.
267         * JDBC access from other participating threads is rejected instead of waiting for the callback to finish, so it cannot
268         * be silently rolled back with this scope. Nested scopes on the same thread are supported. Other participants may
269         * resume JDBC work after this method returns or throws.
270         *
271         * @param transactionalOperation the operation to perform inside a savepoint
272         * @throws IllegalStateException if this transaction has already completed or another thread owns an active savepoint scope
273         * @since 4.1.0
274         */
275        public void withSavepoint(@NonNull TransactionalOperation transactionalOperation) {
276                requireNonNull(transactionalOperation);
277
278                withSavepoint(() -> {
279                        transactionalOperation.perform();
280                        return Optional.empty();
281                });
282        }
283
284        /**
285         * Performs an operation inside a transaction savepoint and optionally returns a value.
286         * <p>
287         * If {@code transactionalOperation} completes successfully, the savepoint is released when the driver supports release.
288         * If an exception bubbles out, Pyranid rolls back to the savepoint, attempts to release it, and preserves cleanup failures
289         * as suppressed exceptions on the thrown exception.
290         * If rollback cleanup fails or release cleanup reports a terminal failure, the surrounding transaction is marked
291         * rollback-only even when the caller handles the body failure.
292         * <p>
293         * Nested savepoint usage should be stack-like: finish inner savepoints before manually releasing or rolling back outer
294         * savepoints.
295         * <p>
296         * While this scope is active, only the thread running its callback may use this transaction's JDBC connection.
297         * JDBC access from other participating threads is rejected instead of waiting for the callback to finish, so it cannot
298         * be silently rolled back with this scope. Nested scopes on the same thread are supported. Other participants may
299         * resume JDBC work after this method returns or throws.
300         *
301         * @param transactionalOperation the operation to perform inside a savepoint
302         * @param <T>                    the type to be returned
303         * @return the result of the operation
304         * @throws IllegalStateException if this transaction has already completed or another thread owns an active savepoint scope
305         * @since 4.1.0
306         */
307        @NonNull
308        public <T> Optional<T> withSavepoint(@NonNull ReturningTransactionalOperation<T> transactionalOperation) {
309                requireNonNull(transactionalOperation);
310                enterSavepointScope();
311
312                try {
313                        Savepoint savepoint = createSavepoint();
314
315                        try {
316                                Optional<T> returnValue = transactionalOperation.perform();
317
318                                if (returnValue == null)
319                                        returnValue = Optional.empty();
320
321                                releaseSavepointAfterSuccess(savepoint);
322                                return returnValue;
323                        } catch (RuntimeException e) {
324                                cleanupSavepointAfterFailure(savepoint, e);
325                                throw e;
326                        } catch (Error e) {
327                                cleanupSavepointAfterFailure(savepoint, e);
328                                throw e;
329                        } catch (Throwable t) {
330                                RuntimeException wrapped = new RuntimeException(t);
331                                cleanupSavepointAfterFailure(savepoint, wrapped);
332                                throw wrapped;
333                        }
334                } finally {
335                        exitSavepointScope();
336                }
337        }
338
339        /**
340         * Should this transaction be rolled back upon completion?
341         * <p>
342         * Default value is {@code false}.
343         *
344         * @return {@code true} if this transaction should be rolled back, {@code false} otherwise
345         */
346        @NonNull
347        public Boolean isRollbackOnly() {
348                return this.rollbackOnly.get();
349        }
350
351        /**
352         * Sets whether this transaction should be rolled back upon completion.
353         *
354         * @param rollbackOnly whether to set this transaction to be rollback-only
355         */
356        public void setRollbackOnly(@NonNull Boolean rollbackOnly) {
357                requireNonNull(rollbackOnly);
358                this.lifecycleLock.lock();
359                try {
360                        assertNotCompleted("set rollback-only state");
361                        this.rollbackOnly.set(rollbackOnly);
362                } finally {
363                        this.lifecycleLock.unlock();
364                }
365        }
366
367        /**
368         * Adds an operation to the list of operations to be executed when the transaction completes.
369         * <p>
370         * The supplied operation receives {@link TransactionResult#COMMITTED} if commit completed successfully,
371         * {@link TransactionResult#ROLLED_BACK} if Pyranid can prove that no application transaction work committed (including when
372         * a failed physical-transaction begin is discarded before application transaction work could execute), or
373         * {@link TransactionResult#IN_DOUBT} if Pyranid cannot prove the final database outcome after application transaction work
374         * could have executed. A {@code ROLLED_BACK} result therefore does not necessarily mean that Pyranid invoked the JDBC
375         * {@code rollback()} method.
376         * <p>
377         * If the operation throws, Pyranid wraps the thrown value in a {@link PostTransactionOperationException}. If another
378         * transaction or cleanup failure is already primary, the wrapper is suppressed onto that primary failure; otherwise,
379         * {@link Database#transaction(TransactionalOperation)} throws the wrapper as the primary failure.
380         *
381         * @param postTransactionOperation the post-transaction operation to add
382         */
383        public void addPostTransactionOperation(@NonNull Consumer<TransactionResult> postTransactionOperation) {
384                requireNonNull(postTransactionOperation);
385                this.lifecycleLock.lock();
386                try {
387                        assertNotCompleted("add a post-transaction operation");
388                        this.postTransactionOperations.add(postTransactionOperation);
389                } finally {
390                        this.lifecycleLock.unlock();
391                }
392        }
393
394        /**
395         * Removes an operation from the list of operations to be executed when the transaction completes.
396         * <p>
397         * Equality is evaluated against a snapshot of the registered operations. New operation instances added while
398         * equality is evaluated are left for a later removal call.
399         *
400         * @param postTransactionOperation the post-transaction operation to remove
401         * @return {@code true} if the post-transaction operation was removed, {@code false} otherwise
402         */
403        @NonNull
404        public Boolean removePostTransactionOperation(@NonNull Consumer<TransactionResult> postTransactionOperation) {
405                requireNonNull(postTransactionOperation);
406                assertNotCompleted("remove a post-transaction operation");
407                Object[] snapshot = this.postTransactionOperations.toArray();
408                // Consumer.equals() is application code. Match one stable snapshot outside the lifecycle lock; chasing
409                // newly added operations could run forever when equals() itself registers an unrelated operation.
410                for (Object candidate : snapshot) {
411                        if (!postTransactionOperation.equals(candidate)) continue;
412                        this.lifecycleLock.lock();
413                        try {
414                                assertNotCompleted("remove a post-transaction operation");
415                                // Another removal may have shifted or removed this occurrence. Identity lookup avoids calling
416                                // equals() again while locked, and preserves the order of equal or duplicate registrations.
417                                for (int index = 0; index < this.postTransactionOperations.size(); ++index) {
418                                        if (this.postTransactionOperations.get(index) == candidate) {
419                                                this.postTransactionOperations.remove(index);
420                                                return true;
421                                        }
422                                }
423                        } finally {
424                                this.lifecycleLock.unlock();
425                        }
426                }
427                this.lifecycleLock.lock();
428                try {
429                        assertNotCompleted("remove a post-transaction operation");
430                        return false;
431                } finally {
432                        this.lifecycleLock.unlock();
433                }
434        }
435
436        /**
437         * Gets an unmodifiable list of post-transaction operations.
438         * <p>
439         * To manipulate the list, use {@link #addPostTransactionOperation(Consumer)} and
440         * {@link #removePostTransactionOperation(Consumer)}.
441         *
442         * @return the list of post-transaction operations
443         */
444        @NonNull
445        public List<@NonNull Consumer<TransactionResult>> getPostTransactionOperations() {
446                return Collections.unmodifiableList(this.postTransactionOperations);
447        }
448
449        /**
450         * Get the isolation level for this transaction.
451         *
452         * @return the isolation level
453         */
454        @NonNull
455        public TransactionIsolation getTransactionIsolation() {
456                return this.transactionIsolation;
457        }
458
459        /**
460         * Gets the options used to create this transaction.
461         *
462         * @return transaction options
463         * @since 4.2.0
464         */
465        @NonNull
466        public TransactionOptions getTransactionOptions() {
467                return this.transactionOptions;
468        }
469
470        @NonNull
471        Long id() {
472                return this.id;
473        }
474
475        @NonNull
476        Boolean hasConnection() {
477                getConnectionLock().lock();
478
479                try {
480                        return this.connection != null;
481                } finally {
482                        getConnectionLock().unlock();
483                }
484        }
485
486        @NonNull
487        Boolean isOwnedBy(@NonNull DataSource dataSource) {
488                requireNonNull(dataSource);
489                return this.dataSource == dataSource;
490        }
491
492        void commit() {
493                getConnectionLock().lock();
494
495                try {
496                        throwPhysicalTransactionBeginFailureIfPresent();
497
498                        if (!hasConnection()) {
499                                LOGGER.finer("Transaction has no connection, so nothing to commit");
500                                return;
501                        }
502
503                        // The public connection accessor rejects COMPLETING. Internal completion owns the existing handle, so it applies
504                        // the savepoint-scope guard itself. Guards, validation and pre-dispatch diagnostics cannot make the commit
505                        // outcome uncertain because none has issued the physical commit yet.
506                        assertSavepointScopeAccess();
507                        throwMetadataProtectionFailureIfPresent();
508                        TransactionCompletionValidation.validate(requireNonNull(this.connection), this.databaseType,
509                                        this.firstSuspectFailure, this.completionValidationRequired);
510
511                        LOGGER.finer("Committing transaction...");
512
513                        long startTime = nanoTime();
514
515                        try {
516                                this.physicalCommitAttempted = true;
517                                requireNonNull(this.connection).commit();
518                                this.physicalCommitSucceeded = true;
519                        } catch (SQLException e) {
520                                // Classify only the driver's original failure, before wrapping, metrics, rollback or cleanup alter it.
521                                this.commitSerializationFailure.set(TransactionCommitEvidence.provesSerializationAbort(e, this.databaseType.dialect()));
522                                DatabaseException wrapped = databaseException("Unable to commit transaction", e);
523                                getMetricsCollectorDispatcher().didFailToCommitPhysicalTransaction(this, getDatabaseType(), Duration.ofNanos(nanoTime() - startTime), wrapped);
524                                throw wrapped;
525                        } catch (RuntimeException | Error e) {
526                                getMetricsCollectorDispatcher().didFailToCommitPhysicalTransaction(this, getDatabaseType(), Duration.ofNanos(nanoTime() - startTime), e);
527                                throw e;
528                        }
529                        // Physical success is already durable evidence even if success instrumentation throws.
530                        getMetricsCollectorDispatcher().didCommitPhysicalTransaction(this, getDatabaseType(), Duration.ofNanos(nanoTime() - startTime));
531                        LOGGER.finer("Transaction committed.");
532                } finally {
533                        getConnectionLock().unlock();
534                }
535        }
536
537        boolean didCommitFailWithSerializationFailure() {
538                return this.commitSerializationFailure.get();
539        }
540
541        boolean didPhysicalCommitSucceed() {
542                return this.physicalCommitSucceeded;
543        }
544
545        boolean didAttemptPhysicalCommit() {
546                return this.physicalCommitAttempted;
547        }
548
549        boolean didPhysicalRollbackSucceed() {
550                return this.physicalRollbackSucceeded;
551        }
552
553        void recordSuspectFailure(@NonNull Throwable failure) {
554                requireNonNull(failure);
555                assertConnectionLockHeld();
556                if (this.connection != null && this.physicalTransactionBeginState == PhysicalTransactionBeginState.READY
557                                && this.completionPhase != CompletionPhase.COMPLETED && this.firstSuspectFailure == null)
558                        this.firstSuspectFailure = failure;
559        }
560
561        void requireCompletionValidation() {
562                assertConnectionLockHeld();
563                if (this.connection != null && this.physicalTransactionBeginState == PhysicalTransactionBeginState.READY
564                                && this.completionPhase != CompletionPhase.COMPLETED)
565                        this.completionValidationRequired = true;
566        }
567
568        /** Uncertain internal control failures must not look like an intentional rollback-only completion. */
569        void throwMetadataProtectionFailureIfPresent() {
570                assertConnectionLockHeld();
571                Throwable failure = this.metadataProtectionFailure;
572                if (failure instanceof Error error) throw error;
573                if (failure != null)
574                        throw TransactionCompletionValidation.metadataProtectionRefusal(failure, this.databaseType);
575        }
576
577        private void clearSuspectFailure() {
578                assertConnectionLockHeld();
579                this.firstSuspectFailure = null;
580        }
581
582        private void assertConnectionLockHeld() {
583                if (!this.connectionLock.isHeldByCurrentThread())
584                        throw new IllegalStateException("Transaction connection lock must be held while recording completion evidence");
585        }
586
587        void rollback() {
588                getConnectionLock().lock();
589
590                try {
591                        // Deliberately no savepoint-scope guard, unlike commit(): completion must always be able to discard work. A
592                        // rollback cannot publish another participant's partial work, and that participant's next JDBC call is rejected
593                        // once completion has marked this transaction completed.
594
595                        if (!hasConnection()) {
596                                LOGGER.finer("Transaction has no connection, so nothing to roll back");
597                                return;
598                        }
599
600                        if (!isPhysicalRollbackPermitted()) {
601                                LOGGER.finer("Physical transaction did not reach a state where rollback is permitted");
602                                return;
603                        }
604
605                        LOGGER.finer("Rolling back transaction...");
606
607                        long startTime = nanoTime();
608
609                        try {
610                                requireNonNull(this.connection).rollback();
611                                this.physicalRollbackSucceeded = true;
612                        } catch (SQLException e) {
613                                DatabaseException wrapped = databaseException("Unable to roll back transaction", e);
614                                getMetricsCollectorDispatcher().didFailToRollbackPhysicalTransaction(this, getDatabaseType(), Duration.ofNanos(nanoTime() - startTime), wrapped);
615                                throw wrapped;
616                        } catch (RuntimeException | Error e) {
617                                getMetricsCollectorDispatcher().didFailToRollbackPhysicalTransaction(this, getDatabaseType(), Duration.ofNanos(nanoTime() - startTime), e);
618                                throw e;
619                        }
620                        getMetricsCollectorDispatcher().didRollbackPhysicalTransaction(this, getDatabaseType(), Duration.ofNanos(nanoTime() - startTime));
621                        LOGGER.finer("Transaction rolled back.");
622                } finally {
623                        getConnectionLock().unlock();
624                }
625        }
626
627        /**
628         * The connection associated with this transaction.
629         * <p>
630         * If no connection is associated yet, we ask the {@link DataSource} for one.
631         *
632         * @return The connection associated with this transaction.
633         * @throws DatabaseException if unable to acquire a connection.
634         */
635        @NonNull
636        Connection getConnection() {
637                lockConnectionInterruptibly("get the transaction connection");
638
639                try {
640                        assertNotCompleted("get the transaction connection");
641                        assertSavepointScopeAccess();
642
643                        if (this.physicalTransactionBeginState == PhysicalTransactionBeginState.READY)
644                                return requireNonNull(this.connection);
645
646                        throwPhysicalTransactionBeginFailureIfPresent();
647
648                        if (this.physicalTransactionBeginState == PhysicalTransactionBeginState.STARTING)
649                                throw new IllegalStateException("Physical transaction begin is already in progress");
650
651                        this.physicalTransactionBeginState = PhysicalTransactionBeginState.STARTING;
652
653                        try {
654                                return beginPhysicalTransaction();
655                        } catch (RuntimeException failure) {
656                                RuntimeException normalizedFailure = failure instanceof DatabaseException
657                                                ? failure
658                                                : databaseException("Unable to begin physical transaction", failure);
659                                this.physicalTransactionBeginFailure = normalizedFailure;
660                                this.physicalTransactionBeginState = PhysicalTransactionBeginState.FAILED;
661                                throw normalizedFailure;
662                        } catch (Error failure) {
663                                this.physicalTransactionBeginFailure = failure;
664                                this.physicalTransactionBeginState = PhysicalTransactionBeginState.FAILED;
665                                throw failure;
666                        }
667                } finally {
668                        getConnectionLock().unlock();
669                }
670        }
671
672        @NonNull
673        private Connection beginPhysicalTransaction() {
674                long startTime = nanoTime();
675                getMetricsCollectorDispatcher().willAcquireTransactionConnection(this, getDatabaseType());
676                MetricsCollector.PhysicalTransactionBeginFailurePhase phase = MetricsCollector.PhysicalTransactionBeginFailurePhase.ACQUIRE_CONNECTION;
677                try {
678
679                        try {
680                                Connection candidate = getDataSource().getConnection();
681                                TransactionCoordinator.assertIndependentConnection(this, candidate);
682                                this.connection = candidate;
683                        } catch (SQLException e) {
684                                DatabaseException wrapped = databaseException("Unable to acquire database connection", e);
685                                throw wrapped;
686                        }
687
688                        this.connectionAcquiredAtNanos = nanoTime();
689                        getMetricsCollectorDispatcher().didAcquireTransactionConnection(this, getDatabaseType(), Duration.ofNanos(this.connectionAcquiredAtNanos - startTime));
690
691                        // Keep track of the initial setting for autocommit since it might need to get changed from "true" to "false" for
692                        // the duration of the transaction and then back to "true" post-transaction.
693                        phase = MetricsCollector.PhysicalTransactionBeginFailurePhase.READ_INITIAL_AUTOCOMMIT;
694                        try {
695                                this.initialAutoCommit = this.connection.getAutoCommit();
696                                this.physicalRollbackPermitted = !this.initialAutoCommit;
697                        } catch (SQLException e) {
698                                DatabaseException wrapped = databaseException("Unable to determine database connection autocommit setting", e);
699                                throw wrapped;
700                        }
701
702                        // Track initial isolation
703                        phase = MetricsCollector.PhysicalTransactionBeginFailurePhase.READ_INITIAL_ISOLATION;
704                        try {
705                                this.initialTransactionIsolationJdbcLevel = this.connection.getTransactionIsolation();
706                        } catch (SQLException e) {
707                                DatabaseException wrapped = databaseException("Unable to determine database connection transaction isolation", e);
708                                throw wrapped;
709                        }
710
711                        phase = MetricsCollector.PhysicalTransactionBeginFailurePhase.READ_INITIAL_READ_ONLY;
712                        try {
713                                this.initialReadOnly = this.connection.isReadOnly();
714                        } catch (SQLException e) {
715                                DatabaseException wrapped = databaseException("Unable to determine database connection read-only setting", e);
716                                throw wrapped;
717                        }
718
719                        Boolean desiredReadOnly = getTransactionOptions().getReadOnly().orElse(null);
720
721                        if (desiredReadOnly != null && !desiredReadOnly.equals(this.initialReadOnly)) {
722                                phase = MetricsCollector.PhysicalTransactionBeginFailurePhase.SET_READ_ONLY;
723                                try {
724                                        this.connection.setReadOnly(desiredReadOnly);
725                                        this.readOnlyWasChanged.set(true);
726                                } catch (SQLException e) {
727                                        DatabaseException wrapped = databaseException(format("Unable to set database connection read-only value to '%s'", desiredReadOnly), e);
728                                        throw wrapped;
729                                }
730                        }
731
732                        // Immediately flip autocommit to false if needed...if initially true, it will get set back to true by Database at
733                        // the end of the transaction
734                        if (this.initialAutoCommit) {
735                                phase = MetricsCollector.PhysicalTransactionBeginFailurePhase.SET_AUTOCOMMIT_FALSE;
736                                setAutoCommit(false);
737                                this.physicalRollbackPermitted = true;
738                        }
739
740                        // Apply requested isolation if not DEFAULT and different from current
741                        TransactionIsolation desiredTransactionIsolation = getTransactionIsolation();
742
743                        if (desiredTransactionIsolation != TransactionIsolation.DEFAULT) {
744                                // Safe; only DEFAULT has a null value
745                                int desiredJdbcLevel = desiredTransactionIsolation.getJdbcLevel().get();
746                                // Apply only if different from current (or current unknown)
747                                if (this.initialTransactionIsolationJdbcLevel == null || this.initialTransactionIsolationJdbcLevel.intValue() != desiredJdbcLevel) {
748                                        phase = MetricsCollector.PhysicalTransactionBeginFailurePhase.SET_ISOLATION;
749                                        try {
750                                                // In the future, we might check supportsTransactionIsolationLevel via DatabaseMetaData first.
751                                                // Probably want to calculate that at Database init time and cache it off
752                                                this.connection.setTransactionIsolation(desiredJdbcLevel);
753                                                this.transactionIsolationWasChanged.set(true);
754                                        } catch (SQLException e) {
755                                                DatabaseException wrapped = databaseException(format("Unable to set transaction isolation to %s", desiredTransactionIsolation.name()), e);
756                                                throw wrapped;
757                                        }
758                                }
759                        }
760
761                        this.physicalTransactionBeginState = PhysicalTransactionBeginState.READY;
762                        getMetricsCollectorDispatcher().didBeginPhysicalTransaction(this, getTransactionIsolation(), getDatabaseType());
763                        return requireNonNull(this.connection);
764                } catch (RuntimeException | Error failure) {
765                        if (phase == MetricsCollector.PhysicalTransactionBeginFailurePhase.ACQUIRE_CONNECTION)
766                                getMetricsCollectorDispatcher().didFailToAcquireTransactionConnection(this, getDatabaseType(),
767                                                Duration.ofNanos(nanoTime() - startTime), failure);
768                        getMetricsCollectorDispatcher().didFailToBeginPhysicalTransaction(this, getTransactionIsolation(),
769                                        phase, getDatabaseType(), failure);
770                        throw failure;
771                }
772        }
773
774        boolean didPhysicalTransactionBeginFail() {
775                return this.physicalTransactionBeginState == PhysicalTransactionBeginState.FAILED;
776        }
777
778        boolean couldApplicationWorkHaveExecuted() {
779                return didPhysicalTransactionBeginSuccessfully();
780        }
781
782        boolean didPhysicalTransactionBeginSuccessfully() {
783                return this.physicalTransactionBeginState == PhysicalTransactionBeginState.READY;
784        }
785
786        boolean isPhysicalRollbackPermitted() {
787                return this.physicalRollbackPermitted;
788        }
789
790        void throwPhysicalTransactionBeginFailureIfPresent() {
791                if (!didPhysicalTransactionBeginFail())
792                        return;
793
794                Throwable failure = requireNonNull(this.physicalTransactionBeginFailure);
795
796                if (failure instanceof RuntimeException runtimeException)
797                        throw runtimeException;
798
799                if (failure instanceof Error error)
800                        throw error;
801
802                throw new AssertionError("Unexpected checked physical transaction begin failure", failure);
803        }
804
805        void setAutoCommit(@NonNull Boolean autoCommit) {
806                requireNonNull(autoCommit);
807
808                getConnectionLock().lock();
809
810                try {
811                        Connection connection = this.connection;
812
813                        if (connection == null)
814                                throw databaseException("Transaction has no connection", null);
815
816                        try {
817                                connection.setAutoCommit(autoCommit);
818                        } catch (SQLException e) {
819                                throw databaseException(format("Unable to set database connection autocommit value to '%s'", autoCommit), e);
820                        }
821                } finally {
822                        getConnectionLock().unlock();
823                }
824        }
825
826        void restoreTransactionIsolationIfNeeded() {
827                getConnectionLock().lock();
828
829                try {
830                        if (this.connection == null)
831                                return;
832
833                        Integer initialTransactionIsolationJdbcLevel = getInitialTransactionIsolationJdbcLevel().orElse(null);
834
835                        if (getTransactionIsolationWasChanged() && initialTransactionIsolationJdbcLevel != null) {
836                                try {
837                                        this.connection.setTransactionIsolation(initialTransactionIsolationJdbcLevel.intValue());
838                                } catch (SQLException e) {
839                                        throw databaseException("Unable to restore original transaction isolation", e);
840                                } finally {
841                                        this.transactionIsolationWasChanged.set(false);
842                                }
843                        }
844                } finally {
845                        getConnectionLock().unlock();
846                }
847        }
848
849        void restoreReadOnlyIfNeeded() {
850                getConnectionLock().lock();
851
852                try {
853                        if (this.connection == null)
854                                return;
855
856                        Boolean initialReadOnly = getInitialReadOnly().orElse(null);
857
858                        if (getReadOnlyWasChanged() && initialReadOnly != null) {
859                                try {
860                                        this.connection.setReadOnly(initialReadOnly);
861                                } catch (SQLException e) {
862                                        throw databaseException("Unable to restore original read-only setting", e);
863                                } finally {
864                                        this.readOnlyWasChanged.set(false);
865                                }
866                        }
867                } finally {
868                        getConnectionLock().unlock();
869                }
870        }
871
872        @NonNull
873        Long generateId() {
874                return ID_GENERATOR.incrementAndGet();
875        }
876
877        @NonNull
878        Optional<Boolean> getInitialAutoCommit() {
879                return Optional.ofNullable(this.initialAutoCommit);
880        }
881
882        @NonNull
883        Optional<Boolean> getInitialReadOnly() {
884                return Optional.ofNullable(this.initialReadOnly);
885        }
886
887        @NonNull
888        DataSource getDataSource() {
889                return this.dataSource;
890        }
891
892        @NonNull
893        private Optional<Integer> getInitialTransactionIsolationJdbcLevel() {
894                return Optional.ofNullable(this.initialTransactionIsolationJdbcLevel);
895        }
896
897        @NonNull
898        private Boolean getTransactionIsolationWasChanged() {
899                return this.transactionIsolationWasChanged.get();
900        }
901
902        @NonNull
903        private Boolean getReadOnlyWasChanged() {
904                return this.readOnlyWasChanged.get();
905        }
906
907        TransactionRetrySafety retrySafety() {
908                return this.retrySafety;
909        }
910
911        @NonNull
912        ReentrantLock getConnectionLock() {
913                return this.connectionLock;
914        }
915
916        @NonNull
917        Optional<Connection> getExistingConnection() {
918                getConnectionLock().lock();
919
920                try {
921                        return Optional.ofNullable(this.connection);
922                } finally {
923                        getConnectionLock().unlock();
924                }
925        }
926
927        /** A volatile identity snapshot avoids acquiring an enclosing transaction's JDBC lock during begin. */
928        boolean hasExistingConnectionIdentity(Connection candidate) {
929                return candidate != null && this.connection == candidate;
930        }
931
932        void clearConnection() {
933                getConnectionLock().lock();
934
935                try {
936                        this.connection = null;
937                } finally {
938                        getConnectionLock().unlock();
939                }
940        }
941
942        void beginCompletion() {
943                this.lifecycleLock.lock();
944                try {
945                        if (this.completionPhase == CompletionPhase.ACTIVE)
946                                this.completionPhase = CompletionPhase.COMPLETING;
947                } finally {
948                        this.lifecycleLock.unlock();
949                }
950        }
951
952        void markCompleted() {
953                this.connectionLock.lock();
954                try {
955                        this.lifecycleLock.lock();
956                        try {
957                                this.completionPhase = CompletionPhase.COMPLETED;
958                                this.firstSuspectFailure = null;
959                                this.metadataProtectionFailure = null;
960                                this.completionValidationRequired = false;
961                        } finally {
962                                this.lifecycleLock.unlock();
963                        }
964                } finally {
965                        this.connectionLock.unlock();
966                }
967        }
968
969        void assertCanParticipate() {
970                this.lifecycleLock.lock();
971                try {
972                        assertNotCompleted("participate");
973                } finally {
974                        this.lifecycleLock.unlock();
975                }
976        }
977
978        @NonNull
979        Boolean isCompleted() {
980                return this.completionPhase == CompletionPhase.COMPLETED;
981        }
982
983        private void markRollbackOnlyIfActive() {
984                this.lifecycleLock.lock();
985                try {
986                        if (this.completionPhase == CompletionPhase.ACTIVE)
987                                this.rollbackOnly.set(true);
988                } finally {
989                        this.lifecycleLock.unlock();
990                }
991        }
992
993        /** An uncertain internal control operation fences only its physical owner, with a visible failure. */
994        static void recordMetadataProtectionFailure(Connection failedConnection, Throwable failure) {
995                recordMetadataProtectionFailure(failedConnection, failure, true);
996        }
997
998        /** A provably rejected control operation retains ordinary, recoverable statement-failure evidence. */
999        static void recordMetadataProtectionRejection(Connection failedConnection, Throwable failure) {
1000                recordMetadataProtectionFailure(failedConnection, failure, false);
1001        }
1002
1003        private static void recordMetadataProtectionFailure(Connection failedConnection, Throwable failure, boolean uncertain) {
1004                requireNonNull(failedConnection);
1005                requireNonNull(failure);
1006                Deque<Transaction> stack = TransactionCoordinator.TRANSACTION_STACK_HOLDER.get();
1007                if (stack == null) return;
1008                Set<Transaction> visited = Collections.newSetFromMap(new IdentityHashMap<>());
1009                for (Transaction transaction : stack) {
1010                        if (visited.add(transaction) && transaction.connection == failedConnection
1011                                        && transaction.connectionLock.isHeldByCurrentThread()) {
1012                                transaction.recordSuspectFailure(failure);
1013                                transaction.requireCompletionValidation();
1014                                if (uncertain && transaction.physicalTransactionBeginState == PhysicalTransactionBeginState.READY
1015                                                && transaction.completionPhase != CompletionPhase.COMPLETED && transaction.metadataProtectionFailure == null)
1016                                        transaction.metadataProtectionFailure = failure;
1017                        }
1018                }
1019        }
1020
1021
1022        /** An admitted savepoint cleanup can fail while completion waits for its connection lease. */
1023        private void markRollbackOnlyForCleanupFailure() {
1024                this.lifecycleLock.lock();
1025                try {
1026                        if (this.completionPhase != CompletionPhase.COMPLETED)
1027                                this.rollbackOnly.set(true);
1028                } finally {
1029                        this.lifecycleLock.unlock();
1030                }
1031        }
1032
1033        private void enterSavepointScope() {
1034                lockConnectionInterruptibly("run a savepoint operation");
1035
1036                try {
1037                        assertNotCompleted("run a savepoint operation");
1038                        assertSavepointScopeAccess();
1039                        this.savepointScopeOwner = Thread.currentThread();
1040                        ++this.savepointScopeDepth;
1041                } finally {
1042                        getConnectionLock().unlock();
1043                }
1044        }
1045
1046        private void exitSavepointScope() {
1047                // Cleanup must release ownership even when the callback left the current thread interrupted.
1048                getConnectionLock().lock();
1049
1050                try {
1051                        if (--this.savepointScopeDepth == 0)
1052                                this.savepointScopeOwner = null;
1053                } finally {
1054                        getConnectionLock().unlock();
1055                }
1056        }
1057
1058        private void assertSavepointScopeAccess() {
1059                if (this.savepointScopeOwner != null && this.savepointScopeOwner != Thread.currentThread())
1060                        throw new SavepointScopeConflictException(format(
1061                                        "Transaction %s has an active savepoint scope on another thread; JDBC work must wait until that scope finishes", id()));
1062        }
1063
1064        private void releaseSavepointAfterSuccess(@NonNull Savepoint savepoint) {
1065                requireNonNull(savepoint);
1066                lockConnectionInterruptibly("release a savepoint");
1067                boolean acquired = false;
1068
1069                try {
1070                        Connection connection = getConnection();
1071                        acquired = true;
1072                        connection.releaseSavepoint(savepoint);
1073                        getMetricsCollectorDispatcher().didReleaseSavepoint(this, getDatabaseType());
1074                } catch (SQLFeatureNotSupportedException e) {
1075                        if (JdbcFallbacks.isTerminal(e)) {
1076                                DatabaseException wrapped = databaseException("Unable to release savepoint", e);
1077                                if (acquired) recordSuspectFailure(wrapped);
1078                                throw wrapped;
1079                        }
1080                        // Some drivers support rollback-to-savepoint but not release; successful closures should still succeed.
1081                } catch (SQLException e) {
1082                        DatabaseException wrapped = databaseException("Unable to release savepoint", e);
1083                        if (acquired) recordSuspectFailure(wrapped);
1084                        throw wrapped;
1085                } catch (RuntimeException | Error failure) {
1086                        if (acquired) recordSuspectFailure(failure);
1087                        throw failure;
1088                } finally {
1089                        getConnectionLock().unlock();
1090                }
1091        }
1092
1093        private void cleanupSavepointAfterFailure(@NonNull Savepoint savepoint,
1094                                                                                                                                                                                @NonNull Throwable primary) {
1095                requireNonNull(savepoint);
1096                requireNonNull(primary);
1097
1098                boolean rollbackConnectionLockAcquired = false;
1099                boolean rollbackConnectionAcquired = false;
1100
1101                try {
1102                        lockConnectionInterruptibly("roll back to a savepoint");
1103                        rollbackConnectionLockAcquired = true;
1104                        Connection connection = getConnection();
1105                        rollbackConnectionAcquired = true;
1106                        connection.rollback(savepoint);
1107                        clearSuspectFailure();
1108                        getMetricsCollectorDispatcher().didRollbackToSavepoint(this, getDatabaseType());
1109                } catch (Throwable rollbackException) {
1110                        markRollbackOnlyForCleanupFailure();
1111                        DatabaseException wrapped = databaseException("Unable to roll back to savepoint", rollbackException);
1112                        if (rollbackConnectionAcquired) recordSuspectFailure(wrapped);
1113                        if (primary != rollbackException)
1114                                Database.appendCleanupFailure(primary, wrapped);
1115                } finally {
1116                        if (rollbackConnectionLockAcquired)
1117                                getConnectionLock().unlock();
1118                }
1119
1120                boolean releaseConnectionLockAcquired = false;
1121                boolean releaseConnectionAcquired = false;
1122
1123                try {
1124                        lockConnectionInterruptibly("release a savepoint");
1125                        releaseConnectionLockAcquired = true;
1126                        Connection connection = getConnection();
1127                        releaseConnectionAcquired = true;
1128                        connection.releaseSavepoint(savepoint);
1129                        getMetricsCollectorDispatcher().didReleaseSavepoint(this, getDatabaseType());
1130                } catch (SQLFeatureNotSupportedException e) {
1131                        if (JdbcFallbacks.isTerminal(e)) {
1132                                // A caller may handle the body failure. Terminal release evidence must still prevent
1133                                // committing later work after a rollback or loss of the surrounding transaction.
1134                                markRollbackOnlyForCleanupFailure();
1135                                DatabaseException wrapped = databaseException("Unable to release savepoint", e);
1136                                if (releaseConnectionAcquired) recordSuspectFailure(wrapped);
1137                                if (primary != e)
1138                                        Database.appendCleanupFailure(primary, wrapped);
1139                        }
1140                        // Some drivers support rollback-to-savepoint but not release.
1141                } catch (Throwable releaseException) {
1142                        if (JdbcFallbacks.isTerminal(releaseException))
1143                                markRollbackOnlyForCleanupFailure();
1144                        DatabaseException wrapped = databaseException("Unable to release savepoint", releaseException);
1145                        if (releaseConnectionAcquired) recordSuspectFailure(wrapped);
1146                        if (primary != releaseException)
1147                                Database.appendCleanupFailure(primary, wrapped);
1148                } finally {
1149                        if (releaseConnectionLockAcquired)
1150                                getConnectionLock().unlock();
1151                }
1152        }
1153
1154        private void releaseSavepointJdbc(@NonNull Savepoint savepoint) {
1155                requireNonNull(savepoint);
1156                lockConnectionInterruptibly("release a savepoint");
1157                boolean acquired = false;
1158
1159                try {
1160                        Connection connection = getConnection();
1161                        acquired = true;
1162                        connection.releaseSavepoint(savepoint);
1163                        getMetricsCollectorDispatcher().didReleaseSavepoint(this, getDatabaseType());
1164                } catch (SQLException e) {
1165                        DatabaseException wrapped = databaseException("Unable to release savepoint", e);
1166                        if (acquired) recordSuspectFailure(wrapped);
1167                        throw wrapped;
1168                } catch (RuntimeException | Error failure) {
1169                        if (acquired) recordSuspectFailure(failure);
1170                        throw failure;
1171                } finally {
1172                        getConnectionLock().unlock();
1173                }
1174        }
1175
1176        private void lockConnectionInterruptibly(@NonNull String operation) {
1177                requireNonNull(operation);
1178                assertNotCompleted(operation);
1179                ReentrantLock connectionLock = getConnectionLock();
1180
1181                // Interruptibility is for a participant waiting on another thread. Reentrant acquisition never waits, and using
1182                // lockInterruptibly() here would instead make a pending interrupt abort commit/rollback before JDBC cleanup runs.
1183                if (connectionLock.isHeldByCurrentThread()) {
1184                        connectionLock.lock();
1185                        return;
1186                }
1187
1188                try {
1189                        connectionLock.lockInterruptibly();
1190                } catch (InterruptedException e) {
1191                        Thread.currentThread().interrupt();
1192                        throw databaseException(format("Interrupted while waiting to %s", operation), e);
1193                }
1194        }
1195
1196        @NonNull
1197        private DatabaseException databaseException(@NonNull String message,
1198                                                                                                                                                @Nullable Throwable cause) {
1199                requireNonNull(message);
1200
1201                DatabaseDialect databaseDialect = getDatabaseType().dialect();
1202                // Driver metadata is diagnostic: a broken accessor must not replace interruption or stop cleanup.
1203                return cause == null ? new DatabaseException(message, null, databaseDialect)
1204                                : DatabaseException.wrapSafely(message, cause, databaseDialect);
1205        }
1206
1207        @NonNull
1208        MetricsCollectorDispatcher getMetricsCollectorDispatcher() {
1209                return this.metricsCollectorDispatcher;
1210        }
1211
1212        @NonNull
1213        DatabaseType getDatabaseType() {
1214                return this.databaseType;
1215        }
1216
1217        @NonNull
1218        Optional<Long> getConnectionAcquiredAtNanos() {
1219                return Optional.ofNullable(this.connectionAcquiredAtNanos);
1220        }
1221
1222        private void assertNotCompleted(@NonNull String operation) {
1223                requireNonNull(operation);
1224
1225                if (this.completionPhase != CompletionPhase.ACTIVE)
1226                        throw new IllegalStateException(format("Transaction %s has already completed its closure and cannot %s", id(), operation));
1227        }
1228
1229        private enum CompletionPhase {
1230                ACTIVE,
1231                COMPLETING,
1232                COMPLETED
1233        }
1234
1235        private enum PhysicalTransactionBeginState {
1236                NOT_STARTED,
1237                STARTING,
1238                READY,
1239                FAILED
1240        }
1241
1242        private static final class SavepointScopeConflictException extends IllegalStateException {
1243                private SavepointScopeConflictException(@NonNull String message) {
1244                        super(message);
1245                }
1246        }
1247}