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.TYPE;
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.PreferenceChangeListenerBase;
032
033/**
034 *  <p>{@summary Provides some general configuration settings for a
035 *  configuration bean that implements
036 *  {@link PreferencesBeanSpec}.}</p>
037 *  <p>At default, the node for the &quot;preferences&quot; is determined by the
038 *  class of the configuration bean specification, but with this annotation, it
039 *  could get another name.</p>
040 *  <p>Also usually, there is no listener for changes to the underlying
041 *  preferences. But this annotation allows to configure it.</p>
042 *
043 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
044 *  @version $Id: PreferencesRoot.java 944 2021-12-21 21:56:24Z tquadrat $
045 *  @since 0.1.0
046 *
047 *  @see java.util.prefs.Preferences#userNodeForPackage(Class)
048 */
049@ClassVersion( sourceVersion = "$Id: PreferencesRoot.java 944 2021-12-21 21:56:24Z tquadrat $" )
050@Documented
051@Retention( CLASS )
052@Target( TYPE )
053@API( status = STABLE, since = "0.1.0" )
054public @interface PreferencesRoot
055{
056        /*------------*\
057    ====** Attributes **=======================================================
058        \*------------*/
059    /**
060     *  The alternative name for the &quot;preferences&quot; node.
061     *
062     *  @return The node name.
063     */
064    String nodeName();
065
066    /**
067     *  <p>{@summary The class for the preferences change listener.} It has to
068     *  extend
069     *  {@link PreferenceChangeListenerBase}.</p>
070     *  <p>The class
071     *  {@link org.tquadrat.foundation.config.spi.prefs.PreferenceChangeListenerImpl}
072     *  provides a default implementation.</p>
073     *
074     *  @return The class for the change listener; if {@code null}, no listener
075     *      support will be generated.
076     */
077    Class<? extends PreferenceChangeListenerBase> changeListenerClass();
078}
079//  annotation PreferencesRoot
080
081/*
082 *  End of File
083 */