001package io.avaje.config;
002
003import java.util.Optional;
004import java.util.Properties;
005import java.util.function.Consumer;
006
007/**
008 * Configuration API for accessing property values and registering onChange listeners.
009 */
010public interface Configuration {
011
012  /**
013   * Return the loaded properties as standard Properties map.
014   */
015  Properties asProperties();
016
017  /**
018   * Return a required configuration value as String.
019   * <p>
020   * IllegalStateException is thrown if the value is not defined in configuration.
021   * </p>
022   *
023   * @param key The configuration key
024   * @return The configured value
025   */
026  String get(String key);
027
028  /**
029   * Return a configuration string value with a given default.
030   *
031   * @param key          The configuration key
032   * @param defaultValue The default value used
033   * @return The configured or default value
034   */
035  String get(String key, String defaultValue);
036
037  /**
038   * Return a configuration value that might not exist.
039   *
040   * @param key The configuration key
041   * @return The configured value wrapped as optional
042   */
043  Optional<String> getOptional(String key);
044
045  /**
046   * Return a required boolean configuration value.
047   * <p>
048   * IllegalStateException is thrown if the value is not defined in configuration.
049   * </p>
050   *
051   * @param key The configuration key
052   * @return The configured value
053   */
054  boolean getBool(String key);
055
056  /**
057   * Return a configuration value as boolean given a default value.
058   *
059   * @param key          The configuration key
060   * @param defaultValue The default value used
061   * @return The configured or default value
062   */
063  boolean getBool(String key, boolean defaultValue);
064
065  /**
066   * Return a required int configuration value.
067   * <p>
068   * IllegalStateException is thrown if the value is not defined in configuration.
069   * </p>
070   *
071   * @param key The configuration key
072   * @return The configured value
073   */
074  int getInt(String key);
075
076  /**
077   * Return a configuration value as int given a default value.
078   *
079   * @param key          The configuration key
080   * @param defaultValue The default value used
081   * @return The configured or default value
082   */
083  int getInt(String key, int defaultValue);
084
085  /**
086   * Return a required long configuration value.
087   * <p>
088   * IllegalStateException is thrown if the value is not defined in configuration.
089   * </p>
090   *
091   * @param key The configuration key
092   * @return The configured value
093   */
094  long getLong(String key);
095
096  /**
097   * Return a configuration value as long given a default value.
098   *
099   * @param key          The configuration key
100   * @param defaultValue The default value used
101   * @return The configured or default value
102   */
103  long getLong(String key, long defaultValue);
104
105  /**
106   * Set a configuration value.
107   * <p>
108   * This will fire an configuration callback listeners that are registered
109   * for this key.
110   * </p>
111   */
112  void setProperty(String key, String value);
113
114  /**
115   * Register a callback for a change to the given configuration key.
116   *
117   * @param key      The configuration key we want to detect changes to
118   * @param callback The callback handling to fire when the configuration changes.
119   */
120  void onChange(String key, Consumer<String> callback);
121
122  /**
123   * Register a callback for a change to the given configuration key as an Int value.
124   *
125   * @param key      The configuration key we want to detect changes to
126   * @param callback The callback handling to fire when the configuration changes.
127   */
128  void onChangeInt(String key, Consumer<Integer> callback);
129
130  /**
131   * Register a callback for a change to the given configuration key as an Long value.
132   *
133   * @param key      The configuration key we want to detect changes to
134   * @param callback The callback handling to fire when the configuration changes.
135   */
136  void onChangeLong(String key, Consumer<Long> callback);
137
138  /**
139   * Register a callback for a change to the given configuration key as an Boolean value.
140   *
141   * @param key      The configuration key we want to detect changes to
142   * @param callback The callback handling to fire when the configuration changes.
143   */
144  void onChangeBool(String key, Consumer<Boolean> callback);
145
146  /**
147   * Put the loaded properties into System properties.
148   */
149  void loadIntoSystemProperties();
150
151  /**
152   * Return a copy of the properties with 'eval' run on all the values.
153   */
154  Properties eval(Properties properties);
155
156  /**
157   * Expression evaluation.
158   */
159  interface ExpressionEval {
160
161    /**
162     * Evaluate a configuration expression.
163     */
164    String eval(String expression);
165  }
166}