001/*
002 * ============================================================================
003 * Copyright © 2002-2021 by Thomas Thrien.
004 * All Rights Reserved.
005 * ============================================================================
006 *
007 * Licensed to the public under the agreements of the GNU Lesser General Public
008 * License, version 3.0 (the "License"). You may obtain a copy of the License at
009 *
010 *      http://www.gnu.org/licenses/lgpl.html
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
014 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
015 * License for the specific language governing permissions and limitations
016 * under the License.
017 */
018
019package org.tquadrat.foundation.config;
020
021import static java.lang.annotation.ElementType.METHOD;
022import static java.lang.annotation.RetentionPolicy.CLASS;
023import static org.apiguardian.api.API.Status.STABLE;
024
025import java.lang.annotation.Documented;
026import java.lang.annotation.Retention;
027import java.lang.annotation.Target;
028
029import org.apiguardian.api.API;
030import org.tquadrat.foundation.annotation.ClassVersion;
031import org.tquadrat.foundation.config.spi.prefs.PreferenceAccessor;
032
033/**
034 *  <p>{@summary This annotation indicates that the property for the annotated
035 *  getter is initialised from a {@code SYSTEM}
036 *  {@linkplain java.util.prefs.Preferences Preferences value}
037 *  with the path and name.}</p>
038 *  <p>This annotation implies the
039 *  {@link NoPreference}
040 *  annotation.</p>
041 *
042 *  @note   Even when no setter is defined for a property with this annotation
043 *      – making it effectively immutable – the field for it will not be
044 *      {@code final}. This is because of the way the initialisation works.
045 *
046 *  @note   Changes to the value of a property marked with this annotation will
047 *      not be reflected to the SYSTEM {@code Preferences}.
048 *
049 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
050 *  @version $Id: SystemPreference.java 942 2021-12-20 02:04:04Z tquadrat $
051 *  @since 0.0.1
052 *
053 *  @see java.util.prefs.Preferences#get(String, String)
054 */
055@ClassVersion( sourceVersion = "$Id: SystemPreference.java 942 2021-12-20 02:04:04Z tquadrat $" )
056@Documented
057@Retention( CLASS )
058@Target( METHOD )
059@API( status = STABLE, since = "0.0.1" )
060public @interface SystemPreference
061{
062        /*------------*\
063    ====** Attributes **=======================================================
064        \*------------*/
065    /**
066     *  The key for the {@code SYSTEM} preference value to read.
067     *
068     *  @return The key for the {@code SYSTEM} preference.
069     */
070    String key();
071
072    /**
073     *  The path for the {@code SYSTEM} preference node that holds the value.
074     *
075     *  @return The path for the {@code SYSTEM} preference node.
076     */
077    String path();
078
079    /**
080     *  <p>{@summary The implementation of
081     *  {@link PreferenceAccessor}
082     *  that is used to access the {@code Preferences} and to translate the
083     *  value into the type of the property.}</p>
084     *  <p>This is mandatory, no default is used, nor will it be somehow
085     *  inferred.
086     *
087     *  @return The class for the preferences accessor.
088     */
089    @API( status = STABLE, since = "0.1.0" )
090    Class<? extends PreferenceAccessor<?>> accessor();
091}
092//  annotation SystemPreference
093
094/*
095 *  End of File
096 */