001/*-
002 * #%L
003 * Smile CDR - CDR
004 * %%
005 * Copyright (C) 2016 - 2026 Smile CDR, Inc.
006 * %%
007 * All rights reserved.
008 * #L%
009 */
010package ca.cdr.test.app.clients.common;
011
012import jakarta.annotation.Nonnull;
013import jakarta.annotation.Nullable;
014
015/**
016 * The HTTP client a test client issues on, and whether closing that test client should close the
017 * HTTP client with it. There are two cases, decided by {@link #resolve(SmileTestHttpClient)}:
018 * <ul>
019 * <li><b>Borrowed</b> ? the caller supplied a {@link SmileTestHttpClient}, typically a harness
020 *     lending one client to everything it hands out. The connection pool and cookie store stay the
021 *     supplier's, so closing the test client must leave them up for the siblings still using
022 *     them.</li>
023 * <li><b>Owned</b> ? the caller supplied {@literal null}, so a client was built here.
024 *     Nothing else holds a reference, so closing the test client is the only thing that can
025 *     release the pool.</li>
026 * </ul>
027 *
028 * @param client the client to issue requests on
029 * @param owned {@literal true} in the owned case, so {@link #closeIfOwned()} closes {@code client}
030 */
031// Created by claude-opus-5
032public record HttpClientOwnership(@Nonnull SmileTestHttpClient client, boolean owned) {
033
034        /**
035         * Decides which of the two cases applies for a client built with {@code theSuppliedClient},
036         * building a client when the caller supplied none.
037         *
038         * @param theSuppliedClient the client the caller supplied, or {@literal null} to build one
039         */
040        public static @Nonnull HttpClientOwnership resolve(@Nullable SmileTestHttpClient theSuppliedClient) {
041                return theSuppliedClient == null
042                        ? new HttpClientOwnership(SmileTestHttpClient.create(), true)
043                        : new HttpClientOwnership(theSuppliedClient, false);
044        }
045
046        /**
047         * Releases the connection pool when this client built it, and does nothing when the pool was
048         * supplied by a caller that still needs it.
049         */
050        public void closeIfOwned() {
051                if (owned) {
052                        client.close();
053                }
054        }
055}