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 org.apiguardian.api.API.Status.STABLE; 022import static org.tquadrat.foundation.config.SpecialPropertyType.CONFIG_PROPERTY_CHARSET; 023import static org.tquadrat.foundation.config.SpecialPropertyType.CONFIG_PROPERTY_LOCALE; 024import static org.tquadrat.foundation.config.SpecialPropertyType.CONFIG_PROPERTY_RESOURCEBUNDLE; 025import static org.tquadrat.foundation.config.SpecialPropertyType.CONFIG_PROPERTY_TIMEZONE; 026import static org.tquadrat.foundation.lang.CommonConstants.PROPERTY_IS_DEBUG; 027import static org.tquadrat.foundation.lang.CommonConstants.PROPERTY_IS_TEST; 028 029import java.nio.charset.Charset; 030import java.time.ZoneId; 031import java.util.Locale; 032import java.util.Optional; 033import java.util.ResourceBundle; 034 035import org.apiguardian.api.API; 036import org.tquadrat.foundation.annotation.ClassVersion; 037import org.tquadrat.foundation.annotation.PropertyName; 038 039/** 040 * <p>{@summary The base for the specification of a configuration bean; the 041 * final specification interface must also be annotated with 042 * {@link ConfigurationBeanSpecification @ConfigurationBeanSpecification} 043 * in order to be recognised properly.}</p> 044 * <p>The generation process will generate only getter and setter methods, 045 * other methods must be provided as {@code default}.</p> 046 * <p>If the configuration bean should be initialised through command line 047 * arguments, the specification interface must extend 048 * {@link org.tquadrat.foundation.config.CLIBeanSpec}, 049 * and if it should work with 050 * {@link java.util.prefs.Preferences Preferences}, 051 * the interface needs to extend 052 * {@link org.tquadrat.foundation.config.PreferencesBeanSpec}. It could 053 * extend both.</p> 054 * 055 * @extauthor Thomas Thrien - thomas.thrien@tquadrat.org 056 * @version $Id: ConfigBeanSpec.java 1010 2022-02-05 19:28:36Z tquadrat $ 057 * @since 0.1.0 058 * 059 * @UMLGraph.link 060 */ 061@ClassVersion( sourceVersion = "$Id: ConfigBeanSpec.java 1010 2022-02-05 19:28:36Z tquadrat $" ) 062@API( status = STABLE, since = "0.1.0" ) 063public interface ConfigBeanSpec 064{ 065 /*---------*\ 066 ====** Methods **========================================================== 067 \*---------*/ 068 /** 069 * Adds a new 070 * {@link ConfigurationChangeListener} 071 * to this configuration bean. 072 * 073 * @param listener The new listener. 074 */ 075 public void addListener( final ConfigurationChangeListener listener ); 076 077 /** 078 * Removes the given 079 * {@link ConfigurationChangeListener} 080 * from this configuration bean. 081 * 082 * @param listener The listener to remove. 083 */ 084 public void removeListener( final ConfigurationChangeListener listener ); 085 086 /** 087 * Returns the 088 * {@link Charset} 089 * that is used throughout the program run. If it was not modified by a 090 * call to 091 * {@link #setCharset(Charset)}, 092 * this method will return the default {@code Charset} or a 093 * {@code Charset} that was previously stored as a preference value, if 094 * configured.<br> 095 * <br>The {@code Charset} cannot be set via a self-defined command line 096 * option, but through JVM options: 097 * <pre><code>java -Dfile.encoding=<<i>charset</i>> <<i>program</i>> <<i>program_options</i> …></code></pre> 098 * 099 * @return The {@code Charset}. 100 * 101 * @see Charset#defaultCharset() 102 * @see org.tquadrat.foundation.lang.CommonConstants#PROPERTY_FILE_ENCODING 103 */ 104 @SpecialProperty( CONFIG_PROPERTY_CHARSET ) 105 @ExemptFromToString 106 public Charset getCharset(); 107 108 /** 109 * Returns the locale that is used throughout the program run. If it was 110 * not modified by a call to 111 * {@link #setLocale(Locale)} 112 * this method will return the default locale or a locale that was 113 * previously stored as a preference value, if configured.<br> 114 * <br>The locale cannot be set via a self-defined command line option, 115 * but through JVM options: 116 * <pre><code>java -Duser.country=<<i>country_code</i>> -Duser.language=<<i>language_code</i>> <<i>program</i>> <<i>program_options</i> …></code></pre> 117 * 118 * @return The locale. 119 * 120 * @see Locale#getDefault() 121 * @see org.tquadrat.foundation.lang.CommonConstants#PROPERTY_USER_COUNTRY 122 * @see org.tquadrat.foundation.lang.CommonConstants#PROPERTY_USER_LANG 123 */ 124 @SpecialProperty( CONFIG_PROPERTY_LOCALE ) 125 public Locale getLocale(); 126 127 /** 128 * <p>{@summary Returns the 129 * {@link ResourceBundle} 130 * that should be used to retrieve texts and messages for the 131 * application.}</p> 132 * <p>Usually the resource bundle is set under the hood (i.e. when the 133 * configuration bean specification implements 134 * {@link org.tquadrat.foundation.config.I18nSupport I18nSupport}) 135 * or with the method {@code initData()}. But if necessary, a setter for 136 * this attribute can be added to the configuration bean specification 137 * like this:</p> 138 * <pre><code> /** 139 * * Sets the 140 * * {@link ResourceBundle} 141 * * that should be used to retrieve texts and messages for the 142 * * application.<br> 143 * * <br>As default, there is no {@code ResourceBundle} set 144 * * ({@link #getResourceBundle()} 145 * * returns 146 * * {@link Optional#empty()}), 147 * * but it not allowed to call this method with the argument {@code null} 148 * * for the {@code bundle} argument. 149 * * 150 * * @param bundle The resource bundle. 151 * */ 152 * @SpecialProperty( CONFIG_PROPERTY_RESOURCEBUNDLE ) 153 * @CheckNull 154 * public void setResourceBundle( final ResourceBundle bundle );</code></pre> 155 * 156 * @return An instance of 157 * {@link Optional} 158 * that holds the resource bundle. 159 */ 160 @SpecialProperty( CONFIG_PROPERTY_RESOURCEBUNDLE ) 161 @ExemptFromToString 162 public Optional<ResourceBundle> getResourceBundle(); 163 164 /** 165 * Returns the time zone that is used throughout the program run. If it 166 * was not modified by a call to 167 * {@link #setTimezone(ZoneId)} 168 * this method will return the default time zone or a time zone that was 169 * previously stored as a preference value, if configured.<br> 170 * <br>The time zone cannot be set via a self-defined command line option, 171 * but through JVM options: 172 * <pre><code>java -Duser.timezone=<<i>zone_id</i>> <<i>program</i>> <<i>program_options</i> …></code></pre> 173 * 174 * @return The time zone. 175 * 176 * @see ZoneId#systemDefault() 177 * @see org.tquadrat.foundation.lang.CommonConstants#PROPERTY_USER_TIMEZONE 178 */ 179 @SpecialProperty( CONFIG_PROPERTY_TIMEZONE ) 180 public ZoneId getTimezone(); 181 182 /** 183 * Returns a flag that indicates whether the application should produce 184 * debug output of some kind. 185 * 186 * @return {@code true} if the application is in debug mode, {@code false} 187 * otherwise. 188 * 189 * @see org.tquadrat.foundation.lang.CommonConstants#PROPERTY_IS_DEBUG 190 */ 191 @SystemProperty( value = PROPERTY_IS_DEBUG, defaultValue = "false" ) 192 @PropertyName( "isDebug" ) 193 public boolean isDebug(); 194 195 /** 196 * Returns a flag that indicates whether the application should produce 197 * test output of some kind. 198 * 199 * @return {@code true} if the application is in test mode, {@code false} 200 * otherwise. 201 * 202 * @see org.tquadrat.foundation.lang.CommonConstants#PROPERTY_IS_TEST 203 */ 204 @SystemProperty( value = PROPERTY_IS_TEST, defaultValue = "false" ) 205 @PropertyName( "isTest") 206 public boolean isTest(); 207 208 /** 209 * Sets the 210 * {@link Charset} 211 * that should be used throughout the program run.<br> 212 * <br>Setting a new {@code Charset} with this method will not change the 213 * system default {@code Charset}. 214 * 215 * @param charset The new {@code Charset}; if {@code null}, the 216 * {@code Charset} will be set to the default locale. 217 * 218 * @see Charset#defaultCharset() 219 */ 220 @SpecialProperty( CONFIG_PROPERTY_CHARSET ) 221 public void setCharset( final Charset charset ); 222 223 /** 224 * Sets the locale that should be used throughout the program run.<br> 225 * <br>Setting a new locale with this method will not change the system 226 * default locale. 227 * 228 * @param locale The new locale; if {@code null}, the locale will be set 229 * to the default locale. 230 * 231 * @see Locale#getDefault() 232 */ 233 @SpecialProperty( CONFIG_PROPERTY_LOCALE ) 234 public void setLocale( final Locale locale ); 235 236 /** 237 * Sets the time zone that should be used throughout the program run.<br> 238 * <br>Setting a new time zone with this method will not change the system 239 * default time zone. 240 * 241 * @param timezone The new time zone; if {@code null} the time zone 242 * will be set to the default time zone. 243 */ 244 @SpecialProperty( CONFIG_PROPERTY_TIMEZONE ) 245 public void setTimezone( final ZoneId timezone ); 246} 247// class ConfigBeanSpec 248 249/* 250 * End of File 251 */