001/* 002 * Copyright 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.revetsec.soklet; 018 019import org.jspecify.annotations.NonNull; 020 021import javax.annotation.concurrent.ThreadSafe; 022 023import static java.util.Objects.requireNonNull; 024 025/** 026 * The transport outcome of delivering a complete Soklet request to a core protocol operation. An oversized body 027 * discarded by Soklet never invokes the core operation. A completed transport carries the actual core result; 028 * it does not imply protocol acceptance, authentication, authorization or mutation success. 029 * <p> 030 * Only adapter operations construct these outcomes. Later releases may add variants; consuming switches should 031 * include a rejecting default branch. This wrapper never mutates its result. 032 * 033 * @param <T> the core operation's result type 034 * @author <a href="https://www.revetkn.com">Mark Allen</a> 035 * @since 1.0.0 036 */ 037@ThreadSafe 038public abstract sealed class SokletRequestResult<T> 039 permits SokletRequestResult.Completed, SokletRequestResult.TooLarge { 040 SokletRequestResult() { } 041 042 static <T> @NonNull SokletRequestResult<@NonNull T> fromResult(@NonNull T result) { 043 return new Completed<>(requireNonNull(result)); 044 } 045 static <T> @NonNull SokletRequestResult<@NonNull T> fromTooLarge() { return new TooLarge<>(); } 046 047 /** 048 * Returns the transport outcome without body, credentials or protocol data. 049 * @return redacted description 050 * @since 1.0.0 051 */ 052 @Override public final @NonNull String toString() { 053 return "SokletRequestResult{outcome=" + getClass().getSimpleName() + ", data=<redacted>}"; 054 } 055 056 /** 057 * The complete materialized request reached the core operation. Its own result still determines acceptance. 058 * @param <T> the core operation's result type 059 * @author <a href="https://www.revetkn.com">Mark Allen</a> 060 * @since 1.0.0 061 */ 062 @ThreadSafe 063 public static final class Completed<T> extends SokletRequestResult<@NonNull T> { 064 private final @NonNull T result; 065 private Completed(@NonNull T result) { this.result = result; } 066 /** 067 * Returns the actual core outcome, including any protocol rejection or infrastructure disposition. 068 * @return core operation result 069 * @since 1.0.0 070 */ 071 public @NonNull T getResult() { return this.result; } 072 } 073 074 /** 075 * Soklet discarded the oversized body. No core operation ran and no pending state or mutation was consumed. 076 * @param <T> the core operation's result type 077 * @author <a href="https://www.revetkn.com">Mark Allen</a> 078 * @since 1.0.0 079 */ 080 @ThreadSafe 081 public static final class TooLarge<T> extends SokletRequestResult<@NonNull T> { 082 private TooLarge() { } 083 } 084}