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; 020 021import javax.annotation.concurrent.ThreadSafe; 022import java.util.Optional; 023 024import static java.util.Objects.requireNonNull; 025 026/** 027 * The completed database outcome, attempted callback value and invocation failure of one transaction boundary. 028 * <p> 029 * A callback value does not establish commit, and a failure does not establish rollback: cleanup or a 030 * post-transaction hook can fail after a successful commit. Independent nested transactions and external side 031 * effects are outside this boundary's result. This result is process-local, not a durable business receipt or 032 * permission to replay an operation. 033 * <p> 034 * The outcome container is thread-safe. The callback value and original failure are retained by reference; 035 * neither is copied or guaranteed immutable or thread-safe, so access to their mutable state requires its own 036 * coordination. A final {@link Error} escapes the invocation instead of being retained in an outcome. 037 * 038 * @param <T> the callback value type 039 * @since 4.9.0 040 */ 041@ThreadSafe 042public final class TransactionOutcome<T> { 043 @NonNull 044 private final TransactionCompletion completion; 045 @NonNull 046 private final Optional<T> attemptedValue; 047 048 TransactionOutcome(@NonNull TransactionCompletion completion, @NonNull Optional<T> attemptedValue) { 049 this.completion = requireNonNull(completion); 050 this.attemptedValue = requireNonNull(attemptedValue); 051 if (completion.getFailure().filter(failure -> !(failure instanceof RuntimeException)).isPresent()) 052 throw new IllegalArgumentException("A transaction outcome can retain only a RuntimeException"); 053 } 054 055 /** 056 * Gets the final completion, after connection cleanup and post-transaction hooks. A configured completion 057 * observer receives this same instance. Its identifiers correlate process-local boundaries, not durable operations. 058 * 059 * @return the completion for this transaction boundary 060 */ 061 @NonNull 062 public TransactionCompletion getCompletion() { 063 return this.completion; 064 } 065 066 /** 067 * Gets this boundary's database result, independently of the callback value and invocation failure. 068 * Boundaries without physical JDBC work retain their logical commit or rollback result. 069 * 070 * @return the database result 071 */ 072 @NonNull 073 public TransactionResult getResult() { 074 return this.completion.getResult(); 075 } 076 077 /** 078 * Gets the value returned normally by the callback, even if completion subsequently rolled back, became 079 * uncertain or failed after commit. A callback that throws has no attempted value. Void callbacks, an empty 080 * optional and an accidentally null optional all produce an empty value. 081 * 082 * @return the attempted callback value, if any 083 */ 084 @NonNull 085 public Optional<T> getAttemptedValue() { 086 return this.attemptedValue; 087 } 088 089 /** 090 * Gets the final invocation failure the traditional transaction API would throw, retaining its identity, 091 * wrapping and suppressed failures. A committed transaction can have a failure, while normal rollback-only 092 * completion has none. Unrecognized failures, including programming errors, should normally be rethrown. 093 * 094 * @return the invocation failure, or empty for successful invocation completion 095 */ 096 @NonNull 097 public Optional<RuntimeException> getFailure() { 098 return this.completion.getFailure().map(RuntimeException.class::cast); 099 } 100}