001/*
002 * ============================================================================
003 * Copyright © 2002-2024 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 org.apiguardian.api.API;
022import org.tquadrat.foundation.annotation.ClassVersion;
023import org.tquadrat.foundation.lang.StringConverter;
024
025import java.lang.annotation.Documented;
026import java.lang.annotation.Retention;
027import java.lang.annotation.Target;
028
029import static java.lang.annotation.ElementType.METHOD;
030import static java.lang.annotation.RetentionPolicy.CLASS;
031import static org.apiguardian.api.API.Status.STABLE;
032
033/**
034 *  <p>{@summary This annotation indicates that the property for the annotated
035 *  getter is initialised from a system property with the given name.}</p>
036 *  <p>The initialisation uses the default
037 *  {@link StringConverter}
038 *  for the type of the property if none is provided; if there is no default
039 *  String converter, an error is thrown during compile time.</p>
040 *  <p>Changing the configuration property value will not have an effect to
041 *  the system property.</p>
042 *  <p>This annotation implies the
043 *  {@link org.tquadrat.foundation.config.NoPreference}
044 *  annotation.</p>
045 *
046 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
047 *  @version $Id: SystemProperty.java 1120 2024-03-16 09:48:00Z tquadrat $
048 *  @since 0.0.1
049 *
050 *  @see System#getProperty(String)
051 */
052@ClassVersion( sourceVersion = "$Id: SystemProperty.java 1120 2024-03-16 09:48:00Z tquadrat $" )
053@Documented
054@Retention( CLASS )
055@Target( METHOD )
056@API( status = STABLE, since = "0.0.1" )
057public @interface SystemProperty
058{
059        /*------------*\
060    ====** Attributes **=======================================================
061        \*------------*/
062    /**
063     *  <p>{@summary The default value for the system property.} It will
064     *  be used for the initialisation of the property if the system property
065     *  is not set.</p>
066     *  <p>It is mandatory to provide a default value for primitive type
067     *  properties.</p>
068     *  <p>The default setting is a String containing only a {@code NUL}; it
069     *  will be treated as _null</p>
070     *
071     *  @return The default value.
072     */
073    public String defaultValue() default "\0";
074
075    /**
076     *  The name for the system property to read.
077     *
078     *  @return The name for the system property.
079     */
080    String value();
081}
082//  annotation SystemProperty
083
084/*
085 *  End of File
086 */