001/*
002 * ============================================================================
003 * Copyright © 2002-2023 by Thomas Thrien.
004 * All Rights Reserved.
005 * ============================================================================
006 *
007 * Licensed to the public under the agreements of the GNU Lesser General Public
008 * License, version 3.0 (the "License"). You may obtain a copy of the License at
009 *
010 *      http://www.gnu.org/licenses/lgpl.html
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
014 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
015 * License for the specific language governing permissions and limitations
016 * under the License.
017 */
018
019package org.tquadrat.foundation.config;
020
021import static org.apiguardian.api.API.Status.STABLE;
022
023import java.util.Optional;
024import java.util.prefs.Preferences;
025
026import org.apiguardian.api.API;
027import org.tquadrat.foundation.annotation.ClassVersion;
028
029/**
030 *  <p>{@summary When a configuration bean should be connected with
031 *  {@link Preferences Preferences},
032 *  the respective configuration bean specification interface needs to extend
033 *  this interface.}</p>
034 *  <p>Only user preferences are supported.</p>
035 *  <p>The preferences values will <i>not</i> be loaded automatically. A call
036 *  to
037 *  {@link #loadPreferences()}
038 *  is required.</p>
039 *  <p>A call to
040 *  {@link #updatePreferences()}
041 *  persists the respective value.</p>
042 *  <p>The name of the preferences node for the values is the class name of the
043 *  configuration bean specification interface.</p>
044 *  <p>If the requirement is to initialise a property from a
045 *  {@link Preferences#systemRoot() SYSTEM Preference},
046 *  consider to use the
047 *  {@link SystemPreference &#64;SystemPreference}
048 *  annotation instead of implementing this interface.</p>
049 *
050 *  @note   None of the methods in this interface can be called from
051 *      {@code initData()}!
052 *
053 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
054 *  @version $Id: PreferencesBeanSpec.java 1061 2023-09-25 16:32:43Z tquadrat $
055 *  @since 0.0.1
056 *
057 *  @UMLGraph.link
058 *
059 *  @see Preference
060 *  @see NoPreference
061 */
062@ClassVersion( sourceVersion = "$Id: PreferencesBeanSpec.java 1061 2023-09-25 16:32:43Z tquadrat $" )
063@API( status = STABLE, since = "0.1.0" )
064public interface PreferencesBeanSpec extends ConfigBeanSpec
065{
066        /*---------*\
067    ====** Methods **==========================================================
068        \*---------*/
069    /**
070     *  Loads the preference values from the
071     *  {@link Preferences Preferences} instances connected
072     *  with the configuration bean based on the specification that is
073     *  extending this interface into the properties of that configuration
074     *  bean.
075     */
076    public void loadPreferences();
077
078    /**
079     *  Returns the user preferences node that backs this configuration bean.
080     *
081     *  @return An instance of
082     *      {@link Optional}
083     *      that holds the
084     *      {@link Preferences}
085     *      instance.
086     */
087    public default Optional<Preferences> obtainPreferencesNode() { return Optional.empty(); }
088
089    /**
090     *  Updates the instances of
091     *  {@link Preferences Preferences},
092     *  that are connected to the configuration bean based on the specification
093     *  that is extending this interface, with the property values of this
094     *  configuration bean.
095     */
096    public void updatePreferences();
097}
098//  interface PreferencesBeanSpec
099
100/*
101 *  End of File
102 */