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.i18n;
020
021import static java.lang.annotation.ElementType.FIELD;
022import static java.lang.annotation.RetentionPolicy.SOURCE;
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 *  <p>{@summary This annotation is used to mark a String constant that holds
034 *  the base bundle name for the resource bundle for the messages and texts.}
035 *  When the annotation processor finds more than one field with this
036 *  annotation, the result is unpredictable.</p>
037 *  <p>The code for the default language is used when there is no resource
038 *  bundle for the current language/locale setting. If not explicitly set, the
039 *  default is &quot;{@code en}&quot;, the language code for English.</p>
040 *  <p>If this annotation is not used at all, the constant
041 *  {@value org.tquadrat.foundation.i18n.I18nUtil#DEFAULT_BASEBUNDLENAME}
042 *  will be used for the base bundle name and the locale
043 *  {@link java.util.Locale#ENGLISH ENGLISH}
044 *  is used as the default language.</p>
045 *  <p>When used with modules, the base bundle name should be either a simple
046 *  class name <i>without</i> a package name, or the package should be open for
047 *  this module ({@code org.tquadrat.foundation.i18n}); otherwise a
048 *  {@linkplain java.util.spi.ResourceBundleProvider resource bundle provider}
049 *  must be provided (and the methods
050 *  {@link org.tquadrat.foundation.i18n.I18nUtil#loadResourceBundle(String)}
051 *  and
052 *  {@link org.tquadrat.foundation.i18n.I18nUtil#loadResourceBundle(String,Module)}
053 *  cannot be used). This is because this library is one module, while the
054 *  (generated) application resource bundle lives in another module, and is
055 *  therefore not accessible. In opposite, a bundle without package is
056 *  accessible from everywhere.</p>
057 *
058 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
059 *  @version $Id: BaseBundleName.java 995 2022-01-23 01:09:35Z tquadrat $
060 *  @since 0.1.0
061 */
062@Documented
063@Retention( SOURCE )
064@Target( FIELD )
065@ClassVersion( sourceVersion = "$Id: BaseBundleName.java 995 2022-01-23 01:09:35Z tquadrat $" )
066@API( status = STABLE, since = "0.1.0" )
067public @interface BaseBundleName
068{
069        /*------------*\
070    ====** Attributes **=======================================================
071        \*------------*/
072    /**
073     *  The default language.
074     *
075     *  @return The language code for the default language.
076     */
077    String defaultLanguage() default "en";
078}
079//  annotation BaseBundleName
080
081/*
082 *  End of File
083 */