001/*
002 * ============================================================================
003 *  Copyright © 2002-2023 by Thomas Thrien.
004 *  All Rights Reserved.
005 * ============================================================================
006 *  Licensed to the public under the agreements of the GNU Lesser General Public
007 *  License, version 3.0 (the "License"). You may obtain a copy of the License at
008 *
009 *       http://www.gnu.org/licenses/lgpl.html
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, WITHOUT
013 *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
014 *  License for the specific language governing permissions and limitations
015 *  under the License.
016 */
017
018package org.tquadrat.foundation.config;
019
020import static org.apiguardian.api.API.Status.STABLE;
021
022import java.util.Optional;
023
024import org.apiguardian.api.API;
025import org.tquadrat.foundation.annotation.ClassVersion;
026import org.tquadrat.foundation.inifile.INIFile;
027
028/**
029 *  <p>{@summary When a configuration bean should be connected with an
030 *  {@link org.tquadrat.foundation.inifile.INIFile INI}
031 *  file (a Windows style configuration file), the respective configuration
032 *  bean specification interface needs to extend this interface.}</p>
033 *  <p>A configuration bean can be connected to only one {@code INI} file, and
034 *  properties that are kept in
035 *  {@link java.util.prefs.Preferences Preferences}
036 *  cannot be held in the {@code INI}, too, and vice versa.</p>
037 *  <p>The configuration bean specification must use the annotation
038 *  {@link INIFileConfig &#64;INIFileConfig}
039 *  to specify the path to the configuration file. In addition, each getter has
040 *  to be annotated with
041 *  {@link INIValue &#64;INIValue}
042 *  to define its coordinates in the configuration.</p>
043 *  <p>When the file is created by the program itself, the respective
044 *  comments from the annotations will be added to the new file; for the
045 *  groups, these can be provided through the
046 *  {@link INIGroup &#64;INIGroup}
047 *  and
048 *  {@link INIGroups &#64;INIGroups}
049 *  annotations</p>
050 *  <p>The configuration values will <i>not</i> be loaded automatically from
051 *  the {@code INI} file. A call to
052 *  {@link #loadINIFile()}
053 *  is required.</p>
054 *  <p>A call to
055 *  {@link #updateINIFile()}
056 *  persists the respective value.</p>
057 *
058 *  @version $Id: INIBeanSpec.java 1061 2023-09-25 16:32:43Z tquadrat $
059 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
060 *  @UMLGraph.link
061 *  @since 0.1.0
062 */
063@ClassVersion( sourceVersion = "$Id: INIBeanSpec.java 1061 2023-09-25 16:32:43Z tquadrat $" )
064@API( status = STABLE, since = "0.1.0" )
065public interface INIBeanSpec extends ConfigBeanSpec
066{
067        /*---------*\
068    ====** Methods **==========================================================
069        \*---------*/
070    /**
071     *  Loads the configuration values from the
072     *  {@link INIFile}
073     *  that is connected to this configuration bean.
074     */
075    public void loadINIFile();
076
077    /**
078     *  Returns a reference to the
079     *  {@link INIFile}
080     *  instance that backs up this configuration bean.
081     *
082     *  @return An instance of
083     *      {@link Optional}
084     *      that holds the {@code INIFile} instance.
085     */
086    public Optional<INIFile> obtainINIFile();
087
088    /**
089     *  Persists the configuration values to the
090     *  {@link INIFile}
091     *  that is connected to this configuration bean.
092     */
093    public void updateINIFile();
094}
095//  interface INIBeanSpec
096
097/*
098 *  End of File
099 */