/*
 * 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.config;

import static org.apache.juneau.commons.function.Suppliers.*;
import static org.apache.juneau.commons.utils.CollectionUtils.*;
import static org.apache.juneau.commons.utils.IoUtils.*;
import static org.apache.juneau.commons.utils.ObjectUtils.*;
import static org.apache.juneau.commons.utils.Shorts.*;
import static org.apache.juneau.commons.utils.StringUtils.*;
import static org.apache.juneau.commons.utils.StringUtils.isEmpty;
import static org.apache.juneau.commons.utils.SystemUtils.*;
import static org.apache.juneau.commons.utils.ThrowableUtils.*;

import java.io.*;
import java.lang.reflect.*;
import java.util.*;
import java.util.stream.*;

import org.apache.juneau.commons.collections.*;
import org.apache.juneau.commons.function.*;
import org.apache.juneau.commons.svl.*;
import org.apache.juneau.config.event.*;
import org.apache.juneau.config.format.*;
import org.apache.juneau.config.internal.*;
import org.apache.juneau.config.store.*;
import org.apache.juneau.config.vars.*;
import org.apache.juneau.marshall.*;
import org.apache.juneau.marshall.collections.*;
import org.apache.juneau.marshall.json.*;
import org.apache.juneau.marshall.json5.*;
import org.apache.juneau.marshall.parser.*;
import org.apache.juneau.marshall.serializer.*;

/**
 * Main configuration API class.
 *
 * <h2 class='section'>Notes:</h2><ul>
 *    <li class='note'>This class is thread safe and reusable.
 * </ul>
 *
 * <h2 class='section'>See Also:</h2><ul>
 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauConfig">juneau-config</a>
 * </ul>
 */
@SuppressWarnings({
   "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants
   "resource" // ConfigStore and other Closeable fields are owned by the caller; lifecycle managed externally
})
public class Config extends Context implements ConfigEventListener {

   /**
    * Builder class.
    */
   public static class Builder extends Context.Builder<Builder> {

      private BinaryFormat binaryFormat;
      private boolean multiLineValuesOnSeparateLines;
      private boolean readOnly;
      private ConfigStore store;
      private int binaryLineLength;
      private ReaderParser parser;
      private String name;
      private ConfigFormat format;
      private VarResolver varResolver;
      private WriterSerializer serializer;
      private List<String> profiles;

      /**
       * Constructor, default settings.
       */
      protected Builder() {
         binaryFormat = env("Config.binaryFormat", BinaryFormat.BASE64);
         binaryLineLength = env("Config.binaryLineLength", -1);
         multiLineValuesOnSeparateLines = env("Config.multiLineValuesOnSeparateLines", false);
         name = env("Config.name", "Configuration.cfg");
         parser = Json5Parser.DEFAULT;
         readOnly = env("Config.readOnly", false);
         serializer = Json5Serializer.DEFAULT;
         store = FileStore.DEFAULT;
         format = null;
         varResolver = VarResolver.DEFAULT;
         profiles = defaultProfiles();
      }

      /**
       * Resolves the default active profiles from {@code juneau.profiles.active} (system property / env var / config),
       * comma-split and trimmed.  Returns an empty list when unset.
       */
      private static List<String> defaultProfiles() {
         var s = env("juneau.profiles.active", "");
         if (ib(s))
            return list();
         return Arrays.stream(s.split(",")).filter(p -> ! p.isBlank()).map(String::trim).collect(Collectors.toCollection(ArrayList::new));
      }

      /**
       * Copy constructor.
       *
       * @param copyFrom The builder to copy from.
       *    <br>Cannot be <jk>null</jk>.
       */
      protected Builder(Builder copyFrom) {
         super(copyFrom);
         binaryFormat = copyFrom.binaryFormat;
         binaryLineLength = copyFrom.binaryLineLength;
         multiLineValuesOnSeparateLines = copyFrom.multiLineValuesOnSeparateLines;
         name = copyFrom.name;
         format = copyFrom.format;
         parser = copyFrom.parser;
         readOnly = copyFrom.readOnly;
         serializer = copyFrom.serializer;
         store = copyFrom.store;
         varResolver = copyFrom.varResolver;
         profiles = copyFrom.profiles == null ? list() : new ArrayList<>(copyFrom.profiles);
      }

      /**
       * Copy constructor.
       *
       * @param copyFrom The bean to copy from.
       *    <br>Cannot be <jk>null</jk>.
       */
      protected Builder(Config copyFrom) {
         super(copyFrom);
         binaryFormat = copyFrom.binaryFormat;
         binaryLineLength = copyFrom.binaryLineLength;
         multiLineValuesOnSeparateLines = copyFrom.multiLineValuesOnSeparateLines;
         name = copyFrom.name;
         format = copyFrom.format;
         parser = copyFrom.parser;
         readOnly = copyFrom.readOnly;
         serializer = copyFrom.serializer;
         store = copyFrom.store;
         varResolver = copyFrom.varResolver;
      }

      /**
       * Binary value format.
       *
       * <p>
       * The format to use when persisting byte arrays.
       *
       * <ul class='values'>
       *    <li>{@link BinaryFormat#BASE64} - BASE64-encoded string.
       *    <li>{@link BinaryFormat#HEX} - Hexadecimal.
       *    <li>{@link BinaryFormat#SPACED_HEX} - Hexadecimal with spaces between bytes.
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>The default is the first value found:
       *    <ul>
       *       <li>System property <js>"Config.binaryFormat"</js>
       *       <li>Environment variable <js>"CONFIG_BINARYFORMAT"</js>
       *       <li>{@link BinaryFormat#BASE64}
       *    </ul>
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       */
      public Builder binaryFormat(BinaryFormat value) {
         binaryFormat = reqnn("value", value);
         return this;
      }

      /**
       * Binary value line length.
       *
       * <p>
       * When serializing binary values, lines will be split after this many characters.
       * <br>Use <c>-1</c> to represent no line splitting.
       *
       * @param value
       *    The new value for this property.
       *    <br>The default is the first value found:
       *    <ul>
       *       <li>System property <js>"Config.binaryLineLength"</js>
       *       <li>Environment variable <js>"CONFIG_BINARYLINELENGTH"</js>
       *       <li><c>-1</c>
       *    </ul>
       * @return This object.
       */
      public Builder binaryLineLength(int value) {
         binaryLineLength = value;
         return this;
      }

      @Override /* Overridden from Context.Builder<?> */
      public Config build() {
         return build(Config.class);
      }

      @Override /* Overridden from Context.Builder<?> */
      public Builder copy() {
         return new Builder(this);
      }

      /**
       * Configuration store.
       *
       * <p>
       * Convenience method for calling <code>store(ConfigMemoryStore.<jsf>DEFAULT</jsf>)</code>.
       *
       * @return This object.
       */
      public Builder memStore() {
         store = MemoryStore.DEFAULT;
         return this;
      }

      /**
       * Multi-line values on separate lines.
       *
       * <p>
       * When enabled, multi-line values will always be placed on a separate line from the key.
       *
       * <p>
       * The default is the first value found:
       *    <ul>
       *       <li>System property <js>"Config.multiLineValuesOnSeparateLine"</js>
       *       <li>Environment variable <js>"CONFIG_MULTILINEVALUESONSEPARATELINE"</js>
       *       <li><jk>false</jk>
       *    </ul>
       *
       * @return This object.
       */
      public Builder multiLineValuesOnSeparateLines() {
         multiLineValuesOnSeparateLines = true;
         return this;
      }

      /**
       * Configuration name.
       *
       * <p>
       * Specifies the configuration name.
       * <br>This is typically the configuration file name, although
       * the name can be anything identifiable by the {@link ConfigStore} used for retrieving and storing the configuration.
       *
       * @param value
       *    The new value for this property.
       *    <br>The default is the first value found:
       *    <ul>
       *       <li>System property <js>"Config.name"</js>
       *       <li>Environment variable <js>"CONFIG_NAME"</js>
       *       <li><js>"Configuration.cfg"</js>
       *    </ul>
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       */
      public Builder name(String value) {
         name = reqnn("value", value);
         return this;
      }

      /**
       * Active configuration profiles.
       *
       * <p>
       * Each active profile {@code P} activates a {@code <name>-P} overlay (e.g. base {@code my.cfg} + profile
       * {@code stage} &rarr; {@code my-stage.cfg}) layered over the base config: profile entries win over base, and
       * for multiple active profiles the <b>last</b> one wins.  YAML bases use {@code <name>-P.yml} overlays the same
       * way.  Overlays are resolved through the configured {@link #store(ConfigStore) store}, so live-reload fires when
       * either the base or an active profile file changes.
       *
       * <p>
       * Defaults to the comma-separated value of {@code juneau.profiles.active} (system property, environment variable
       * &mdash; with relaxed binding &mdash; or config key).  Pass no arguments / an empty array to disable profiles.
       *
       * @param value
       *    The active profile names, in activation order.
       *    <br>May be empty.
       *    <br>Can be <jk>null</jk> (treated as no active profiles).
       * @return This object.
       * @since 10.0.0
       */
      public Builder profiles(String...value) {
         profiles = value == null ? list() : list(value);
         return this;
      }

      /**
       * Configuration format.
       *
       * @param value The format. Can be <jk>null</jk> to auto-detect from the config name extension.
       * @return This object.
       */
      public Builder format(ConfigFormat value) {
         format = value;
         return this;
      }

      /**
       * Sets YAML format.
       *
       * @return This object.
       */
      public Builder yaml() {
         format = YamlConfigFormat.INSTANCE;
         return this;
      }

      /**
       * Sets INI format.
       *
       * @return This object.
       */
      public Builder ini() {
         format = IniConfigFormat.INSTANCE;
         return this;
      }

      /**
       * POJO parser.
       *
       * <p>
       * The parser to use for parsing values to POJOs.
       *
       * @param value
       *    The new value for this property.
       *    <br>The default is {@link JsonParser#DEFAULT}.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       */
      public Builder parser(ReaderParser value) {
         parser = reqnn("value", value);
         return this;
      }

      /**
       * Read-only mode.
       *
       * <p>
       * When enabled, attempts to call any setters on this object will throw an {@link UnsupportedOperationException}.
       *
       * <p>
       *    The default is the first value found:
       *    <ul>
       *       <li>System property <js>"Config.readOnly"</js>
       *       <li>Environment variable <js>"CONFIG_READONLY"</js>
       *       <li><jk>false</jk>
       *    </ul>
       *
       * @return This object.
       */
      public Builder readOnly() {
         readOnly = true;
         return this;
      }

      /**
       * POJO serializer.
       *
       * <p>
       * The serializer to use for serializing POJO values.
       *
       * @param value
       *    The new value for this property.
       *    <br>The default is {@link Json5Serializer#DEFAULT}
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       */
      public Builder serializer(WriterSerializer value) {
         serializer = reqnn("value", value);
         return this;
      }

      /**
       * Configuration store.
       *
       * <p>
       * The configuration store used for retrieving and storing configurations.
       *
       * @param value
       *    The new value for this property.
       *    <br>The default is {@link FileStore#DEFAULT}.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       */
      public Builder store(ConfigStore value) {
         store = reqnn("value", value);
         return this;
      }

      /**
       * SVL variable resolver.
       *
       * <p>
       * The resolver to use for resolving SVL variables.
       *
       * @param value
       *    The new value for this property.
       *    <br>The default is {@link VarResolver#DEFAULT}.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       */
      public Builder varResolver(VarResolver value) {
         varResolver = reqnn("value", value);
         return this;
      }
   }

   // Use set(T)/reset() for testing.
   static final Memoizer<Config> SYSTEM_DEFAULT = memoizer(Config::findSystemDefault);

   /**
    * Creates a new builder for this object.
    *
    * @return A new builder.
    */
   public static Builder create() {
      return new Builder();
   }

   /**
    * Same as {@link #create()} but initializes the builder with the specified config name.
    *
    * @param name
    *    The configuration name.
    *    <br>Must not be <jk>null</jk>.
    * @return A new builder.
    */
   public static Builder create(String name) {
      return new Builder().name(name);
   }

   /**
    * Returns the list of candidate system default configuration file names.
    *
    * <p>
    * If the <js>"juneau.configFile"</js> system property is set, returns a singleton of that value.
    * <br>Otherwise, returns a list consisting of the following values:
    * <ol>
    *    <li>File with same name as jar file but with <js>".cfg"</js> extension.  (e.g. <js>"myjar.cfg"</js>)
    *    <li><js>"juneau.cfg"</js>
    *    <li><js>"default.cfg"</js>
    *    <li><js>"application.cfg"</js>
    *    <li><js>"app.cfg"</js>
    *    <li><js>"settings.cfg"</js>
    *    <li><js>"application.properties"</js>
    * </ol>
    *
    * @return
    *    A list of candidate file names.
    *    <br>The returned list is modifiable.
    *    <br>Each call constructs a new list.
    */
   public static synchronized List<String> getCandidateSystemDefaultConfigNames() {
      var l = listOfType(String.class);

      var s = env("juneau.configFile").orElse(null);
      if (nn(s)) {
         l.add(s);
         return l;
      }

      var cmd = env("sun.java.command", "not_found").split("\\s+")[0];
      if (cmd.endsWith(".jar") && ! co(cmd, "surefirebooter")) { // HTT - not a .jar during tests
         cmd = jarBaseName(cmd);  // Strip path up to last separator and the ".jar" suffix.
         l.add(cmd + ".cfg");
         cmd = stripVersion(cmd);  // Try also without version in jar name.
         l.add(cmd + ".cfg");
      }

      l.add("juneau.cfg");
      l.add("default.cfg");
      l.add("application.cfg");
      l.add("app.cfg");
      l.add("settings.cfg");
      l.add("application.properties");

      return l;
   }

   /**
    * Returns the system default configuration.
    *
    * @return The system default configuration, or <jk>null</jk> if it doesn't exist.
    */
   public static synchronized Config getSystemDefault() { return SYSTEM_DEFAULT.get(); }

   /**
    * Sets a system default configuration.
    *
    * @param systemDefault The new system default configuration.
    */
   public static synchronized void setSystemDefault(Config systemDefault) {
      SYSTEM_DEFAULT.set(systemDefault);
   }

   private static synchronized Config find(String name) {
      if (FileStore.DEFAULT.exists(name)) // HTT - no .cfg files on disk in test environment
         return Config.create(name).store(FileStore.DEFAULT).build();
      if (ClasspathStore.DEFAULT.exists(name)) // HTT - test config files are not on classpath by default
         return Config.create(name).store(ClasspathStore.DEFAULT).build();
      return null;
   }

   private static synchronized Config findSystemDefault() {

      for (var n : getCandidateSystemDefaultConfigNames()) {
         var config = find(n);
         if (nn(config)) // HTT - find() always returns null in test environment
            return config; // HTT
      }

      return null;
   }

   private static boolean isSimpleType(Type t) {
      if (! (t instanceof Class))
         return false;
      var c = (Class<?>)t;
      return (c == String.class || c.isPrimitive() || c.isAssignableFrom(Number.class) || c == Boolean.class || c.isEnum());
   }
   private static ConfigFormat detectFormat(String name) {
      var n = emptyIfNull(name).toLowerCase(Locale.ROOT);
      if (n.endsWith(".yaml") || n.endsWith(".yml"))
         return YamlConfigFormat.INSTANCE;
      return IniConfigFormat.INSTANCE;
   }
   // Plain string ops instead of regex: avoids stack-overflow (S5998) and super-linear backtracking (S8786).
   static String jarBaseName(String cmd) {
      var base = cmd.substring(Math.max(cmd.lastIndexOf('/'), cmd.lastIndexOf('\\')) + 1);
      return base.length() > 4 ? base.substring(0, base.length() - 4) : cmd;
   }

   static String stripVersion(String cmd) {
      var i = Math.min(nonNeg(cmd.indexOf('.')), nonNeg(cmd.indexOf('_')));
      return i == Integer.MAX_VALUE ? cmd : cmd.substring(0, i);
   }

   private static int nonNeg(int i) {
      return i < 0 ? Integer.MAX_VALUE : i;
   }

   private static String section(String section) {
      reqnn("section", section);
      if (isEmpty(section))
         return "";
      return section;
   }
   private static String skey(String key) {
      var i = key.lastIndexOf('/');
      if (i == -1)
         return key;
      return key.substring(i + 1);
   }
   private static String sname(String key) {
      reqnn("key", key);
      var i = key.lastIndexOf('/');
      if (i == -1)
         return "";
      return key.substring(0, i);
   }

   protected final boolean multiLineValuesOnSeparateLines;
   protected final boolean readOnly;
   protected final int binaryLineLength;
   protected final BinaryFormat binaryFormat;
   protected final MarshallingSession marshallingSession;
   protected final ConfigStore store;
   protected final ReaderParser parser;
   protected final String name;
   protected final ConfigFormat format;
   protected final VarResolver varResolver;
   protected final VarResolverSession varSession;
   protected final WriterSerializer serializer;

   private final ConfigMap configMap;
   private final List<ConfigEventListener> listeners = synced(ll());

   /**
    * Constructor.
    *
    * @param builder The builder for this object.
    *    <br>Cannot be <jk>null</jk>.
    * @throws IOException Thrown by underlying stream.
    */
   public Config(Builder builder) throws IOException {
      super(builder);

      binaryFormat = builder.binaryFormat;
      binaryLineLength = builder.binaryLineLength;
      multiLineValuesOnSeparateLines = builder.multiLineValuesOnSeparateLines;
      name = builder.name;
      format = builder.format == null ? detectFormat(name) : builder.format;
      parser = builder.parser;
      readOnly = builder.readOnly;
      serializer = builder.serializer;
      // When profiles are active, wrap the configured store so reads of the base name return the base config
      // with each active profile's <name>-<profile> overlay merged on top (profile-wins, last-active-wins).
      var profiles2 = builder.profiles == null ? Collections.<String>emptyList() : builder.profiles;
      store = profiles2.isEmpty()
         ? builder.store
         : ProfileConfigStore.create().delegate(builder.store).baseName(name).profiles(profiles2).format(format).build();
      varResolver = builder.varResolver;
      configMap = store.getMap(name, format);
      configMap.register(this);
      marshallingSession = parser.getMarshallingContext().getSession();
      varSession = varResolver.copy().vars(ConfigVar.class).bean(Config.class, this).build().createSession();
   }

   Config(Config copyFrom, VarResolverSession varSession) {
      super(copyFrom);
      marshallingSession = copyFrom.marshallingSession;
      binaryFormat = copyFrom.binaryFormat;
      binaryLineLength = copyFrom.binaryLineLength;
      configMap = copyFrom.configMap;
      configMap.register(this);
      multiLineValuesOnSeparateLines = copyFrom.multiLineValuesOnSeparateLines;
      name = copyFrom.name;
      format = copyFrom.format;
      parser = copyFrom.parser;
      readOnly = copyFrom.readOnly;
      serializer = copyFrom.serializer;
      store = copyFrom.store;
      this.varSession = varSession;
      varResolver = copyFrom.varResolver;
   }

   /**
    * Add a listener to this config to react to modification events.
    *
    * <p>
    * Listeners should be removed using {@link #removeListener(ConfigEventListener)}.
    *
    * @param listener The new listener to add.
    * @return This object.
    */
   public synchronized Config addListener(ConfigEventListener listener) {
      listeners.add(listener);
      return this;
   }

   /**
    * Closes this configuration object by unregistering it from the underlying config map.
    */
   public void close() {
      configMap.unregister(this);
   }

   /**
    * Commit the changes in this config to the store.
    *
    * @return This object.
    * @throws IOException Thrown by underlying stream.
    * @throws UnsupportedOperationException If configuration is read only.
    */
   public Config commit() throws IOException {
      checkWrite();
      configMap.commit();
      return this;
   }

   @Override /* Overridden from Context */
   public Builder copy() {
      return new Builder(this);
   }

   /**
    * Returns <jk>true</jk> if this section contains the specified key and the key has a non-blank value.
    *
    * @param key
    *    The key.
    *    <br>Must not be <jk>null</jk>.
    * @return <jk>true</jk> if this section contains the specified key and the key has a non-blank value.
    */
   public boolean exists(String key) {
      return ine(get(key).as(String.class).orElse(null));
   }

   /**
    * Gets the entry with the specified key.
    *
    * <p>
    * The key can be in one of the following formats...
    * <ul class='spaced-list'>
    *    <li>
    *       <js>"key"</js> - A value in the default section (i.e. defined above any <c>[section]</c> header).
    *    <li>
    *       <js>"section/key"</js> - A value from the specified section.
    * </ul>
    *
    * <p>
    * If entry does not exist, returns an empty {@link Entry} object.
    *
    * @param key
    *    The key.
    *    <br>Must not be <jk>null</jk>.
    * @return The entry bean, never <jk>null</jk>.
    */
   public Entry get(String key) {
      return new Entry(this, configMap, sname(key), skey(key));
   }

   /**
    * Returns the keys of the entries in the specified section.
    *
    * @param section
    *    The section name to write from.
    *    <br>If empty, refers to the default section.
    *    <br>Must not be <jk>null</jk>.
    * @return
    *    An unmodifiable set of keys, or an empty set if the section doesn't exist.
    */
   public Set<String> getKeys(String section) {
      return configMap.getKeys(section(section));
   }

   /**
    * Returns the name associated with this config (usually a file name).
    *
    * @return The name associated with this config, or <jk>null</jk> if it has no name.
    */
   public String getName() { return name; }

   /**
    * Gets the section with the specified name.
    *
    * <p>
    * If section does not exist, returns an empty {@link Section} object.
    *
    * @param name The section name.  <jk>null</jk> and blank refer to the default section.
    * @return The section bean, never <jk>null</jk>.
    */
   public Section getSection(String name) {
      return new Section(this, configMap, emptyIfNull(name));
   }

   /**
    * Returns the section names defined in this config.
    *
    * @return The section names defined in this config.
    */
   public Set<String> getSectionNames() { return u(configMap.getSections()); }

   /**
    * Gets the entry with the specified key.
    *
    * <p>
    * The key can be in one of the following formats...
    * <ul class='spaced-list'>
    *    <li>
    *       <js>"key"</js> - A value in the default section (i.e. defined above any <c>[section]</c> header).
    *    <li>
    *       <js>"section/key"</js> - A value from the specified section.
    * </ul>
    *
    * <p>
    * If entry does not exist, returns <jk>null</jk>.
    *
    * <h4 class='section'>Notes:</h4><ul>
    *    <li class='note'>This method is equivalent to calling <c>get(<jv>key</jv>).orElse(<jk>null</jk>);</c>.
    * </ul>
    *
    * @param key
    *    The key.
    *    <br>Must not be <jk>null</jk>.
    * @return The entry value, or <jk>null</jk> if it doesn't exist.
    */
   public String getString(String key) {
      return new Entry(this, configMap, sname(key), skey(key)).orElse(null);
   }

   /**
    * Loads the contents of the specified map of maps into this config.
    *
    * @param m
    *    The maps to load.
    *    <br>Can be <jk>null</jk> (no-op).
    * @return This object.
    * @throws SerializeException Value could not be serialized.
    */
   public Config load(Map<String,Map<String,Object>> m) throws SerializeException {
      if (nn(m))
         for (var e : m.entrySet()) {
            setSection(e.getKey(), null, e.getValue());
         }
      return this;
   }

   /**
    * Overwrites the contents of the config file.
    *
    * @param contents The new contents of the config file.
    * @param synchronous Wait until the change has been persisted before returning this map.
    * @return This object.
    * @throws IOException Thrown by underlying stream.
    * @throws InterruptedException Thread was interrupted.
    * @throws UnsupportedOperationException If configuration is read only.
    */
   public Config load(Reader contents, boolean synchronous) throws IOException, InterruptedException {
      checkWrite();
      configMap.load(read(contents), synchronous);
      return this;
   }

   /**
    * Overwrites the contents of the config file.
    *
    * @param contents The new contents of the config file.
    * @param synchronous Wait until the change has been persisted before returning this map.
    * @return This object.
    * @throws IOException Thrown by underlying stream.
    * @throws InterruptedException Thread was interrupted.
    * @throws UnsupportedOperationException If configuration is read only.
    */
   public Config load(String contents, boolean synchronous) throws IOException, InterruptedException {
      checkWrite();
      configMap.load(contents, synchronous);
      return this;
   }

   @Override /* Overridden from ConfigEventListener */
   public synchronized void onConfigChange(ConfigEvents events) {
      listeners.forEach(x -> x.onConfigChange(events));
   }

   /**
    * Removes an entry with the specified key.
    *
    * @param key
    *    The key.
    *    <br>Must not be <jk>null</jk>.
    * @return This object.
    * @throws UnsupportedOperationException If configuration is read only.
    */
   public Config remove(String key) {
      checkWrite();
      var sname = sname(key);
      var skey = skey(key);
      configMap.removeEntry(sname, skey);
      return this;
   }

   /**
    * Removes the import statement with the specified name from the specified section.
    *
    * @param sectionName
    *    The section name where to place the import statement.
    *    <br>Must not be <jk>null</jk>.
    *    <br>Use blank for the default section.
    * @param importName
    *    The import name.
    *    <br>Must not be <jk>null</jk>.
    * @return This object.
    * @throws UnsupportedOperationException If configuration is read only.
    */
   public Config removeImport(String sectionName, String importName) {
      checkWrite();
      configMap.removeImport(section(sectionName), importName);
      return this;
   }

   /**
    * Removes a listener from this config.
    *
    * @param listener The listener to remove.
    * @return This object.
    */
   public synchronized Config removeListener(ConfigEventListener listener) {
      listeners.remove(listener);
      return this;
   }

   /**
    * Removes the section with the specified name.
    *
    * @param name The name of the section to remove
    * @return This object.
    * @throws UnsupportedOperationException If configuration is read only.
    */
   public Config removeSection(String name) {
      checkWrite();
      configMap.removeSection(name);
      return this;
   }

   /**
    * Creates a copy of this config using the specified var session for resolving variables.
    *
    * <p>
    * This creates a shallow copy of the config but replacing the variable resolver.
    *
    * @param varSession The var session used for resolving string variables.
    * @return A new config object.
    */
   public Config resolving(VarResolverSession varSession) {
      return new Config(this, varSession);
   }

   /**
    * Does a rollback of any changes on this config currently in memory.
    *
    * @return This object.
    * @throws UnsupportedOperationException If configuration is read only.
    */
   public Config rollback() {
      checkWrite();
      configMap.rollback();
      return this;
   }

   /**
    * Returns a fluent builder for adding or updating the entry with the specified key.
    *
    * <p>
    * This is an ergonomic, self-documenting alternative to the
    * {@link #set(String, Object, Serializer, String, List)} overload.  Rather than overloading a single call
    * with several "leave-unchanged versus clear" sentinel conventions, each facet is expressed explicitly:
    * <ul>
    *    <li><b>Not calling</b> a facet method leaves that facet untouched.
    *    <li>An explicit setter ({@link EntryBuilder#comment(String)}, {@link EntryBuilder#preLines(List)},
    *       {@link EntryBuilder#serializer(Serializer)}) sets that facet.
    *    <li>An explicit clear ({@link EntryBuilder#clearComment()}, {@link EntryBuilder#clearPreLines()}) clears that facet.
    * </ul>
    *
    * <h4 class='section'>Example:</h4>
    * <p class='bjava'>
    *    <jv>config</jv>.entry(<js>"MySection/myKey"</js>)
    *       .comment(<js>"My comment"</js>)
    *       .preLines(List.<jsm>of</jsm>(<js>"# A pre-line"</js>))
    *       .set(<js>"My value"</js>);
    * </p>
    *
    * @param key
    *    The key.
    *    <br>Must not be <jk>null</jk>.
    * @return A new fluent entry builder, never <jk>null</jk>.
    */
   public EntryBuilder entry(String key) {
      return new EntryBuilder(this, key);
   }

   /**
    * Adds or replaces an entry with the specified key with a POJO serialized to a string using the registered
    * serializer.
    *
    * <p>
    * Equivalent to calling <c>put(key, value, isEncoded(key))</c>.
    *
    * @param key
    *    The key.
    *    <br>Must not be <jk>null</jk>.
    * @param value The new value POJO.
    * @return This object.
    * @throws SerializeException
    *    If serializer could not serialize the value or if a serializer is not registered with this config file.
    * @throws UnsupportedOperationException If configuration is read only.
    */
   public Config set(String key, Object value) throws SerializeException {
      return set(key, value, null);
   }

   /**
    * Same as {@link #set(String, Object)} but allows you to specify the serializer to use to serialize the
    * value.
    *
    * @param key
    *    The key.
    *    <br>Must not be <jk>null</jk>.
    * @param value The new value.
    * @param serializer
    *    The serializer to use for serializing the object.
    *    If <jk>null</jk>, then uses the predefined serializer on the config file.
    * @return This object.
    * @throws SerializeException
    *    If serializer could not serialize the value or if a serializer is not registered with this config file.
    * @throws UnsupportedOperationException If configuration is read only.
    */
   public Config set(String key, Object value, Serializer serializer) throws SerializeException {
      return set(key, serialize(value, serializer));
   }

   /**
    * Same as {@link #set(String, Object)} but allows you to specify all aspects of a value.
    *
    * @param key
    *    The key.
    *    <br>Must not be <jk>null</jk>.
    * @param value The new value.
    * @param serializer
    *    The serializer to use for serializing the object.
    *    If <jk>null</jk>, then uses the predefined serializer on the config file.
    * @param comment
    *    Optional same-line comment to add to this value.
    *    <br>If <jk>null</jk>, then previous value will not be replaced.
    * @param preLines
    *    Optional comment or blank lines to add before this entry.
    *    <br>If <jk>null</jk>, then previous value will not be replaced.
    * @return This object.
    * @throws SerializeException
    *    If serializer could not serialize the value or if a serializer is not registered with this config file.
    * @throws UnsupportedOperationException If configuration is read only.
    */
   public Config set(String key, Object value, Serializer serializer, String comment, List<String> preLines) throws SerializeException {
      checkWrite();
      reqnn("key", key);
      var sname = sname(key);
      var skey = skey(key);

      configMap.setEntry(sname, skey, serialize(value, serializer), comment, preLines);
      return this;
   }

   /**
    * Sets a value in this config.
    *
    * @param key
    *    The key.
    *    <br>Must not be <jk>null</jk>.
    * @param value
    *    The value.
    *    <br>Can be <jk>null</jk> (no-op if the entry does not already exist).
    * @return This object.
    * @throws UnsupportedOperationException If configuration is read only.
    */
   public Config set(String key, String value) {
      checkWrite();
      reqnn("key", key);
      var sname = sname(key);
      var skey = skey(key);

      var ce = configMap.getEntry(sname, skey);
      if (ce == null && value == null)
         return this;

      configMap.setEntry(sname, skey, s(value), null, null);
      return this;
   }

   /**
    * Creates the specified import statement if it doesn't exist.
    *
    * @param sectionName
    *    The section name where to place the import statement.
    *    <br>Must not be <jk>null</jk>.
    *    <br>Use blank for the default section.
    * @param importName
    *    The import name.
    *    <br>Must not be <jk>null</jk>.
    * @param preLines
    *    Optional comment and blank lines to add immediately before the import statement.
    *    <br>If <jk>null</jk>, previous pre-lines will not be replaced.
    * @return This object.
    * @throws UnsupportedOperationException If configuration is read only.
    */
   public Config setImport(String sectionName, String importName, List<String> preLines) {
      checkWrite();
      configMap.setImport(section(sectionName), importName, preLines);
      return this;
   }

   /**
    * Creates the specified section if it doesn't exist.
    *
    * <p>
    * Returns the existing section if it already exists.
    *
    * @param name
    *    The section name.
    *    <br>Must not be <jk>null</jk>.
    *    <br>Use blank for the default section.
    * @param preLines
    *    Optional comment and blank lines to add immediately before the section.
    *    <br>If <jk>null</jk>, previous pre-lines will not be replaced.
    * @return This object.
    * @throws UnsupportedOperationException If configuration is read only.
    */
   public Config setSection(String name, List<String> preLines) {
      try {
         return setSection(section(name), preLines, null);
      } catch (SerializeException e) {
         throw toRex(e);  // HTT - setSection with null contents cannot throw SerializeException
      }
   }

   /**
    * Creates the specified section if it doesn't exist.
    *
    * @param name
    *    The section name.
    *    <br>Must not be <jk>null</jk>.
    *    <br>Use blank for the default section.
    * @param preLines
    *    Optional comment and blank lines to add immediately before the section.
    *    <br>If <jk>null</jk>, previous pre-lines will not be replaced.
    * @param contents
    *    Values to set in the new section.
    *    <br>Can be <jk>null</jk> (no additional values are set).
    * @return This object.
    * @throws SerializeException Contents could not be serialized.
    * @throws UnsupportedOperationException If configuration is read only.
    */
   public Config setSection(String name, List<String> preLines, Map<String,Object> contents) throws SerializeException {
      checkWrite();
      configMap.setSection(section(name), preLines);

      if (nn(contents))
         for (var e : contents.entrySet())
            set(section(name) + '/' + e.getKey(), e.getValue());

      return this;
   }

   /**
    * Takes the settings defined in this configuration and sets them as system properties.
    *
    * <p>
    * This is never called automatically; applications that want their config entries published as JVM-wide
    * system properties must call it explicitly.
    *
    * @return This object.
    */
   public Config setSystemProperties() {
      for (var section : getSectionNames()) {
         for (var key : getKeys(section)) {
            var k = (section.isEmpty() ? key : section + '/' + key);
            // Intentional real-JVM-property export: this method's documented contract is to publish config
            // entries as process-global system properties so external/third-party code (which reads raw
            // System.getProperty) can observe them.  Routing through Settings would break that contract, so
            // the mutation is kept deliberately.
            System.setProperty(k, getRaw(k));
         }
      }
      return this;
   }

   /**
    * Returns the contents of this config as a simple map.
    *
    * @return The contents of this config as a simple map.
    */
   public JsonMap toMap() {
      return configMap.asMap();
   }

   @Override /* Overridden from Context */
   protected FluentMap<String,Object> properties() {
      // HTT - Config.toString() is overridden to return configMap.toString(), so this method is never called in practice
      return super.properties()
         .a("binaryFormat", binaryFormat)
         .a("binaryLineLength", binaryLineLength)
         .a("multiLineValuesOnSeparateLines", multiLineValuesOnSeparateLines)
         .a("format", format == null ? null : format.id())
         .a("name", name)
         .a("parser", parser)
         .a("readOnly", readOnly)
         .a("serializer", serializer)
         .a("store", store)
         .a("varResolver", varResolver);
   }

   @Override /* Overridden from Object */
   public String toString() {
      return configMap.toString();
   }

   /**
    * Saves this config file to the specified writer using this config's {@link ConfigFormat} (INI, YAML, etc.).
    *
    * @param w
    *    The writer to send the output to.
    *    <br>Must not be <jk>null</jk>.
    *    <br>The writer is not closed by this method.
    * @return The same writer passed in.
    * @throws IOException If a problem occurred trying to send contents to the writer.
    */
   public Writer writeTo(Writer w) throws IOException {
      return configMap.writeTo(w);
   }

   /**
    * Returns the specified value as a string from the config file.
    *
    * <p>
    * Unlike {@link #getString(String)}, this method doesn't replace SVL variables.
    *
    * <p>
    * Values read through the other getters are resolved against the configured {@link VarResolver}, so a value that
    * can be written by an untrusted party can pull in environment variables, system properties and other
    * resolver content.  Escape untrusted text before storing it in a config entry, or read it with this method.
    *
    * @param key The key.
    * @return The value, or <jk>null</jk> if the section or value doesn't exist.
    */
   public String getRaw(String key) {

      var sname = sname(key);
      var skey = skey(key);

      var ce = configMap.getEntry(sname, skey);

      return ce == null ? null : ce.getValue();
   }

   private String nlIfMl(CharSequence cs) {
      var s = cs.toString();
      if (s.indexOf('\n') != -1 && multiLineValuesOnSeparateLines)
         return "\n" + s;
      return s;
   }

   @SuppressWarnings({
      "java:S3776" // Cognitive complexity acceptable for config value serialization
   })
   private String serialize(Object value, Serializer serializer) throws SerializeException {
      if (value == null)
         return "";
      if (serializer == null)
         serializer = this.serializer;
      var c = value.getClass();
      if (value instanceof CharSequence value2)
         return nlIfMl(value2);
      if (isSimpleType(c))
         return value.toString();

      if (value instanceof byte[] b) {
         String s = null;
         if (binaryFormat == BinaryFormat.HEX)
            s = toHex(b);
         else if (binaryFormat == BinaryFormat.SPACED_HEX)
            s = toSpacedHex(b);
         else
            s = base64Encode(b);
         var l = binaryLineLength;
         if (l <= 0 || s.length() <= l)
            return s;
         var sb = new StringBuilder();
         for (var i = 0; i < s.length(); i += l)
            sb.append(binaryLineLength > 0 ? "\n" : "").append(s.substring(i, Math.min(s.length(), i + l)));
         return sb.toString();
      }

      String r = null;
      if (multiLineValuesOnSeparateLines)
         r = "\n" + (String)serializer.write(value);
      else
         r = (String)serializer.write(value);

      if (r.startsWith("'"))
         return r.substring(1, r.length() - 1);
      return r;
   }

   void checkWrite() {
      if (readOnly)
         throw uoex("Cannot call this method on a read-only configuration.");
   }

   ConfigMap getConfigMap() { return configMap; }

   List<ConfigEventListener> getListeners() { return u(listeners); }

}