/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.juneau.commons.settings;

import static org.apache.juneau.commons.function.Suppliers.*;
import static org.apache.juneau.commons.reflect.ReflectionUtils.*;
import static org.apache.juneau.commons.utils.Shorts.*;

import java.nio.charset.*;
import java.util.*;
import java.util.concurrent.*;
import java.util.function.*;

import org.apache.juneau.commons.function.*;
import org.apache.juneau.commons.reflect.*;

/**
 * Encapsulates Java system properties with support for global and per-thread overrides for unit testing.
 *
 * <p>
 * This class provides a thread-safe way to access system properties that can be overridden at both the global level
 * and per-thread level, making it useful for unit tests that need to temporarily change system property
 * values without affecting other tests or threads.
 *
 * <p>
 * Settings instances are created using the {@link Builder} pattern. Use {@link #create()} to create a new builder,
 * or {@link #get()} to get the singleton instance (which is created using default builder settings).
 *
 * <h2 class='section'>Lookup Order:</h2>
 * <p>
 * When retrieving a property value, the lookup order is:
 * <ol>
 *    <li>Per-thread store (if set via {@link #setLocal(String, String)})
 *    <li>Global store (if set via {@link #setGlobal(String, String)})
 *    <li>Sources added at runtime through {@link #addSource(PropertySource)}, newest first
 *    <li>The system-default <c>Config</c>, when juneau-config is on the classpath (SPI order 100)
 *    <li>Command-line args (SPI order 50)
 *    <li>Java system properties (SPI order 40)
 *    <li>Environment variables, verbatim (SPI order 30)
 *    <li>The <c>.env</c> file (SPI order 20)
 *    <li>The jar manifest (SPI order 10)
 *    <li>Environment variables, relaxed spelling (registered first, so checked last)
 * </ol>
 *
 * <p>
 * If SPI registered no system-property source (a shaded jar that does not merge <c>META-INF/services</c>, for example),
 * a fallback system-property source sits just above the relaxed environment source.
 *
 * <h2 class='section'>Sources vs Stores:</h2>
 * <ul class='spaced-list'>
 *    <li><b>Sources</b> ({@link PropertySource}) - Provide read-only access to property values. Examples: {@link FunctionalPropertySource}
 *    <li><b>Stores</b> ({@link PropertyStore}) - Provide read/write access to property values. Examples: {@link MapStore}, {@link FunctionalPropertyStore}
 *    <li>Stores can be used as sources (they extend {@link PropertySource}), so you can add stores via {@link Builder#addSource(PropertySource)}
 * </ul>
 *
 * <h2 class='section'>Features:</h2>
 * <ul class='spaced-list'>
 *    <li>System property access - read Java system properties with type conversion via {@link StringSetting}
 *    <li>Global overrides - override system properties globally for all threads (stored in a {@link PropertyStore})
 *    <li>Per-thread overrides - override system properties for specific threads (stored in a per-thread {@link PropertyStore})
 *    <li>Custom sources - add arbitrary property sources (e.g., Spring properties, environment variables, config files) via the {@link Builder}
 *    <li>Disable override support - system property to prevent new global overrides from being set
 *    <li>Type-safe accessors - type conversion methods on {@link StringSetting} for common types: Integer, Long, Boolean, Double, Float, File, Path, URI, Charset
 *    <li>Resettable suppliers - settings are returned as {@link StringSetting} instances that can be reset to force recomputation
 * </ul>
 *
 * <h2 class='section'>Usage Examples:</h2>
 * <p class='bjava'>
 *    <jc>// Get a system property as a StringSetting (using singleton instance)</jc>
 *    StringSetting <jv>setting</jv> = Settings.<jsf>get</jsf>().get(<js>"my.property"</js>);
 *    String <jv>value</jv> = <jv>setting</jv>.get();  <jc>// Get the string value</jc>
 *
 *    <jc>// Get with type conversion using StringSetting methods</jc>
 *    Setting&lt;Integer&gt; <jv>intSetting</jv> = Settings.<jsf>get</jsf>().get(<js>"my.int.property"</js>).asInteger();
 *    Setting&lt;Long&gt; <jv>longSetting</jv> = Settings.<jsf>get</jsf>().get(<js>"my.long.property"</js>).asLong();
 *    Setting&lt;Boolean&gt; <jv>boolSetting</jv> = Settings.<jsf>get</jsf>().get(<js>"my.bool.property"</js>).asBoolean();
 *    Setting&lt;Double&gt; <jv>doubleSetting</jv> = Settings.<jsf>get</jsf>().get(<js>"my.double.property"</js>).asDouble();
 *    Setting&lt;Float&gt; <jv>floatSetting</jv> = Settings.<jsf>get</jsf>().get(<js>"my.float.property"</js>).asFloat();
 *    Setting&lt;File&gt; <jv>fileSetting</jv> = Settings.<jsf>get</jsf>().get(<js>"my.file.property"</js>).asFile();
 *    Setting&lt;Path&gt; <jv>pathSetting</jv> = Settings.<jsf>get</jsf>().get(<js>"my.path.property"</js>).asPath();
 *    Setting&lt;URI&gt; <jv>uriSetting</jv> = Settings.<jsf>get</jsf>().get(<js>"my.uri.property"</js>).asURI();
 *    Setting&lt;Charset&gt; <jv>charsetSetting</jv> = Settings.<jsf>get</jsf>().get(<js>"my.charset.property"</js>).asCharset();
 *
 *    <jc>// Use custom type conversion</jc>
 *    Setting&lt;MyCustomType&gt; <jv>customSetting</jv> = Settings.<jsf>get</jsf>().get(<js>"my.custom.property"</js>).asType(MyCustomType.<jk>class</jk>);
 *
 *    <jc>// Reset a setting to force recomputation</jc>
 *    <jv>setting</jv>.reset();
 *
 *    <jc>// Override for current thread (useful in unit tests)</jc>
 *    Settings.<jsf>get</jsf>().setLocal(<js>"my.property"</js>, <js>"test-value"</js>);
 *    <jc>// ... test code that uses the override ...</jc>
 *    Settings.<jsf>get</jsf>().unsetLocal(<js>"my.property"</js>);  <jc>// Remove specific override</jc>
 *    <jc>// OR</jc>
 *    Settings.<jsf>get</jsf>().clearLocal();  <jc>// Clear all thread-local overrides</jc>
 *
 *    <jc>// Set global override (applies to all threads)</jc>
 *    Settings.<jsf>get</jsf>().setGlobal(<js>"my.property"</js>, <js>"global-value"</js>);
 *    <jc>// ... code that uses the global override ...</jc>
 *    Settings.<jsf>get</jsf>().unsetGlobal(<js>"my.property"</js>);  <jc>// Remove specific override</jc>
 *    <jc>// OR</jc>
 *    Settings.<jsf>get</jsf>().clearGlobal();  <jc>// Clear all global overrides</jc>
 *
 *    <jc>// Create a custom Settings instance with custom sources (e.g., Spring properties)</jc>
 *    MapStore <jv>springSource</jv> = <jk>new</jk> MapStore();
 *    <jv>springSource</jv>.set(<js>"spring.datasource.url"</js>, <js>"jdbc:postgresql://localhost/db"</js>);
 *    Settings <jv>custom</jv> = Settings.<jsf>create</jsf>()
 *       .addSource(<jv>springSource</jv>)
 *       .addSource(FunctionalPropertySource.<jsf>of</jsf>(System::getProperty))
 *       .build();
 * </p>
 *
 * <h2 class='section'>System Properties:</h2>
 * <ul class='spaced-list'>
 *    <li><c>juneau.settings.disableGlobal</c> (system property) or <c>JUNEAU_SETTINGS_DISABLEGLOBAL</c> (system env) - If set to <c>true</c>, prevents new global overrides
 *       from being set via {@link #setGlobal(String, String)}. Existing global overrides will still be
 *       returned by {@link #get(String)} until explicitly removed.
 *       <p class='bnote'>
 *          Note: This property is read once at class initialization time when creating the singleton instance
 *          and cannot be changed at runtime. Changing the system property after the class has been loaded will
 *          have no effect on the singleton instance. However, you can create custom Settings instances using
 *          {@link #create()} that ignore this property.
 *       </p>
 * </ul>
 */
@SuppressWarnings({
   "java:S115", // Constants use UPPER_snakeCase convention (e.g., MSG_globalDisabled)
   "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants
   "unchecked" // Type erasure requires unchecked cast
})
public class Settings {

   /**
    * System property source that delegates to {@link System#getProperty(String)}.
    */
   public static final PropertySource SYSTEM_PROPERTY_SOURCE = FunctionalPropertySource.of(System::getProperty);

   private static final Set<String> FROM_STRING_METHOD_NAMES = new LinkedHashSet<>(Arrays.asList("fromString", "parse", "forName", "valueOf"));

   /**
    * System environment variable source that delegates to {@link System#getenv(String)}.
    */
   public static final PropertySource SYSTEM_ENV_SOURCE = FunctionalPropertySource.of(System::getenv);

   /**
    * {@link #SYSTEM_ENV_SOURCE} wrapped with {@link RelaxedPropertySource relaxed binding}, so a single logical key
    * resolves from any of the common environment-variable spellings (e.g. {@code my.prop} / {@code myProp} /
    * {@code MySection/myKey} all satisfied by {@code MY_PROP} / {@code MY_SECTION_MY_KEY}).
    *
    * <p>
    * This is the env source used by the default {@link #get() singleton}.  It is verbatim-first, so exact-match
    * behavior is unchanged &mdash; a relaxed variant is only probed when the exact name misses.
    *
    * <p>
    * Its runtime class is a {@link CachingPropertySource} wrapping the relaxed source.  The environment is immutable
    * inside the JVM, so caching is safe, and every chain that uses this constant shares one cache.
    *
    * @since 10.0.0
    */
   public static final PropertySource RELAXED_SYSTEM_ENV_SOURCE = CachingPropertySource.of(new RelaxedPropertySource(SYSTEM_ENV_SOURCE));

   private static final String DISABLE_GLOBAL_PROP = "juneau.settings.disableGlobal";
   private static final String MSG_globalDisabled = "Global settings not enabled";
   private static final String MSG_localDisabled = "Local settings not enabled";

   /**
    * Returns properties for this Settings object itself.
    * Note that these are initialized at startup and not changeable through System.setProperty().
    */
   private static final Optional<String> initProperty(String property) {
      var v = SYSTEM_PROPERTY_SOURCE.get(property);
      if (v.isPresent())
         return v.value();  // Not testable
      v = SYSTEM_ENV_SOURCE.get(ucr(property.replace('.', '_')));
      if (v.isPresent())
         return v.value();  // Not testable
      return oe();
   }

   /**
    * Creates a new builder for constructing a Settings instance.
    *
    * <p>
    * This method provides a convenient way to create custom Settings instances with specific
    * configuration. The builder allows you to configure stores, sources, and other settings
    * before building the final Settings instance.
    *
    * <h4 class='section'>Example:</h4>
    * <p class='bjava'>
    *    <jc>// Create a custom Settings instance</jc>
    *    Settings <jv>custom</jv> = Settings.<jsf>create</jsf>()
    *       .globalStore(() -&gt; <jk>new</jk> MapStore())
    *       .localStore(() -&gt; <jk>new</jk> MapStore())
    *       .addSource(FunctionalPropertySource.<jsf>of</jsf>(System::getProperty))
    *       .build();
    * </p>
    *
    * @return A new Builder instance.
    */
   public static Builder create() {
      return new Builder();
   }

   /**
    * Builder for creating Settings instances.
    */
   public static class Builder {
      private Supplier<PropertyStore> globalStoreSupplier = MapStore::new;
      private Supplier<PropertyStore> localStoreSupplier = MapStore::new;
      private final List<PropertySource> sources = new ArrayList<>();
      private final Map<Class<?>,Function<String,?>> customTypeFunctions = new IdentityHashMap<>();

      /**
       * Sets the supplier for the global store.
       *
       * @param supplier The supplier for the global store.  Must not be <c>null</c>.  Can supply null to disable global store.
       * @return This builder for method chaining.
       */
      public Builder globalStore(NullableSupplier<PropertyStore> supplier) {
         this.globalStoreSupplier = reqnn("supplier", supplier);
         return this;
      }

      /**
       * Sets the supplier for the local (per-thread) store.
       *
       * @param supplier The supplier for the local store. Must not be <c>null</c>.
       * @return This builder for method chaining.
       */
      public Builder localStore(NullableSupplier<PropertyStore> supplier) {
         this.localStoreSupplier = reqnn("supplier", supplier);
         return this;
      }

      /**
       * Sets the sources list, replacing any existing sources.
       *
       * @param sources The sources to set. Must not be <c>null</c> or contain <c>null</c> elements.
       * @return This builder for method chaining.
       */
      @SafeVarargs
      public final Builder setSources(PropertySource...sources) {
         reqnns("sources", sources);
         this.sources.clear();
         for (var source : sources) {
            this.sources.add(source);
         }
         return this;
      }

      /**
       * Adds a source to the sources list.
       *
       * @param source The source to add. Must not be <c>null</c>.
       * @return This builder for method chaining.
       */
      public Builder addSource(PropertySource source) {
         reqnn("source", source);
         this.sources.add(source);
         return this;
      }

      /**
       * Adds a functional source to the sources list.
       *
       * @param source The functional source to add. Must not be <c>null</c>.
       * @return This builder for method chaining.
       */
      public Builder addSource(FunctionalPropertySource source) {
         return addSource((PropertySource)source);
      }

      /**
       * Discovers and registers {@link PropertySourceProvider} instances via {@link ServiceLoader}.
       *
       * <p>
       * Providers are sorted by {@link PropertySourceProvider#order()} ascending.
       *
       * @return This builder for method chaining.
       */
      public Builder useServiceLoader() {
         return addProviders(ServiceLoader.load(PropertySourceProvider.class).stream().map(ServiceLoader.Provider::get).toList());
      }

      /** Sorts the providers by {@link PropertySourceProvider#order()} ascending, creates their sources and appends the non-null ones. */
      Builder addProviders(Collection<? extends PropertySourceProvider> providers) {
         providers.stream()
            .sorted(Comparator.comparingInt(PropertySourceProvider::order))
            .map(PropertySourceProvider::create)
            .filter(Objects::nonNull)
            .forEach(this::addSource);
         return this;
      }

      /** Inserts a source at the given index. */
      Builder insertSource(int index, PropertySource source) {
         reqnn("source", source);
         this.sources.add(index, source);
         return this;
      }

      /** An unmodifiable view of the sources registered so far. */
      List<PropertySource> sourceList() {
         return Collections.unmodifiableList(sources);
      }

      /**
       * Registers a custom type conversion function for the specified type.
       *
       * <p>
       * This allows you to add support for converting string values to custom types when using
       * {@link Settings#get(String, Object)}. The function will be used to convert string values
       * to the specified type.
       *
       * <h4 class='section'>Example:</h4>
       * <p class='bjava'>
       *    <jc>// Register a custom converter for a custom type</jc>
       *    Settings <jv>custom</jv> = Settings.<jsf>create</jsf>()
       *       .addTypeFunction(Integer.<jk>class</jk>, Integer::valueOf)
       *       .addTypeFunction(MyCustomType.<jk>class</jk>, MyCustomType::fromString)
       *       .build();
       *
       *    <jc>// Now you can use get() with these types</jc>
       *    Integer <jv>intValue</jv> = <jv>custom</jv>.get(<js>"my.int.property"</js>, 0);
       *    MyCustomType <jv>customValue</jv> = <jv>custom</jv>.get(<js>"my.custom.property"</js>, MyCustomType.DEFAULT);
       * </p>
       *
       * @param <T> The type to register a converter for.
       * @param type The class type to register a converter for. Must not be <c>null</c>.
       * @param function The function that converts a string to the specified type. Must not be <c>null</c>.
       * @return This builder for method chaining.
       */
      public <T> Builder addTypeFunction(Class<T> type, Function<String,T> function) {
         reqnn("type", type);
         reqnn("function", function);
         customTypeFunctions.put(type, function);
         return this;
      }

      /**
       * Builds a Settings instance from this builder.
       *
       * @return A new Settings instance.
       */
      public Settings build() {
         return new Settings(this);
      }
   }

   /**
    * Builds the default chain: the relaxed env source, then the SPI providers sorted by order, then (only when no SPI
    * provider registered a system-property source) {@link #SYSTEM_PROPERTY_SOURCE} at index 1.
    *
    * <p>
    * Detection may fail safe (keep a duplicate) but must never fail unsafe (drop the only system-property source).
    */
   static Builder defaultBuilder(Collection<PropertySourceProvider> providers) {
      var b = new Builder().setSources(RELAXED_SYSTEM_ENV_SOURCE).addProviders(providers);
      if (b.sourceList().stream().noneMatch(Settings::isSpiSystemPropertySource))
         b.insertSource(1, SYSTEM_PROPERTY_SOURCE);  // no SPI sysprop source: keep today's fallback at today's index
      return b;
   }

   @SuppressWarnings({
      "java:S1872" // Exact-class match by name on purpose: any classloader counts, subclasses must not (fail safe).
   })
   private static boolean isSpiSystemPropertySource(PropertySource s) {
      return s.getClass().getName().equals(SystemPropertyPropertySource.class.getName());  // exact class name, any loader
   }

   private static final Settings INSTANCE = defaultBuilder(ServiceLoader.load(PropertySourceProvider.class).stream().map(ServiceLoader.Provider::get).toList())
      .globalStore(initProperty(DISABLE_GLOBAL_PROP).map(Boolean::valueOf).orElse(false) ? () -> null : MapStore::new)
      .build();

   /**
    * Returns the singleton instance of Settings.
    *
    * @return The singleton Settings instance.
    */
   public static Settings get() {
      return INSTANCE;
   }

   private final Memoizer<PropertyStore> globalStore;
   @SuppressWarnings({
      "java:S5164" // Cleanup method provided: cleanup()
   })
   private final ThreadLocal<PropertyStore> localStore;
   private final List<PropertySource> sources;
   private final Map<Class<?>,Function<String,?>> toTypeFunctions;

   /**
    * Constructor.
    */
   private Settings(Builder builder) {
      this.globalStore = memoizer(builder.globalStoreSupplier);
      this.localStore = ThreadLocal.withInitial(builder.localStoreSupplier);
      this.sources = new CopyOnWriteArrayList<>(builder.sources);
      this.toTypeFunctions = new ConcurrentHashMap<>(builder.customTypeFunctions);
   }

   /**
    * Adds a property source after this settings instance has been built.
    *
    * @param source The property source to add. Must not be <jk>null</jk>.
    * @return This object for method chaining.
    */
   public Settings addSource(PropertySource source) {
      reqnn("source", source);
      sources.add(source);
      return this;
   }

   /**
    * Returns the number of {@link PropertySource}s currently registered with this
    * {@code Settings} instance.
    *
    * <p>
    * Intended primarily for tests that need to verify nothing has leaked extra sources into the
    * process-wide {@link #get() Settings.get()} singleton &mdash; the historical failure mode
    * documented where a per-{@code RestContext}
    * config bridge added a {@code ConfigPropertySource} per cached {@code RestContext} via
    * {@link #addSource(PropertySource)} and never removed it.
    *
    * @return The current source count. Always {@code &gt;= 0}.
    */
   public int sourceCount() {
      return sources.size();
   }

   /**
    * Returns a live, read-only view of the registered sources, in registration order.  Package-private, for tests.
    *
    * @return An unmodifiable view; later {@link #addSource} / {@link #removeSource} calls show through.
    */
   List<PropertySource> sources() {
      return Collections.unmodifiableList(sources);
   }

   /**
    * Removes a previously-added property source.
    *
    * <p>
    * The match is by identity ({@code ==}), not equality.  Callers that mutate the singleton
    * {@link #get() Settings.get()} from a test should capture the exact reference returned to/passed
    * into {@link #addSource(PropertySource)} and pass it back here in their teardown to avoid
    * cross-test bleed.
    *
    * @param source The property source to remove. Must not be <jk>null</jk>.
    * @return <jk>true</jk> if the source was present and removed, <jk>false</jk> otherwise.
    */
   public boolean removeSource(PropertySource source) {
      reqnn("source", source);
      // Identity-based removal so that PropertySource impls without a sensible equals() still
      // round-trip cleanly through add/remove pairs.
      // Removals are serialized so the index found in the snapshot is still valid when removed; addSource only appends.
      synchronized (sources) {
         var snapshot = sources.toArray(new PropertySource[0]);
         for (var i = 0; i < snapshot.length; i++) {
            if (snapshot[i] == source) {
               sources.remove(i);
               return true;
            }
         }
      }
      return false;
   }

   /**
    * Returns a {@link StringSetting} for the specified system property.
    *
    * <p>
    * The returned {@link StringSetting} is a resettable supplier that caches the lookup result.
    * Use the {@link StringSetting#asInteger()}, {@link StringSetting#asBoolean()}, etc. methods
    * to convert to different types.
    *
    * <p>
    * The lookup order is:
    * <ol>
    *    <li>Per-thread override (if set via {@link #setLocal(String, String)})
    *    <li>Global override (if set via {@link #setGlobal(String, String)})
    *    <li>Sources added at runtime through {@link #addSource(PropertySource)}, newest first
    *    <li>The system-default <c>Config</c>, when juneau-config is on the classpath (SPI order 100)
    *    <li>Command-line args (SPI order 50)
    *    <li>Java system properties (SPI order 40)
    *    <li>Environment variables, verbatim (SPI order 30)
    *    <li>The <c>.env</c> file (SPI order 20)
    *    <li>The jar manifest (SPI order 10)
    *    <li>Environment variables, relaxed spelling (registered first, so checked last)
    * </ol>
    *
    * <p>
    * If SPI registered no system-property source (a shaded jar that does not merge <c>META-INF/services</c>, for example),
    * a fallback system-property source sits just above the relaxed environment source.
    *
    * @param name The property name. Must not be <jk>null</jk>.
    * @return A {@link StringSetting} that provides the resolved property value.
    */
   public StringSetting get(String name) {
      reqnn("name", name);
      return new StringSetting(this, () -> resolve(name));
   }

   /**
    * Walks the thread-local store, the global store, then every source newest first. The one copy of the lookup order.
    *
    * @return The resolved value, or <jk>null</jk> when no store or source defines the name or the winner is an explicit null.
    */
   private String resolve(String name) {
      // 1. Check thread-local override
      var v = localStore.get().get(name);
      if (v.isPresent())
         return v.value().orElse(null); // Present result: Optional.empty() means explicit null override.

      // 2. Check global override
      v = globalLookup(name);
      if (v.isPresent())
         return v.value().orElse(null); // Present result: Optional.empty() means explicit null override.

      // 3. Check sources in reverse order (last added first)
      // Iterate one snapshot so a concurrent removeSource() can't shrink the list between size() and get(i).
      var snapshot = sources.toArray(new PropertySource[0]);
      for (int i = snapshot.length - 1; i >= 0; i--) {
         var source = snapshot[i];
         var result = source.get(name);
         if (result.isPresent())
            return result.value().orElse(null);
      }

      return null;
   }

   /**
    * Returns the override value for the specified property, consulting only the per-thread
    * (local) and global stores &mdash; <i>not</i> the sources list.
    *
    * <p>
    * Intended for callers (notably the {@code @Value} resolution path) that interleave a
    * caller-scoped property source between the Settings override stores and the sources list.
    * Using this method, the caller can honor the "{@link #setLocal(String, String) local}
    * / {@link #setGlobal(String, String) global} override wins" contract before consulting
    * its own scoped sources, and still fall through to {@link #get(String)} (which checks
    * the sources list) afterwards without the override stores accidentally being consulted twice.
    *
    * <p>
    * Lookup order honored by this method:
    * <ol>
    *    <li>Per-thread (local) store
    *    <li>Global store
    * </ol>
    *
    * <p>
    * If a store is present with an empty value (i.e. an explicit null override), the returned
    * {@link Optional} is {@code Optional.empty()} but {@link #isOverridden(String)} would
    * return {@code true}. Callers needing to distinguish "absent" from "explicit null" should
    * use {@link #isOverridden(String)} alongside this method.
    *
    * @param name The property name. Must not be <jk>null</jk>.
    * @return The override value, or {@link Optional#empty()} if neither store carries an override.
    * @see #isOverridden(String)
    * @see #get(String)
    */
   public Optional<String> getOverride(String name) {
      reqnn("name", name);
      var v = localStore.get().get(name);
      if (v.isPresent())
         return v.value();
      v = globalLookup(name);
      if (v.isPresent())
         return v.value();
      return oe();
   }

   /**
    * Returns <jk>true</jk> if the specified property has an override in either the per-thread
    * (local) or global store.
    *
    * <p>
    * Distinguishes the "explicit null override" case &mdash; where {@link #getOverride(String)}
    * returns {@link Optional#empty()} because the override value itself was {@code null} &mdash;
    * from the "no override" case.
    *
    * @param name The property name. Must not be <jk>null</jk>.
    * @return <jk>true</jk> if either store carries an override (even with a {@code null} value).
    */
   public boolean isOverridden(String name) {
      reqnn("name", name);
      return localStore.get().get(name).isPresent() || globalLookup(name).isPresent();
   }

   /** Looks up an override in the global store, which is absent (null) when global overrides are disabled. */
   private PropertyLookupResult globalLookup(String name) {
      var store = globalStore.get();
      return n(store) ? PropertyLookupResult.missing() : store.get(name);
   }

   /**
    * Looks up a system property, returning a default value if not found.
    *
    * <p>
    * This method searches for a value using the same lookup order as {@link #get(String)}.
    * If a value is found, it is converted to the type of the default value using {@link #toType(String, Class)}.
    * Supported types include any type that has a static method with signature <c>public static &lt;T&gt; T anyName(String arg)</c>
    * or a public constructor with signature <c>public T(String arg)</c>, such as {@link Boolean}, {@link Integer}, {@link Charset}, {@link java.io.File}, etc.
    *
    * <h4 class='section'>Example:</h4>
    * <p class='bjava'>
    *    <jc>// System property: -Dmy.property=true</jc>
    *    Boolean <jv>flag</jv> = get(<js>"my.property"</js>, <jk>false</jk>);  <jc>// true</jc>
    *
    *    <jc>// Environment variable: MY_PROPERTY=UTF-8</jc>
    *    Charset <jv>charset</jv> = get(<js>"my.property"</js>, Charset.defaultCharset());  <jc>// UTF-8</jc>
    *
    *    <jc>// Not found, returns default</jc>
    *    String <jv>value</jv> = get(<js>"nonexistent"</js>, <js>"default"</js>);  <jc>// "default"</jc>
    * </p>
    *
    * @param <T> The type to convert the value to.
    * @param name The property name. Must not be <jk>null</jk>.
    * @param def The default value to return if not found. Must not be <jk>null</jk>.
    * @return The found value (converted to type T), or the default value if not found.
    * @see #get(String)
    * @see #toType(String, Class)
    */
   public <T> T get(String name, T def) {
      reqnn("def", def);
      reqnn("name", name);
      var v = resolve(name);
      if (v == null)
         return def;
      var t = toType(v, (Class<T>)def.getClass());
      return t == null ? def : t;  // matches the filter(Objects::nonNull) in StringSetting.asType
   }

   /**
    * Sets a global override for the specified property.
    *
    * <p>
    * This override will apply to all threads and takes precedence over system properties.
    * However, per-thread overrides (set via {@link #setLocal(String, String)}) will still take precedence
    * over global overrides.
    *
    * <p>
    * If the <c>juneau.settings.disableGlobal</c> system property is set to <c>true</c>,
    * this method will throw an exception. This allows system administrators
    * to prevent applications from overriding system properties globally.
    *
    * <p>
    * Setting a value to <c>null</c> will store an empty optional, effectively overriding the system
    * property to return empty. Use {@link #unsetGlobal(String)} to completely remove the override.
    *
    * @param name The property name. Must not be <jk>null</jk>.
    * @param value The override value, or <c>null</c> to set an empty override.
    * @return This object for method chaining.
    * @see #unsetGlobal(String)
    * @see #clearGlobal()
    */
   public Settings setGlobal(String name, String value) {
      reqnn("name", name);
      globalStore.orElseThrow(()->isex(MSG_globalDisabled)).set(name, value);
      return this;
   }

   /**
    * Removes a global override for the specified property.
    *
    * <p>
    * After calling this method, the property will fall back to the system property value
    * (or per-thread override if one exists).
    *
    * @param name The property name. Must not be <jk>null</jk>.
    * @see #setGlobal(String, String)
    * @see #clearGlobal()
    */
   public void unsetGlobal(String name) {
      reqnn("name", name);
      globalStore.orElseThrow(()->isex(MSG_globalDisabled)).unset(name);
   }

   /**
    * Sets a per-thread override for the specified property.
    *
    * <p>
    * This override will only apply to the current thread and takes precedence over global overrides
    * and system properties. This is particularly useful in unit tests where you need to temporarily
    * change a system property value without affecting other threads or tests.
    *
    * <p>
    * Setting a value to <c>null</c> will store an empty optional, effectively overriding the property
    * to return empty for this thread. Use {@link #unsetLocal(String)} to completely remove the override.
    *
    * @param name The property name. Must not be <jk>null</jk>.
    * @param value The override value, or <c>null</c> to set an empty override.
    * @return This object for method chaining.
    * @see #unsetLocal(String)
    * @see #clearLocal()
    */
   public Settings setLocal(String name, String value) {
      reqnn("name", name);
      chk(nn(localStore.get()), MSG_localDisabled);
      localStore.get().set(name, value);
      return this;
   }

   /**
    * Removes a per-thread override for the specified property.
    *
    * <p>
    * After calling this method, the property will fall back to the global override (if set)
    * or the system property value for the current thread.
    *
    * @param name The property name. Must not be <jk>null</jk>.
    * @see #setLocal(String, String)
    * @see #clearLocal()
    */
   public void unsetLocal(String name) {
      reqnn("name", name);
      chk(nn(localStore.get()), MSG_localDisabled);
      localStore.get().unset(name);
   }

   /**
    * Clears all per-thread overrides for the current thread.
    *
    * <p>
    * After calling this method, all properties will fall back to global overrides (if set)
    * or system property values for the current thread.
    *
    * <p>
    * This is typically called in a <c>@AfterEach</c> or <c>@After</c> test method to clean up
    * thread-local overrides after a test completes.
    *
    * @return This object for method chaining.
    * @see #setLocal(String, String)
    * @see #unsetLocal(String)
    */
   public Settings clearLocal() {
      chk(nn(localStore.get()), MSG_localDisabled);
      localStore.get().clear();
      return this;
   }

   /**
    * Cleans up thread-local storage for the current thread.
    *
    * <p>
    * This method should be called when a thread is finished using this Settings instance to prevent memory leaks
    * in thread pool environments where threads are reused.
    */
   public void cleanup() {
      if (localStore != null) {
         localStore.remove();
      }
   }

   /**
    * Clears all global overrides.
    *
    * <p>
    * After calling this method, all properties will fall back to resolver values
    * (or per-thread overrides if they exist).
    *
    * @return This object for method chaining.
    * @see #setGlobal(String, String)
    * @see #unsetGlobal(String)
    */
   public Settings clearGlobal() {
      globalStore.orElseThrow(()->isex(MSG_globalDisabled)).clear();
      return this;
   }

   /**
    * Converts a string to the specified type using reflection to find conversion methods or constructors.
    *
    * <p>
    * This method attempts to convert a string to the specified type using the following lookup order:
    * <ol>
    *    <li>Custom type functions registered via {@link Builder#addTypeFunction(Class, Function)}</li>
    *    <li>Special handling for {@link String} (returns the string as-is)</li>
    *    <li>Special handling for {@link Enum} types (uses {@link Enum#valueOf(Class, String)})</li>
    *    <li>Reflection lookup for static methods with signature <c>public static &lt;T&gt; T anyName(String arg)</c>
    *       on the target class</li>
    *    <li>Reflection lookup for static methods on the superclass (for abstract classes like {@link Charset}
    *       where concrete implementations need to use the abstract class's static method)</li>
    *    <li>Reflection lookup for public constructors with signature <c>public T(String arg)</c></li>
    * </ol>
    *
    * <p>
    * When a conversion method or constructor is found via reflection, it is cached in the
    * <c>toTypeFunctions</c> map for future use.
    *
    * <h4 class='section'>Examples:</h4>
    * <ul class='spaced-list'>
    *    <li><c>Boolean</c> - Uses <c>Boolean.valueOf(String)</c> static method
    *    <li><c>Integer</c> - Uses <c>Integer.valueOf(String)</c> static method
    *    <li><c>Charset</c> - Uses <c>Charset.forName(String)</c> static method (even for concrete implementations)
    *    <li><c>File</c> - Uses <c>File(String)</c> constructor
    * </ul>
    *
    * @param <T> The target type.
    * @param s The string to convert. Must not be <jk>null</jk>.
    * @param c The target class. Must not be <jk>null</jk>.
    * @return The converted value.
    * @throws RuntimeException If the type is not supported for conversion (no static method or constructor found).
    */
   @SuppressWarnings({
      "rawtypes" // Raw types necessary for generic type handling
   })
   public <T> T toType(String s, Class<T> c) {
      reqnn("s", s);
      reqnn("c", c);
      var f = (Function<String,T>)toTypeFunctions.get(c);
      if (f == null) {
         if (c == String.class)
            return (T)s;
         if (c.isEnum())
            return (T)Enum.valueOf((Class<? extends Enum>)c, s);
         ClassInfoTyped<T> ci = info(c);
         f = ci.getDeclaredMethod(x -> x.isStatic() && x.hasParameterTypes(String.class) && x.hasReturnType(c) && FROM_STRING_METHOD_NAMES.contains(x.getName())).map(x -> (Function<String,T>)s2 -> x.invoke(null, s2)).orElse(null);
         // Also accept `static T parse(CharSequence)` etc. — common for java.time types (Instant,
         // LocalDate, Duration) whose static factories declare the wider CharSequence parameter.
         if (f == null)
            f = ci.getDeclaredMethod(x -> x.isStatic() && x.hasParameterTypes(CharSequence.class) && x.hasReturnType(c) && FROM_STRING_METHOD_NAMES.contains(x.getName())).map(x -> (Function<String,T>)s2 -> x.invoke(null, s2)).orElse(null);
         if (f == null)
            f = ci.getPublicConstructor(x -> x.hasParameterTypes(String.class)).map(x -> (Function<String,T>)x::newInstance).orElse(null);
         if (f != null)
            toTypeFunctions.putIfAbsent(c, f);
      }
      if (f == null)
         throw rex("Invalid env type: %s", c);
      return f.apply(s);
   }
}