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}