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