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}