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.oauth; 018 019import org.jspecify.annotations.NonNull; 020import javax.annotation.concurrent.Immutable; 021import static java.util.Objects.requireNonNull; 022 023/** 024 * The outcome of a cached client-credentials token acquisition. 025 * Non-transient endpoint client errors return a fixed rejection; transport, metadata, malformed responses and 026 * transient endpoint failures remain exceptions. Applications receive outcomes from the operation and cannot 027 * construct them. A later release may add variants; consuming switches should include a rejecting default. 028 * @author <a href="https://www.revetkn.com">Mark Allen</a> 029 * @since 1.0.0 030 */ 031@Immutable 032public abstract sealed class AccessTokenAcquisitionResult permits AccessTokenAcquisitionResult.Succeeded, AccessTokenAcquisitionResult.Rejected { 033 AccessTokenAcquisitionResult() { } 034 static @NonNull AccessTokenAcquisitionResult fromAccessToken(@NonNull AccessToken accessToken) { 035 return new Succeeded(requireNonNull(accessToken)); 036 } 037 static AccessTokenAcquisitionResult.@NonNull Rejected fromRejection(OAuthTokenRequestResult.@NonNull Rejected rejection) { 038 return new Rejected(rejection.getError(), rejection.getStatus()); 039 } 040 /** 041 * Returns the outcome kind with all values redacted. 042 * @return redacted description 043 * @since 1.0.0 044 */ 045 @Override 046 public final @NonNull String toString() { 047 return "AccessTokenAcquisitionResult{outcome=" + getClass().getSimpleName() + ", data=<redacted>}"; 048 } 049 /** 050 * The source returned a currently valid access token, from its cache or a completed renewal. 051 * @author <a href="https://www.revetkn.com">Mark Allen</a> 052 * @since 1.0.0 053 */ 054 @Immutable 055 public static final class Succeeded extends AccessTokenAcquisitionResult { 056 private final @NonNull AccessToken value; 057 private Succeeded(@NonNull AccessToken value) { this.value = requireNonNull(value); } 058 /** 059 * Returns the value released after all operation checks passed. 060 * @return checked value 061 * @since 1.0.0 062 */ 063 public @NonNull AccessToken getAccessToken() { return this.value; } 064 } 065 /** 066 * The endpoint returned a non-transient client error. No response body or credential is retained. 067 * @author <a href="https://www.revetkn.com">Mark Allen</a> 068 * @since 1.0.0 069 */ 070 @Immutable 071 public static final class Rejected extends AccessTokenAcquisitionResult { 072 private final @NonNull OAuthEndpointError error; 073 private final int status; 074 private Rejected(@NonNull OAuthEndpointError error, int status) { 075 this.error = requireNonNull(error); this.status = status; 076 } 077 /** 078 * Returns the fixed endpoint error; unrecognized or absent codes use the same fallback. 079 * @return fixed endpoint error 080 * @since 1.0.0 081 */ 082 public @NonNull OAuthEndpointError getError() { return this.error; } 083 /** 084 * Returns the endpoint's HTTP status. 085 * @return endpoint status 086 * @since 1.0.0 087 */ 088 public @NonNull Integer getStatus() { return this.status; } 089 } 090}