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.totp;
018
019import java.util.Objects;
020import org.jspecify.annotations.NonNull;
021
022/**
023 * One explicit authoritative observation; omission never represents absence.
024 * @since 1.0.0
025 */
026@javax.annotation.concurrent.Immutable
027public sealed interface TotpStoreEntry permits TotpStoreEntry.Present, TotpStoreEntry.Absent {
028 /**
029  * A versioned permanent sealed record.
030  * @since 1.0.0
031  */
032 @javax.annotation.concurrent.Immutable
033 final class Present implements TotpStoreEntry {
034  private final @NonNull TotpStoreRecord record;
035  private Present(@NonNull TotpStoreRecord record) { this.record = Objects.requireNonNull(record); }
036  /**
037   * Wraps a record read from the exact address.
038   * @param record the opaque record
039   * @return the present observation
040   * @since 1.0.0
041   */
042  public static TotpStoreEntry.@NonNull Present fromRecord(@NonNull TotpStoreRecord record) {
043   return new Present(record);
044  }
045  /**
046   * Returns the immutable opaque record.
047   * @return the record
048   * @since 1.0.0
049   */
050  public @NonNull TotpStoreRecord getRecord() { return this.record; }
051  /**
052   * Redacts the record.
053   * @since 1.0.0
054   */
055  @Override public @NonNull String toString() { return "Present{record=<redacted>}"; }
056 }
057 /**
058  * Confirmed absence at the authoritative snapshot point.
059  * @since 1.0.0
060  */
061 @javax.annotation.concurrent.Immutable
062 final class Absent implements TotpStoreEntry {
063  private static final TotpStoreEntry.@NonNull Absent INSTANCE = new Absent();
064  private Absent() { }
065  /**
066   * Returns the singleton confirmed absence.
067   * @return confirmed absence
068   * @since 1.0.0
069   */
070  public static TotpStoreEntry.@NonNull Absent confirmed() { return INSTANCE; }
071  /**
072   * Returns a fixed description.
073   * @since 1.0.0
074   */
075  @Override public @NonNull String toString() { return "Absent{}"; }
076 }
077}