001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.data.preferences;
003
004import org.openstreetmap.josm.data.Preferences;
005
006/**
007 * Interface for a preference value.
008 *
009 * Implementations must provide a proper <code>equals</code> method.
010 *
011 * @param <T> the data type for the value
012 * @since 9759
013 */
014public interface Setting<T> {
015    /**
016     * Returns the value of this setting.
017     *
018     * @return the value of this setting
019     */
020    T getValue();
021
022    /**
023     * Check if the value of this Setting object is equal to the given value.
024     * @param otherVal the other value
025     * @return true if the values are equal
026     */
027    default boolean equalVal(T otherVal) {
028        return getValue() == null ? (otherVal == null) : getValue().equals(otherVal);
029    }
030
031    /**
032     * Clone the current object.
033     * @return an identical copy of the current object
034     */
035    Setting<T> copy();
036
037    /**
038     * Enable usage of the visitor pattern.
039     *
040     * @param visitor the visitor
041     */
042    void visit(SettingVisitor visitor);
043
044    /**
045     * Returns a setting whose value is null.
046     *
047     * Cannot be static, because there is no static inheritance.
048     * @return a Setting object that isn't null itself, but returns null
049     * for {@link #getValue()}
050     */
051    Setting<T> getNullInstance();
052
053    /**
054     * Set the time for this setting.
055     *
056     * For default preferences. They are saved in a cache file. Keeping the
057     * time allows to discard very old default settings.
058     * @param time the time in seconds since epoch
059     */
060    void setTime(Long time);
061
062    /**
063     * Get the time for this setting.
064     * @return the time for this setting
065     * @see #setTime(java.lang.Long)
066     */
067    Long getTime();
068
069    /**
070     * Mark setting as new.
071     *
072     * For default preferences. A setting is marked as new, if it has been seen
073     * in the current session.
074     * Methods like {@link Preferences#get(java.lang.String, java.lang.String)},
075     * can be called from different parts of the code with the same key. In this case,
076     * the supplied default value must match. However, this is only an error if the mismatching
077     * default value has been seen in the same session (and not loaded from cache).
078     * @param isNew true, if it is new
079     */
080    void setNew(boolean isNew);
081
082    /**
083     * Return if the setting has been marked as new.
084     * @return true, if the setting has been marked as new
085     * @see #setNew(boolean)
086     */
087    boolean isNew();
088}