001/*
002 * Copyright © 2025 CUI-OpenSource-Software (info@cuioss.de)
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 */
016package de.cuioss.http.client;
017
018/**
019 * Common interface for components that provide health status information.
020 * <p>
021 * This interface unifies health checking across different JWT validation components
022 * by providing a consistent way to check component health and retrieve detailed status information.
023 * <p>
024 * Implementation requirements:
025 * <ul>
026 *   <li>Implementations must be thread-safe for concurrent access</li>
027 *   <li>{@link #getLoaderStatus()} must be non-blocking and return immediately</li>
028 *   <li>Status checks must NOT trigger I/O operations or network requests</li>
029 * </ul>
030 * <p>
031 * Usage example:
032 * <pre>
033 * LoadingStatusProvider provider = someComponent;
034 * LoaderStatus status = provider.getLoaderStatus();
035 * if (status == LoaderStatus.OK) {
036 *     // Component is healthy and ready to use
037 * } else if (status == LoaderStatus.ERROR) {
038 *     // Handle error state
039 * } else {
040 *     // Handle undefined state
041 * }
042 * </pre>
043 *
044 * @author Oliver Wolff
045 * @since 1.0
046 */
047public interface LoadingStatusProvider {
048
049    /**
050     * Gets the current status of the loading operation without blocking.
051     * <p>
052     * This method must be non-blocking and return immediately with the current cached status.
053     * It must NOT trigger any I/O operations, network requests, or other potentially blocking operations.
054     * <p>
055     * The returned status values:
056     * <ul>
057     *   <li>{@link LoaderStatus#OK} - Component is operational and healthy</li>
058     *   <li>{@link LoaderStatus#ERROR} - Component encountered an error</li>
059     *   <li>{@link LoaderStatus#LOADING} - Component is in the process of loading or initializing</li>
060     *   <li>{@link LoaderStatus#UNDEFINED} - Initial state, not yet initialized</li>
061     * </ul>
062     * <p>
063     * Implementation requirements:
064     * <ul>
065     *   <li>Must be thread-safe for concurrent calls</li>
066     *   <li>Must return immediately without blocking</li>
067     *   <li>Must NOT perform any I/O operations or network requests</li>
068     *   <li>Should return the current cached status from memory</li>
069     *   <li>Required for MicroProfile Health compliance for readiness checks</li>
070     *   <li>In exceptional cases, may return UNDEFINED rather than throwing</li>
071     * </ul>
072     *
073     * @return the current status of the loading operation from cache/memory, never {@code null}
074     */
075    LoaderStatus getLoaderStatus();
076
077    /**
078     * Convenience method to check if the loader status is OK.
079     * <p>
080     * This method provides a simplified way to check if the component is healthy
081     * without directly comparing the status enum.
082     *
083     * @return {@code true} if the component status is {@link LoaderStatus#OK}, {@code false} otherwise
084     */
085    default boolean isLoaderStatusOK() {
086        return getLoaderStatus() == LoaderStatus.OK;
087    }
088}