001/* 002 * ============================================================================ 003 * Copyright © 2002-2021 by Thomas Thrien. 004 * All Rights Reserved. 005 * ============================================================================ 006 * Licensed to the public under the agreements of the GNU Lesser General Public 007 * License, version 3.0 (the "License"). You may obtain a copy of the License at 008 * 009 * http://www.gnu.org/licenses/lgpl.html 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 013 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 014 * License for the specific language governing permissions and limitations 015 * under the License. 016 */ 017 018package org.tquadrat.foundation.config.spi.prefs; 019 020import static java.util.Arrays.asList; 021import static org.apiguardian.api.API.Status.STABLE; 022import static org.tquadrat.foundation.lang.Objects.requireNonNullArgument; 023import static org.tquadrat.foundation.lang.Objects.requireNotEmptyArgument; 024 025import java.util.prefs.BackingStoreException; 026import java.util.prefs.Preferences; 027 028import org.apiguardian.api.API; 029import org.tquadrat.foundation.annotation.ClassVersion; 030import org.tquadrat.foundation.config.spi.InvalidPreferenceValueException; 031import org.tquadrat.foundation.function.Getter; 032import org.tquadrat.foundation.function.Setter; 033 034/** 035 * <p>{@summary The abstract base class for the preference accessors.}</p> 036 * <p>Custom preference accessors can be implemented based directly on this 037 * class. If a 038 * {@link org.tquadrat.foundation.lang.StringConverter} 039 * implementation exists for the given type, the accessor for that type should 040 * be implemented based on 041 * {@link PreferenceAccessorBase}.</p> 042 * <p>Accessors for types that should be stored as {@code byte} arrays (or 043 * BLOBs) can be implemented by extending 044 * {@link BulkDataAccessorBase}.</p> 045 * 046 * @see Preferences#MAX_VALUE_LENGTH 047 * 048 * @extauthor Thomas Thrien - thomas.thrien@tquadrat.org 049 * @version $Id: PreferenceAccessor.java 1061 2023-09-25 16:32:43Z tquadrat $ 050 * @since 0.0.1 051 * 052 * @param <T> The type of the property. 053 * 054 * @UMLGraph.link 055 */ 056@ClassVersion( sourceVersion = "$Id: PreferenceAccessor.java 1061 2023-09-25 16:32:43Z tquadrat $" ) 057@API( status = STABLE, since = "0.0.1" ) 058public abstract class PreferenceAccessor<T> 059{ 060 /*------------*\ 061 ====** Attributes **======================================================= 062 \*------------*/ 063 /** 064 * The property getter. 065 */ 066 private final Getter<T> m_Getter; 067 068 /** 069 * The property name. 070 */ 071 private final String m_PropertyName; 072 073 /** 074 * The property setter. 075 */ 076 private final Setter<T> m_Setter; 077 078 /*--------------*\ 079 ====** Constructors **===================================================== 080 \*--------------*/ 081 /** 082 * Creates a new {@code PreferenceAccessor} instance. 083 * 084 * @param propertyName The name of the property. 085 * @param getter The property getter. 086 * @param setter The property setter. 087 */ 088 protected PreferenceAccessor( final String propertyName, final Getter<T> getter, final Setter<T> setter ) 089 { 090 m_PropertyName = requireNotEmptyArgument( propertyName, "propertyName" ); 091 m_Getter = requireNonNullArgument( getter, "getter" ); 092 m_Setter = requireNonNullArgument( setter, "setter" ); 093 } // PreferenceAccessor() 094 095 /*---------*\ 096 ====** Methods **========================================================== 097 \*---------*/ 098 /** 099 * Returns the property name. 100 * 101 * @return The property name. 102 */ 103 public final String getPropertyName() { return m_PropertyName; } 104 105 /** 106 * Returns the getter. 107 * 108 * @return The getter. 109 */ 110 protected final Getter<T> getter() { return m_Getter; } 111 112 /** 113 * Checks whether the provided preferences node has a key name like the 114 * property name. 115 * 116 * @param node The preferences node. 117 * @return {@code true} if there is a key with that name, {@code false} 118 * otherwise. 119 * @throws BackingStoreException There are problems on reading the given 120 * node. 121 */ 122 protected final boolean hasKey( final Preferences node ) throws BackingStoreException 123 { 124 final var retValue = asList( node.keys() ).contains( m_PropertyName ); 125 126 //---* Done *---------------------------------------------------------- 127 return retValue; 128 } // hasKey() 129 130 /** 131 * Reads the preference value from the given node and writes it to the 132 * property. 133 * 134 * @param node The preference node. 135 * @throws BackingStoreException There are problems on reading the given 136 * node. 137 * @throws InvalidPreferenceValueException The preferences value cannot be 138 * translated to the property type. 139 */ 140 public abstract void readPreference( final Preferences node ) throws BackingStoreException, InvalidPreferenceValueException; 141 142 /** 143 * Returns the setter. 144 * 145 * @return The setter. 146 */ 147 protected final Setter<T> setter() { return m_Setter; } 148 149 /** 150 * Writes the preference value from the property and writes it to the 151 * given node. 152 * 153 * @param node The preference node. 154 * @throws BackingStoreException There are problems on writing the given 155 * node. 156 */ 157 public abstract void writePreference( final Preferences node ) throws BackingStoreException; 158} 159// class PreferenceAccessor 160 161/* 162 * End of File 163 */