001/*
002 * PlotSquared, a land and world management plugin for Minecraft.
003 * Copyright (C) IntellectualSites <https://intellectualsites.com>
004 * Copyright (C) IntellectualSites team and contributors
005 *
006 * This program is free software: you can redistribute it and/or modify
007 * it under the terms of the GNU General Public License as published by
008 * the Free Software Foundation, either version 3 of the License, or
009 * (at your option) any later version.
010 *
011 * This program is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014 * GNU General Public License for more details.
015 *
016 * You should have received a copy of the GNU General Public License
017 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
018 */
019package com.plotsquared.core.configuration;
020
021import java.util.Map;
022
023/**
024 * Represents a source of configurable options and settings.
025 */
026public interface Configuration extends ConfigurationSection {
027
028    /**
029     * Sets the default value of the given path as provided.
030     * <p>If no source {@link Configuration} was provided as a default
031     * collection, then a new {@link MemoryConfiguration} will be created to
032     * hold the new default value.</p>
033     * <p>If value is null, the value will be removed from the default
034     * Configuration source.</p>
035     *
036     * @param path  Path of the value to set.
037     * @param value Value to set the default to.
038     * @throws IllegalArgumentException Thrown if path is null.
039     */
040    @Override
041    void addDefault(String path, Object value);
042
043    /**
044     * Sets the default values of the given paths as provided.
045     * <p>If no source {@link Configuration} was provided as a default
046     * collection, then a new {@link MemoryConfiguration} will be created to
047     * hold the new default values.</p>
048     *
049     * @param defaults A map of Path-&gt;Values to add to defaults.
050     * @throws IllegalArgumentException Thrown if defaults is null.
051     */
052    void addDefaults(Map<String, Object> defaults);
053
054    /**
055     * Sets the default values of the given paths as provided.
056     * <p>If no source {@link Configuration} was provided as a default
057     * collection, then a new {@link MemoryConfiguration} will be created to
058     * hold the new default value.</p>
059     * <p>This method will not hold a reference to the specified Configuration,
060     * nor will it automatically update if that Configuration ever changes. If
061     * you check this, you should set the default source with {@link
062     * #setDefaults(Configuration)}.</p>
063     *
064     * @param defaults A configuration holding a list of defaults to copy.
065     * @throws IllegalArgumentException Thrown if defaults is null or this.
066     */
067    void addDefaults(Configuration defaults);
068
069    /**
070     * Gets the source {@link Configuration} for this configuration.
071     *
072     * <p>If no configuration source was set, but default values were added, then
073     * a {@link MemoryConfiguration} will be returned. If no source was set
074     * and no defaults were set, then this method will return null.</p>
075     *
076     * @return Configuration source for default values, or null if none exist.
077     */
078    Configuration getDefaults();
079
080    /**
081     * Sets the source of all default values for this {@link Configuration}.
082     *
083     * <p>If a previous source was set, or previous default values were defined,
084     * then they will not be copied to the new source.</p>
085     *
086     * @param defaults New source of default values for this configuration.
087     * @throws IllegalArgumentException Thrown if defaults is null or this.
088     */
089    void setDefaults(Configuration defaults);
090
091    /**
092     * Gets the {@link ConfigurationOptions} for this {@link Configuration}.
093     * <p>All setters through this method are chainable.</p>
094     *
095     * @return Options for this configuration
096     */
097    ConfigurationOptions options();
098
099}