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