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}