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}