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;
019
020import static java.lang.annotation.ElementType.TYPE;
021import static java.lang.annotation.RetentionPolicy.CLASS;
022import static org.apiguardian.api.API.Status.STABLE;
023
024import java.lang.annotation.Documented;
025import java.lang.annotation.Retention;
026import java.lang.annotation.Target;
027
028import org.apiguardian.api.API;
029import org.tquadrat.foundation.annotation.ClassVersion;
030
031/**
032 *  The definition of an {@code INI} file that is used in the context of a
033 *  configuration bean implementing
034 *  {@link INIBeanSpec}.
035 *
036 *  @version $Id: INIFileConfig.java 1015 2022-02-09 08:25:36Z tquadrat $
037 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
038 *  @since 0.1.0
039 */
040@ClassVersion( sourceVersion = "$Id: INIFileConfig.java 1015 2022-02-09 08:25:36Z tquadrat $" )
041@Documented
042@Retention( CLASS )
043@Target( TYPE )
044@API( status = STABLE, since = "0.1.0" )
045public @interface INIFileConfig
046{
047        /*------------*\
048    ====** Attributes **=======================================================
049        \*------------*/
050    /**
051     *  In case the configuration file is created by the program, this comment
052     *  will be written to it.
053     *
054     *  @return The file comment.
055     */
056    public String comment() default "";
057
058    /**
059     *  Flag that indicates whether the configuration file must already exist
060     *  prior to the first attempt to open it. If {@code true} and the file
061     *  does not exist, the creation of the configuration bean will fail with
062     *  an
063     *  {@link ExceptionInInitializerError}
064     *  that has an
065     *  {@link java.io.FileNotFoundException FileNotFoundException}
066     *  as the
067     *  {@linkplain Throwable#getCause() cause}.
068     *
069     *  @return {@code true} if the file needs to exist on program start,
070     *      {@code false} if it will be created when missing.
071     */
072    public boolean mustExist() default false;
073
074    /**
075     *  <p>{@summary The filename of the {@code INI} file.}</p>
076     *  <p>If the filename starts …</p>
077     *  <ul>
078     *      <li>… with {@code '/'} (on UNIX) or {@code 'C:\'} (or another drive
079     *      letter on MS&nbsp;Windows) it represents an absolute path and will
080     *      be used as is.<br>
081     *      Sample: {@code /etc/configs/app.ini}</li>
082     *      <li>… with the prefix {@code $USER/}, it will be resolved against the
083     *      home folder of the current user.<br>
084     *      Sample: {@code $USER/.config/app.ini}<br>
085     *      On Ubuntu, and for the user otto, this resolves to
086     *      {@code /home/otto/.config/app.ini}.</li>
087     *      <li>… with the prefix {@code ${<property>}}, it will be resolved
088     *      against the path that is represented by the property with the name
089     *      {@code <property>}. Obviously, the property has to be of type
090     *      {@link java.nio.file.Path},
091     *      otherwise the generated configuration bean will not compile.<br>
092     *      Sample: {@code ${configPath}app.ini}<br>
093     *      If {@code getConfigPath()} return {@code /opt/data/configs}, this
094     *      resolves to {@code /opt/data/configs/app.ini}.</li>
095     *  </ul>
096     *  <p>In any other case, the filename represents a relative path that is
097     *  resolved against the current working directory. So if the value is
098     *  {@code data/config/app.ini}, and the current working directory is
099     *  {@code /home/otto}, it resolves to
100     *  {@code /home/otto/config/app.ini}.</p>
101     *
102     *  @return The filename.
103     */
104    public String path();
105}
106//  @interface INIFileConfig
107
108/*
109 *  End of File
110 */