001/*
002 * Copyright 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.soklet;
018
019import com.google.errorprone.annotations.CheckReturnValue;
020import org.jspecify.annotations.NonNull;
021
022import javax.annotation.concurrent.ThreadSafe;
023
024import static java.util.Objects.requireNonNull;
025
026/**
027 * Stable, opaque reference identity for one complete transport lifecycle graph.
028 * Independent engines retain one token; decorators return their delegate's exact
029 * token unchanged. Soklet permanently claims the token for the lifecycle that
030 * first accepts its configuration, so a token must not be reused for a distinct
031 * transport graph or lifecycle generation.
032 *
033 * @author <a href="https://www.revetkn.com">Mark Allen</a>
034 */
035@ThreadSafe
036public final class TransportIdentity {
037        @NonNull
038        private final InternalTransportIdentity internalIdentity;
039
040        TransportIdentity(@NonNull InternalTransportIdentity internalIdentity) {
041                this.internalIdentity = requireNonNull(internalIdentity);
042        }
043
044        /**
045         * Creates a fresh reference-identity token distinct from every token previously
046         * returned. Identity tokens intentionally do not have structural equality or
047         * hash-code semantics.
048         *
049         * @return a fresh transport identity
050         */
051        @NonNull
052        @CheckReturnValue
053        public static TransportIdentity create() {
054                return InternalTransportIdentity.create().publicIdentity();
055        }
056
057        @NonNull
058        InternalTransportIdentity internalIdentity() {
059                return this.internalIdentity;
060        }
061}