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.RUNTIME;
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;
031
032/**
033 *  The marker for a configuration bean specification. It will work only on
034 *  interfaces that extend
035 *  {@link ConfigBeanSpec}.
036 *
037 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
038 *  @version $Id: ConfigurationBeanSpecification.java 920 2021-05-23 14:27:24Z tquadrat $
039 *  @since 0.0.1
040 *
041 *  @UMLGraph.link
042 */
043@ClassVersion( sourceVersion = "$Id: ConfigurationBeanSpecification.java 920 2021-05-23 14:27:24Z tquadrat $" )
044@Documented
045@Retention( RUNTIME )
046@Target( TYPE )
047@API( status = STABLE, since = "0.0.1" )
048public @interface ConfigurationBeanSpecification
049{
050        /*------------*\
051    ====** Attributes **=======================================================
052        \*------------*/
053    /**
054     *  The optional base class for the new configuration bean. The default is
055     *  {@link Object} (and will be ignored).
056     *
057     *  @return The base class.
058     */
059    public Class<?> baseClass() default Object.class;
060
061    /**
062     *  <p>{@summary The name of the resource with the initialisation data for
063     *  the configuration bean.}</p>
064     *  <p>The resource file must have the format of a Java properties file,
065     *  and the name is relative to the location of the configuration bean
066     *  specification interface itself.</p>
067     *  <p>The special value &quot;=&quot; translates to the simple name of
068     *  the interface, suffixed with {@code .properties}; this means, for a
069     *  specification interface named {@code com.sample.Specification},
070     *  the resulting name for the property would be
071     *  {@code Specification.properties}.</p>
072     *  <p>The keys for the properties are properties as specified in the
073     *  configuration bean specification interface.</p>
074     *
075     *  @return The resource name for an initialisation data property; the
076     *      default is not having such a resource.
077     *
078     *  @see java.util.Properties
079     *  @see Class#getResourceAsStream(String)
080     */
081    String initDataResource() default "";
082
083    /**
084     *  <p>{@summary The fully qualified name of the class that implements the
085     *  configuration bean.} The default is the empty String.</p>
086     *  <p>If no explicit class name is set, it will be derived from the name
087     *  of the interface that specifies the configuration bean as below:
088     *  <pre><code>  var packageName = specification.getClass().getPackageName();
089     *  var specificationName = specification.getClass().getSimpleName();
090     *  var className = format( "%sgenerated.%sImpl", packageName.isEmpty()
091     *      ? ""
092     *      : packageName + ".", specificationName );</code></pre>
093     *  For a specification interface named {@code com.sample.Specification},
094     *  the resulting name would be
095     *  {@code com.sample.generated.SpecificationImpl}.
096     *
097     *  @return The intended name of the configuration bean class.
098     */
099    String name() default "";
100
101    /**
102     *  The flag that determines the package for the generated bean. If
103     *  {@code false} (the default) it will be put to a package named
104     *  {@code generated} below the package of the specification interface, on
105     *  {@code true} it will be stored to the same package with the
106     *  specification interface.
107     *
108     *  @return {@code true} if the generated configuration bean should be
109     *      placed in the same package as the specification interface,
110     *      {@code false} if it should be placed to the {@code generated}
111     *      sub-package.
112     */
113    boolean samePackage() default false;
114
115    /**
116     *  The flag that indicates whether the access to the configuration bean
117     *  properties should be synchronised. The default is {@code true}.
118     *
119     *  @return {@code true} if any access to a configuration value has to be
120     *      thread-safe, {@code false} otherwise.
121     */
122    boolean synchronizeAccess() default true;
123}
124//  annotation ConfigurationBeanSpecification
125
126/*
127 *  End of File
128 */