001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.commons.settings;
018
019/**
020 * A writable extension of {@link SettingSource} that supports modifying property values.
021 *
022 * <p>
023 * This interface extends {@link SettingSource} with methods for setting, unsetting, and clearing properties.
024 * All stores that implement this interface provide read/write access and can be modified at runtime.
025 *
026 * <p>
027 * <b>Sources vs Stores:</b>
028 * <ul>
029 *    <li><b>Sources</b> ({@link SettingSource}) - Provide read-only access to property values
030 *    <li><b>Stores</b> ({@link SettingStore}) - Provide read/write access to property values
031 * </ul>
032 *
033 * <h5 class='section'>Example:</h5>
034 * <p class='bjava'>
035 *    <jc>// Create a writable store</jc>
036 *    MapStore <jv>store</jv> = <jk>new</jk> MapStore();
037 *    <jv>store</jv>.set(<js>"my.property"</js>, <js>"value"</js>);
038 *    <jv>store</jv>.unset(<js>"my.property"</js>);
039 *    <jv>store</jv>.clear();
040 * </p>
041 */
042public interface SettingStore extends SettingSource {
043
044   /**
045    * Sets a setting in this store.
046    *
047    * <p>
048    * Setting a value to <c>null</c> means that {@link #get(String)} will return <c>Optional.empty()</c> for that key,
049    * effectively overriding any values from lower-priority sources. Use {@link #unset(String)} if you want
050    * {@link #get(String)} to return <c>null</c> (indicating the key doesn't exist in this store).
051    *
052    * @param name The property name.
053    * @param value The property value, or <c>null</c> to set an empty override.
054    */
055   void set(String name, String value);
056
057   /**
058    * Removes a setting from this store.
059    *
060    * <p>
061    * After calling this method, {@link #get(String)} will return <c>null</c> for the specified key,
062    * indicating that the key doesn't exist in this store (as opposed to returning <c>Optional.empty()</c>,
063    * which would indicate the key exists but has a null value).
064    *
065    * @param name The property name to remove.
066    */
067   void unset(String name);
068
069   /**
070    * Clears all settings from this store.
071    *
072    * <p>
073    * After calling this method, all keys will be removed from this store, and {@link #get(String)} will
074    * return <c>null</c> for all keys.
075    */
076   void clear();
077}
078