juneau-core/juneau-config/src/main/java/org/apache/juneau/config/Config.java

// ***************************************************************************************************************************
// * 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.common.internal.ArgUtils.*;
import static org.apache.juneau.common.internal.IOUtils.*;
import static org.apache.juneau.common.internal.StringUtils.*;
import static org.apache.juneau.common.internal.ThrowableUtils.*;
import static org.apache.juneau.internal.CollectionUtils.*;

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

import org.apache.juneau.*;
import org.apache.juneau.collections.*;
import org.apache.juneau.config.event.*;
import org.apache.juneau.config.internal.*;
import org.apache.juneau.config.mod.*;
import org.apache.juneau.config.store.*;
import org.apache.juneau.config.vars.*;
import org.apache.juneau.internal.*;
import org.apache.juneau.json.*;
import org.apache.juneau.parser.*;
import org.apache.juneau.serializer.*;
import org.apache.juneau.svl.*;
import org.apache.juneau.utils.*;

/**
 * Main configuration API class.
 *
 * <h5 class='section'>Notes:</h5><ul>
 * 	<li class='note'>This class is thread safe and reusable.
 * </ul>
 *
 * <h5 class='section'>See Also:</h5><ul>
 * 	<li class='link'><a class="doclink" href="../../../../index.html#juneau-config">Overview &gt; juneau-config</a>
 * </ul>
 */
public final class Config extends Context implements ConfigEventListener {

	//-----------------------------------------------------------------------------------------------------------------
	// Static
	//-----------------------------------------------------------------------------------------------------------------

	private static boolean DISABLE_AUTO_SYSTEM_PROPS = Boolean.getBoolean("juneau.disableAutoSystemProps");
	private static volatile Config SYSTEM_DEFAULT = findSystemDefault();

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

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

	private synchronized static Config findSystemDefault() {

		for (String n : getCandidateSystemDefaultConfigNames()) {
			Config config = find(n);
			if (config != null) {
				if (! DISABLE_AUTO_SYSTEM_PROPS)
					config.setSystemProperties();
				return config;
			}
		}

		return null;
	}

	/**
	 * 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>Any file ending in <js>".cfg"</js> in the home directory (names ordered alphabetically).
	 * 	<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>
	 * <p>
	 *
	 * @return
	 * 	A list of candidate file names.
	 * 	<br>The returned list is modifiable.
	 * 	<br>Each call constructs a new list.
	 */
	public synchronized static List<String> getCandidateSystemDefaultConfigNames() {
		List<String> l = list();

		String s = System.getProperty("juneau.configFile");
		if (s != null) {
			l.add(s);
			return l;
		}

		String cmd = System.getProperty("sun.java.command", "not_found").split("\\s+")[0];
		if (cmd.endsWith(".jar") && ! cmd.contains("surefirebooter")) {
			cmd = cmd.replaceAll(".*?([^\\\\\\/]+)\\.jar$", "$1");
			l.add(cmd + ".cfg");
			cmd = cmd.replaceAll("[\\.\\_].*$", "");  // Try also without version in jar name.
			l.add(cmd + ".cfg");
		}

		Set<File> files = sortedSet(new File(".").listFiles());
		for (File f : files)
			if (f.getName().endsWith(".cfg"))
				l.add(f.getName());

		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;
	}

	private synchronized static Config find(String name) {
		if (name == null)
			return null;
		if (FileStore.DEFAULT.exists(name))
			return Config.create(name).store(FileStore.DEFAULT).build();
		if (ClasspathStore.DEFAULT.exists(name))
			return Config.create(name).store(ClasspathStore.DEFAULT).build();
		return null;
	}

	/**
	 * 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.
	 * @return A new builder.
	 */
	public static Builder create(String name) {
		return new Builder().name(name);
	}

	//-------------------------------------------------------------------------------------------------------------------
	// Builder
	//-------------------------------------------------------------------------------------------------------------------

	/**
	 * Builder class.
	 */
	@FluentSetters
	public static class Builder extends Context.Builder {

		String name;
		ConfigStore store;
		WriterSerializer serializer;
		ReaderParser parser;
		Map<Character,Mod> mods;
		VarResolver varResolver;
		int binaryLineLength;
		BinaryFormat binaryFormat;
		boolean multiLineValuesOnSeparateLines, readOnly;

		/**
		 * Constructor, default settings.
		 */
		protected Builder() {
			super();
			name = env("Config.name", "Configuration.cfg");
			store = FileStore.DEFAULT;
			serializer = Json5Serializer.DEFAULT;
			parser = JsonParser.DEFAULT;
			mods = map();
			mods(XorEncodeMod.INSTANCE);
			varResolver = VarResolver.DEFAULT;
			binaryLineLength = env("Config.binaryLineLength", -1);
			binaryFormat = env("Config.binaryFormat", BinaryFormat.BASE64);
			multiLineValuesOnSeparateLines = env("Config.multiLineValuesOnSeparateLines", false);
			readOnly = env("Config.readOnly", false);
		}

		/**
		 * Copy constructor.
		 *
		 * @param copyFrom The bean to copy from.
		 */
		protected Builder(Config copyFrom) {
			super(copyFrom);
			name = copyFrom.name;
			store = copyFrom.store;
			serializer = copyFrom.serializer;
			parser = copyFrom.parser;
			mods = copyOf(copyFrom.mods);
			varResolver = copyFrom.varResolver;
			binaryLineLength = copyFrom.binaryLineLength;
			binaryFormat = copyFrom.binaryFormat;
			multiLineValuesOnSeparateLines = copyFrom.multiLineValuesOnSeparateLines;
			readOnly = copyFrom.readOnly;
		}

		/**
		 * Copy constructor.
		 *
		 * @param copyFrom The builder to copy from.
		 */
		protected Builder(Builder copyFrom) {
			super(copyFrom);
			name = copyFrom.name;
			store = copyFrom.store;
			serializer = copyFrom.serializer;
			parser = copyFrom.parser;
			mods = copyOf(copyFrom.mods);
			varResolver = copyFrom.varResolver;
			binaryLineLength = copyFrom.binaryLineLength;
			binaryFormat = copyFrom.binaryFormat;
			multiLineValuesOnSeparateLines = copyFrom.multiLineValuesOnSeparateLines;
			readOnly = copyFrom.readOnly;
		}

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

		@Override /* Context.Builder */
		public Config build() {
			return build(Config.class);
		}

		//-----------------------------------------------------------------------------------------------------------------
		// Properties
		//-----------------------------------------------------------------------------------------------------------------

		/**
		 * 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"
		 * 		<li>Environment variable <js>"CONFIG_NAME"
		 * 		<li><js>"Configuration.cfg"</js>
		 * 	</ul>
		 * @return This object.
		 */
		public Builder name(String value) {
			name = 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}.
		 * @return This object.
		 */
		public Builder store(ConfigStore value) {
			store = value;
			return 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;
		}

		/**
		 * 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}
		 * @return This object.
		 */
		public Builder serializer(WriterSerializer value) {
			serializer = value;
			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}.
		 * @return This object.
		 */
		public Builder parser(ReaderParser value) {
			parser = value;
			return this;
		}

		/**
		 * Adds a value modifier.
		 *
		 * <p>
		 * Modifiers are used to modify entry value before being persisted.
		 *
		 * @param values
		 * 	The mods to apply to this config.
		 * @return This object.
		 */
		public Builder mods(Mod...values) {
			for (Mod value : values)
				mods.put(value.getId(), 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}.
		 * @return This object.
		 */
		public Builder varResolver(VarResolver value) {
			varResolver = 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"
		 * 		<li>Environment variable <js>"CONFIG_BINARYLINELENGTH"
		 * 		<li><c>-1</c>
		 * 	</ul>
		 * @return This object.
		 */
		public Builder binaryLineLength(int value) {
			binaryLineLength = value;
			return this;
		}

		/**
		 * 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"
		 * 		<li>Environment variable <js>"CONFIG_BINARYFORMAT"
		 * 		<li>{@link BinaryFormat#BASE64}
		 * 	</ul>
		 * @return This object.
		 */
		public Builder binaryFormat(BinaryFormat value) {
			binaryFormat = value;
			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"
		 * 		<li>Environment variable <js>"CONFIG_MULTILINEVALUESONSEPARATELINE"
		 * 		<li><jk>false</jk>
		 * 	</ul>
		 *
		 * @return This object.
		 */
		public Builder multiLineValuesOnSeparateLines() {
			multiLineValuesOnSeparateLines = true;
			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"
		 * 		<li>Environment variable <js>"CONFIG_READONLY"
		 * 		<li><jk>false</jk>
		 * 	</ul>
		 *
		 * @return This object.
		 */
		public Builder readOnly() {
			readOnly = true;
			return this;
		}

		// <FluentSetters>

		@Override /* GENERATED - org.apache.juneau.Context.Builder */
		public Builder annotations(Annotation...values) {
			super.annotations(values);
			return this;
		}

		@Override /* GENERATED - org.apache.juneau.Context.Builder */
		public Builder apply(AnnotationWorkList work) {
			super.apply(work);
			return this;
		}

		@Override /* GENERATED - org.apache.juneau.Context.Builder */
		public Builder applyAnnotations(java.lang.Class<?>...fromClasses) {
			super.applyAnnotations(fromClasses);
			return this;
		}

		@Override /* GENERATED - org.apache.juneau.Context.Builder */
		public Builder applyAnnotations(Method...fromMethods) {
			super.applyAnnotations(fromMethods);
			return this;
		}

		@Override /* GENERATED - org.apache.juneau.Context.Builder */
		public Builder cache(Cache<HashKey,? extends org.apache.juneau.Context> value) {
			super.cache(value);
			return this;
		}

		@Override /* GENERATED - org.apache.juneau.Context.Builder */
		public Builder debug() {
			super.debug();
			return this;
		}

		@Override /* GENERATED - org.apache.juneau.Context.Builder */
		public Builder debug(boolean value) {
			super.debug(value);
			return this;
		}

		@Override /* GENERATED - org.apache.juneau.Context.Builder */
		public Builder impl(Context value) {
			super.impl(value);
			return this;
		}

		@Override /* GENERATED - org.apache.juneau.Context.Builder */
		public Builder type(Class<? extends org.apache.juneau.Context> value) {
			super.type(value);
			return this;
		}

		// </FluentSetters>
	}

	//-------------------------------------------------------------------------------------------------------------------
	// Instance
	//-------------------------------------------------------------------------------------------------------------------

	final String name;
	final ConfigStore store;
	final WriterSerializer serializer;
	final ReaderParser parser;
	final Map<Character,Mod> mods;
	final VarResolver varResolver;
	final int binaryLineLength;
	final BinaryFormat binaryFormat;
	final boolean multiLineValuesOnSeparateLines, readOnly;
	final BeanSession beanSession;
	final VarResolverSession varSession;

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


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

	/**
	 * Constructor.
	 *
	 * @param builder The builder for this object.
	 * @throws IOException Thrown by underlying stream.
	 */
	public Config(Builder builder) throws IOException {
		super(builder);

		name = builder.name;
		store = builder.store;
		configMap = store.getMap(name);
		configMap.register(this);
		serializer = builder.serializer;
		parser = builder.parser;
		beanSession = parser.getBeanContext().getSession();
		mods = unmodifiable(copyOf(builder.mods));
		varResolver = builder.varResolver;
		varSession = varResolver
			.copy()
			.vars(ConfigVar.class)
			.bean(Config.class, this)
			.build()
			.createSession();
		binaryLineLength = builder.binaryLineLength;
		binaryFormat = builder.binaryFormat;
		multiLineValuesOnSeparateLines = builder.multiLineValuesOnSeparateLines;
		readOnly = builder.readOnly;
	}

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

	/**
	 * 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);
	}

	/**
	 * 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;
	}

	//-----------------------------------------------------------------------------------------------------------------
	// Workhorse getters
	//-----------------------------------------------------------------------------------------------------------------

	/**
	 * Returns the specified value as a string from the config file.
	 *
	 * <p>
	 * Unlike {@link #getString(String)}, this method doesn't replace SVL variables.
	 *
	 * @param key The key.
	 * @return The value, or <jk>null</jk> if the section or value doesn't exist.
	 */
	private String getRaw(String key) {

		String sname = sname(key);
		String skey = skey(key);

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

		if (ce == null)
			return null;

		return removeMods(ce.getModifiers(), ce.getValue());
	}

	String applyMods(String mods, String x) {
		if (mods != null && x != null)
			for (int i = 0; i < mods.length(); i++)
				x = getMod(mods.charAt(i)).doApply(x);
		return x;
	}

	String removeMods(String mods, String x) {
		if (mods != null && x != null)
			for (int i = mods.length()-1; i > -1; i--)
				x = getMod(mods.charAt(i)).doRemove(x);
		return x;
	}

	Mod getMod(char id) {
		Mod x = mods.get(id);
		return x == null ? Mod.NO_OP : x;
	}

	//-----------------------------------------------------------------------------------------------------------------
	// Utility methods
	//-----------------------------------------------------------------------------------------------------------------

	/**
	 * Takes the settings defined in this configuration and sets them as system properties.
	 *
	 * @return This object.
	 */
	public Config setSystemProperties() {
		for (String section : getSectionNames()) {
			for (String key : getKeys(section)) {
				String k = (section.isEmpty() ? key : section + '/' + key);
				System.setProperty(k, getRaw(k));
			}
		}
		return this;
	}

	//-----------------------------------------------------------------------------------------------------------------
	// Workhorse setters
	//-----------------------------------------------------------------------------------------------------------------

	/**
	 * Sets a value in this config.
	 *
	 * @param key The key.
	 * @param value The value.
	 * @return This object.
	 * @throws UnsupportedOperationException If configuration is read only.
	 */
	public Config set(String key, String value) {
		checkWrite();
		assertArgNotNull("key", key);
		String sname = sname(key);
		String skey = skey(key);

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

		String s = applyMods(ce == null ? null : ce.getModifiers(), stringify(value));

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

	/**
	 * 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.
	 * @param value The new value POJO.
	 * @return The previous value, or <jk>null</jk> if the section or key did not previously exist.
	 * @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.
	 * @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 The previous value, or <jk>null</jk> if the section or key did not previously exist.
	 * @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.
	 * @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 modifiers
	 * 	Optional modifiers to apply to the value.
	 * 	<br>If <jk>null</jk>, then previous value will not be replaced.
	 * @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 The previous value, or <jk>null</jk> if the section or key did not previously exist.
	 * @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 modifiers, String comment, List<String> preLines) throws SerializeException {
		checkWrite();
		assertArgNotNull("key", key);
		String sname = sname(key);
		String skey = skey(key);
		modifiers = nullIfEmpty(modifiers);

		String s = applyMods(modifiers, serialize(value, serializer));

		configMap.setEntry(sname, skey, s, modifiers, comment, preLines);
		return this;
	}

	/**
	 * Removes an entry with the specified key.
	 *
	 * @param key The key.
	 * @return The previous value, or <jk>null</jk> if the section or key did not previously exist.
	 * @throws UnsupportedOperationException If configuration is read only.
	 */
	public Config remove(String key) {
		checkWrite();
		String sname = sname(key);
		String skey = skey(key);
		configMap.removeEntry(sname, skey);
		return this;
	}

	/**
	 * Encodes and unencoded entries in this config.
	 *
	 * <p>
	 * If any entries in the config are marked as encoded but not actually encoded,
	 * this will encode them.
	 *
	 * @return This object.
	 * @throws UnsupportedOperationException If configuration is read only.
	 */
	public Config applyMods() {
		checkWrite();
		for (String section : configMap.getSections()) {
			for (String key : configMap.getKeys(section)) {
				ConfigMapEntry ce = configMap.getEntry(section, key);
				if (ce.getModifiers() != null) {
					String mods = ce.getModifiers();
					String value = ce.getValue();
					for (int i = 0; i < mods.length(); i++) {
						Mod mod = getMod(mods.charAt(i));
						if (! mod.isApplied(value)) {
							configMap.setEntry(section, key, mod.apply(value), null, null, null);
						}
					}
				}
			}
		}

		return this;
	}

	//-----------------------------------------------------------------------------------------------------------------
	// API methods
	//-----------------------------------------------------------------------------------------------------------------

	/**
	 * 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.
	 * @return The entry bean, never <jk>null</jk>.
	 */
	public Entry get(String key) {
		return new Entry(this, configMap, sname(key), skey(key));
	}

	/**
	 * 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>.
	 *
	 * <h5 class='section'>Notes:</h5><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.
	 * @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);
	}

	/**
	 * 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 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 section names defined in this config.
	 *
	 * @return The section names defined in this config.
	 */
	public Set<String> getSectionNames() {
		return unmodifiable(configMap.getSections());
	}

	/**
	 * Returns <jk>true</jk> if this section contains the specified key and the key has a non-blank value.
	 *
	 * @param key The key.
	 * @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 isNotEmpty(get(key).as(String.class).orElse(null));
	}

	/**
	 * 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 The appended or existing section.
	 * @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 asRuntimeException(e);  // Impossible.
		}
	}

	/**
	 * 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>.
	 * @return The appended or existing section.
	 * @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 (contents != null)
			for (Map.Entry<String,Object> e : contents.entrySet())
				set(section(name) + '/' + e.getKey(), e.getValue());

		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 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 The appended or existing import statement.
	 * @throws UnsupportedOperationException If configuration is read only.
	 */
	public Config setImport(String sectionName, String importName, List<String> preLines) {
		checkWrite();
		configMap.setImport(section(name), importName, preLines);
		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(sectionName, importName);
		return this;
	}

	/**
	 * Loads the contents of the specified map of maps into this config.
	 *
	 * @param m The maps to load.
	 * @return This object.
	 * @throws SerializeException Value could not be serialized.
	 */
	public Config load(Map<String,Map<String,Object>> m) throws SerializeException {
		if (m != null)
			for (Map.Entry<String,Map<String,Object>> e : m.entrySet()) {
				setSection(e.getKey(), null, e.getValue());
			}
		return 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;
	}

	/**
	 * Saves this config file to the specified writer as an INI file.
	 *
	 * <p>
	 * The writer will automatically be closed.
	 *
	 * @param w The writer to send the output to.
	 * @return This object.
	 * @throws IOException If a problem occurred trying to send contents to the writer.
	 */
	public Writer writeTo(Writer w) throws IOException {
		return configMap.writeTo(w);
	}

	/**
	 * 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;
	}

	/**
	 * 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;
	}

	/**
	 * Closes this configuration object by unregistering it from the underlying config map.
	 *
	 * @throws IOException Thrown by underlying stream.
	 */
	public void close() throws IOException {
		configMap.unregister(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;
	}

	/**
	 * 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 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();
	}

	//-----------------------------------------------------------------------------------------------------------------
	// Test methods
	//-----------------------------------------------------------------------------------------------------------------

	ConfigMap getConfigMap() {
		return configMap;
	}

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


	//-----------------------------------------------------------------------------------------------------------------
	// Interface methods
	//-----------------------------------------------------------------------------------------------------------------

	@Override /* ConfigEventListener */
	public synchronized void onConfigChange(ConfigEvents events) {
		for (ConfigEventListener l : listeners)
			l.onConfigChange(events);
	}

	//-----------------------------------------------------------------------------------------------------------------
	// Private methods
	//-----------------------------------------------------------------------------------------------------------------

	private String serialize(Object value, Serializer serializer) throws SerializeException {
		if (value == null)
			return "";
		if (serializer == null)
			serializer = this.serializer;
		Class<?> c = value.getClass();
		if (value instanceof CharSequence)
			return nlIfMl((CharSequence)value);
		if (isSimpleType(c))
			return value.toString();

		if (value instanceof byte[]) {
			String s = null;
			byte[] b = (byte[])value;
			if (binaryFormat == BinaryFormat.HEX)
				s = toHex(b);
			else if (binaryFormat == BinaryFormat.SPACED_HEX)
				s = toSpacedHex(b);
			else
				s = base64Encode(b);
			int l = binaryLineLength;
			if (l <= 0 || s.length() <= l)
				return s;
			StringBuilder sb = new StringBuilder();
			for (int 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.serialize(value);
		else
			r = (String)serializer.serialize(value);

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

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

	private boolean isSimpleType(Type t) {
		if (! (t instanceof Class))
			return false;
		Class<?> c = (Class<?>)t;
		return (c == String.class || c.isPrimitive() || c.isAssignableFrom(Number.class) || c == Boolean.class || c.isEnum());
	}

	private String sname(String key) {
		assertArgNotNull("key", key);
		int i = key.indexOf('/');
		if (i == -1)
			return "";
		return key.substring(0, i);
	}

	private String skey(String key) {
		int i = key.indexOf('/');
		if (i == -1)
			return key;
		return key.substring(i+1);
	}

	private String section(String section) {
		assertArgNotNull("section", section);
		if (isEmpty(section))
			return "";
		return section;
	}

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


	//-----------------------------------------------------------------------------------------------------------------
	// Other methods
	//-----------------------------------------------------------------------------------------------------------------

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

	@Override /* Object */
	protected void finalize() throws Throwable {
		close();
	}
}