001/** 002 * Copyright (C) 2011-2012 Typesafe Inc. <http://typesafe.com> 003 */ 004package com.typesafe.config; 005 006import java.time.Duration; 007import java.time.Period; 008import java.time.temporal.TemporalAmount; 009import java.util.List; 010import java.util.Map; 011import java.util.Set; 012import java.util.concurrent.TimeUnit; 013 014/** 015 * An immutable map from config paths to config values. Paths are dot-separated 016 * expressions such as <code>foo.bar.baz</code>. Values are as in JSON 017 * (booleans, strings, numbers, lists, or objects), represented by 018 * {@link ConfigValue} instances. Values accessed through the 019 * <code>Config</code> interface are never null. 020 * 021 * <p> 022 * {@code Config} is an immutable object and thus safe to use from multiple 023 * threads. There's never a need for "defensive copies." 024 * 025 * <p> 026 * Fundamental operations on a {@code Config} include getting configuration 027 * values, <em>resolving</em> substitutions with {@link Config#resolve()}, and 028 * merging configs using {@link Config#withFallback(ConfigMergeable)}. 029 * 030 * <p> 031 * All operations return a new immutable {@code Config} rather than modifying 032 * the original instance. 033 * 034 * <p> 035 * <strong>Examples</strong> 036 * 037 * <p> 038 * You can find an example app and library <a 039 * href="https://github.com/lightbend/config/tree/master/examples">on 040 * GitHub</a>. Also be sure to read the <a 041 * href="package-summary.html#package_description">package overview</a> which 042 * describes the big picture as shown in those examples. 043 * 044 * <p> 045 * <strong>Paths, keys, and Config vs. ConfigObject</strong> 046 * 047 * <p> 048 * <code>Config</code> is a view onto a tree of {@link ConfigObject}; the 049 * corresponding object tree can be found through {@link Config#root()}. 050 * <code>ConfigObject</code> is a map from config <em>keys</em>, rather than 051 * paths, to config values. Think of <code>ConfigObject</code> as a JSON object 052 * and <code>Config</code> as a configuration API. 053 * 054 * <p> 055 * The API tries to consistently use the terms "key" and "path." A key is a key 056 * in a JSON object; it's just a string that's the key in a map. A "path" is a 057 * parseable expression with a syntax and it refers to a series of keys. Path 058 * expressions are described in the <a 059 * href="https://github.com/lightbend/config/blob/master/HOCON.md">spec for 060 * Human-Optimized Config Object Notation</a>. In brief, a path is 061 * period-separated so "a.b.c" looks for key c in object b in object a in the 062 * root object. Sometimes double quotes are needed around special characters in 063 * path expressions. 064 * 065 * <p> 066 * The API for a {@code Config} is in terms of path expressions, while the API 067 * for a {@code ConfigObject} is in terms of keys. Conceptually, {@code Config} 068 * is a one-level map from <em>paths</em> to values, while a 069 * {@code ConfigObject} is a tree of nested maps from <em>keys</em> to values. 070 * 071 * <p> 072 * Use {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath} to convert 073 * between path expressions and individual path elements (keys). 074 * 075 * <p> 076 * Another difference between {@code Config} and {@code ConfigObject} is that 077 * conceptually, {@code ConfigValue}s with a {@link ConfigValue#valueType() 078 * valueType()} of {@link ConfigValueType#NULL NULL} exist in a 079 * {@code ConfigObject}, while a {@code Config} treats null values as if they 080 * were missing. (With the exception of two methods: {@link Config#hasPathOrNull} 081 * and {@link Config#getIsNull} let you detect <code>null</code> values.) 082 * 083 * <p> 084 * <strong>Getting configuration values</strong> 085 * 086 * <p> 087 * The "getters" on a {@code Config} all work in the same way. They never return 088 * null, nor do they return a {@code ConfigValue} with 089 * {@link ConfigValue#valueType() valueType()} of {@link ConfigValueType#NULL 090 * NULL}. Instead, they throw {@link ConfigException.Missing} if the value is 091 * completely absent or set to null. If the value is set to null, a subtype of 092 * {@code ConfigException.Missing} called {@link ConfigException.Null} will be 093 * thrown. {@link ConfigException.WrongType} will be thrown anytime you ask for 094 * a type and the value has an incompatible type. Reasonable type conversions 095 * are performed for you though. 096 * 097 * <p> 098 * <strong>Iteration</strong> 099 * 100 * <p> 101 * If you want to iterate over the contents of a {@code Config}, you can get its 102 * {@code ConfigObject} with {@link #root()}, and then iterate over the 103 * {@code ConfigObject} (which implements <code>java.util.Map</code>). Or, you 104 * can use {@link #entrySet()} which recurses the object tree for you and builds 105 * up a <code>Set</code> of all path-value pairs where the value is not null. 106 * 107 * <p> 108 * <strong>Resolving substitutions</strong> 109 * 110 * <p> 111 * <em>Substitutions</em> are the <code>${foo.bar}</code> syntax in config 112 * files, described in the <a href= 113 * "https://github.com/lightbend/config/blob/master/HOCON.md#substitutions" 114 * >specification</a>. Resolving substitutions replaces these references with real 115 * values. 116 * 117 * <p> 118 * Before using a {@code Config} it's necessary to call {@link Config#resolve()} 119 * to handle substitutions (though {@link ConfigFactory#load()} and similar 120 * methods will do the resolve for you already). 121 * 122 * <p> 123 * <strong>Merging</strong> 124 * 125 * <p> 126 * The full <code>Config</code> for your application can be constructed using 127 * the associative operation {@link Config#withFallback(ConfigMergeable)}. If 128 * you use {@link ConfigFactory#load()} (recommended), it merges system 129 * properties over the top of <code>application.conf</code> over the top of 130 * <code>reference.conf</code>, using <code>withFallback</code>. You can add in 131 * additional sources of configuration in the same way (usually, custom layers 132 * should go either just above or just below <code>application.conf</code>, 133 * keeping <code>reference.conf</code> at the bottom and system properties at 134 * the top). 135 * 136 * <p> 137 * <strong>Serialization</strong> 138 * 139 * <p> 140 * Convert a <code>Config</code> to a JSON or HOCON string by calling 141 * {@link ConfigObject#render()} on the root object, 142 * <code>myConfig.root().render()</code>. There's also a variant 143 * {@link ConfigObject#render(ConfigRenderOptions)} which allows you to control 144 * the format of the rendered string. (See {@link ConfigRenderOptions}.) Note 145 * that <code>Config</code> does not remember the formatting of the original 146 * file, so if you load, modify, and re-save a config file, it will be 147 * substantially reformatted. 148 * 149 * <p> 150 * As an alternative to {@link ConfigObject#render()}, the 151 * <code>toString()</code> method produces a debug-output-oriented 152 * representation (which is not valid JSON). 153 * 154 * <p> 155 * Java serialization is supported as well for <code>Config</code> and all 156 * subtypes of <code>ConfigValue</code>. 157 * 158 * <p> 159 * <strong>This is an interface but don't implement it yourself</strong> 160 * 161 * <p> 162 * <em>Do not implement {@code Config}</em>; it should only be implemented by 163 * the config library. Arbitrary implementations will not work because the 164 * library internals assume a specific concrete implementation. Also, this 165 * interface is likely to grow new methods over time, so third-party 166 * implementations will break. 167 */ 168public interface Config extends ConfigMergeable { 169 /** 170 * Gets the {@code Config} as a tree of {@link ConfigObject}. This is a 171 * constant-time operation (it is not proportional to the number of values 172 * in the {@code Config}). 173 * 174 * @return the root object in the configuration 175 */ 176 ConfigObject root(); 177 178 /** 179 * Gets the origin of the {@code Config}, which may be a file, or a file 180 * with a line number, or just a descriptive phrase. 181 * 182 * @return the origin of the {@code Config} for use in error messages 183 */ 184 ConfigOrigin origin(); 185 186 @Override 187 Config withFallback(ConfigMergeable other); 188 189 /** 190 * Returns a replacement config with all substitutions (the 191 * <code>${foo.bar}</code> syntax, see <a 192 * href="https://github.com/lightbend/config/blob/master/HOCON.md">the 193 * spec</a>) resolved. Substitutions are looked up using this 194 * <code>Config</code> as the root object, that is, a substitution 195 * <code>${foo.bar}</code> will be replaced with the result of 196 * <code>getValue("foo.bar")</code>. 197 * 198 * <p> 199 * This method uses {@link ConfigResolveOptions#defaults()}, there is 200 * another variant {@link Config#resolve(ConfigResolveOptions)} which lets 201 * you specify non-default options. 202 * 203 * <p> 204 * A given {@link Config} must be resolved before using it to retrieve 205 * config values, but ideally should be resolved one time for your entire 206 * stack of fallbacks (see {@link Config#withFallback}). Otherwise, some 207 * substitutions that could have resolved with all fallbacks available may 208 * not resolve, which will be potentially confusing for your application's 209 * users. 210 * 211 * <p> 212 * <code>resolve()</code> should be invoked on root config objects, rather 213 * than on a subtree (a subtree is the result of something like 214 * <code>config.getConfig("foo")</code>). The problem with 215 * <code>resolve()</code> on a subtree is that substitutions are relative to 216 * the root of the config and the subtree will have no way to get values 217 * from the root. For example, if you did 218 * <code>config.getConfig("foo").resolve()</code> on the below config file, 219 * it would not work: 220 * 221 * <pre> 222 * common-value = 10 223 * foo { 224 * whatever = ${common-value} 225 * } 226 * </pre> 227 * 228 * <p> 229 * Many methods on {@link ConfigFactory} such as 230 * {@link ConfigFactory#load()} automatically resolve the loaded 231 * <code>Config</code> on the loaded stack of config files. 232 * 233 * <p> 234 * Resolving an already-resolved config is a harmless no-op, but again, it 235 * is best to resolve an entire stack of fallbacks (such as all your config 236 * files combined) rather than resolving each one individually. 237 * 238 * @return an immutable object with substitutions resolved 239 * @throws ConfigException.UnresolvedSubstitution 240 * if any substitutions refer to nonexistent paths 241 * @throws ConfigException 242 * some other config exception if there are other problems 243 */ 244 Config resolve(); 245 246 /** 247 * Like {@link Config#resolve()} but allows you to specify non-default 248 * options. 249 * 250 * @param options 251 * resolve options 252 * @return the resolved <code>Config</code> (may be only partially resolved if options are set to allow unresolved) 253 */ 254 Config resolve(ConfigResolveOptions options); 255 256 /** 257 * Checks whether the config is completely resolved. After a successful call 258 * to {@link Config#resolve()} it will be completely resolved, but after 259 * calling {@link Config#resolve(ConfigResolveOptions)} with 260 * <code>allowUnresolved</code> set in the options, it may or may not be 261 * completely resolved. A newly-loaded config may or may not be completely 262 * resolved depending on whether there were substitutions present in the 263 * file. 264 * 265 * @return true if there are no unresolved substitutions remaining in this 266 * configuration. 267 * @since 1.2.0 268 */ 269 boolean isResolved(); 270 271 /** 272 * Like {@link Config#resolve()} except that substitution values are looked 273 * up in the given source, rather than in this instance. This is a 274 * special-purpose method which doesn't make sense to use in most cases; 275 * it's only needed if you're constructing some sort of app-specific custom 276 * approach to configuration. The more usual approach if you have a source 277 * of substitution values would be to merge that source into your config 278 * stack using {@link Config#withFallback} and then resolve. 279 * <p> 280 * Note that this method does NOT look in this instance for substitution 281 * values. If you want to do that, you could either merge this instance into 282 * your value source using {@link Config#withFallback}, or you could resolve 283 * multiple times with multiple sources (using 284 * {@link ConfigResolveOptions#setAllowUnresolved(boolean)} so the partial 285 * resolves don't fail). 286 * 287 * @param source 288 * configuration to pull values from 289 * @return an immutable object with substitutions resolved 290 * @throws ConfigException.UnresolvedSubstitution 291 * if any substitutions refer to paths which are not in the 292 * source 293 * @throws ConfigException 294 * some other config exception if there are other problems 295 * @since 1.2.0 296 */ 297 Config resolveWith(Config source); 298 299 /** 300 * Like {@link Config#resolveWith(Config)} but allows you to specify 301 * non-default options. 302 * 303 * @param source 304 * source configuration to pull values from 305 * @param options 306 * resolve options 307 * @return the resolved <code>Config</code> (may be only partially resolved 308 * if options are set to allow unresolved) 309 * @since 1.2.0 310 */ 311 Config resolveWith(Config source, ConfigResolveOptions options); 312 313 /** 314 * Validates this config against a reference config, throwing an exception 315 * if it is invalid. The purpose of this method is to "fail early" with a 316 * comprehensive list of problems; in general, anything this method can find 317 * would be detected later when trying to use the config, but it's often 318 * more user-friendly to fail right away when loading the config. 319 * 320 * <p> 321 * Using this method is always optional, since you can "fail late" instead. 322 * 323 * <p> 324 * You must restrict validation to paths you "own" (those whose meaning are 325 * defined by your code module). If you validate globally, you may trigger 326 * errors about paths that happen to be in the config but have nothing to do 327 * with your module. It's best to allow the modules owning those paths to 328 * validate them. Also, if every module validates only its own stuff, there 329 * isn't as much redundant work being done. 330 * 331 * <p> 332 * If no paths are specified in <code>checkValid()</code>'s parameter list, 333 * validation is for the entire config. 334 * 335 * <p> 336 * If you specify paths that are not in the reference config, those paths 337 * are ignored. (There's nothing to validate.) 338 * 339 * <p> 340 * Here's what validation involves: 341 * 342 * <ul> 343 * <li>All paths found in the reference config must be present in this 344 * config or an exception will be thrown. 345 * <li> 346 * Some changes in type from the reference config to this config will cause 347 * an exception to be thrown. Not all potential type problems are detected, 348 * in particular it's assumed that strings are compatible with everything 349 * except objects and lists. This is because string types are often "really" 350 * some other type (system properties always start out as strings, or a 351 * string like "5ms" could be used with {@link #getMilliseconds}). Also, 352 * it's allowed to set any type to null or override null with any type. 353 * <li> 354 * Any unresolved substitutions in this config will cause a validation 355 * failure; both the reference config and this config should be resolved 356 * before validation. If the reference config is unresolved, it's a bug in 357 * the caller of this method. 358 * </ul> 359 * 360 * <p> 361 * If you want to allow a certain setting to have a flexible type (or 362 * otherwise want validation to be looser for some settings), you could 363 * either remove the problematic setting from the reference config provided 364 * to this method, or you could intercept the validation exception and 365 * screen out certain problems. Of course, this will only work if all other 366 * callers of this method are careful to restrict validation to their own 367 * paths, as they should be. 368 * 369 * <p> 370 * If validation fails, the thrown exception contains a list of all problems 371 * found. See {@link ConfigException.ValidationFailed#problems}. The 372 * exception's <code>getMessage()</code> will have all the problems 373 * concatenated into one huge string, as well. 374 * 375 * <p> 376 * Again, <code>checkValid()</code> can't guess every domain-specific way a 377 * setting can be invalid, so some problems may arise later when attempting 378 * to use the config. <code>checkValid()</code> is limited to reporting 379 * generic, but common, problems such as missing settings and blatant type 380 * incompatibilities. 381 * 382 * @param reference 383 * a reference configuration 384 * @param restrictToPaths 385 * only validate values underneath these paths that your code 386 * module owns and understands 387 * @throws ConfigException.ValidationFailed 388 * if there are any validation issues 389 * @throws ConfigException.NotResolved 390 * if this config is not resolved 391 * @throws ConfigException.BugOrBroken 392 * if the reference config is unresolved or caller otherwise 393 * misuses the API 394 */ 395 void checkValid(Config reference, String... restrictToPaths); 396 397 /** 398 * Checks whether a value is present and non-null at the given path. This 399 * differs in two ways from {@code Map.containsKey()} as implemented by 400 * {@link ConfigObject}: it looks for a path expression, not a key; and it 401 * returns false for null values, while {@code containsKey()} returns true 402 * indicating that the object contains a null value for the key. 403 * 404 * <p> 405 * If a path exists according to {@link #hasPath(String)}, then 406 * {@link #getValue(String)} will never throw an exception. However, the 407 * typed getters, such as {@link #getInt(String)}, will still throw if the 408 * value is not convertible to the requested type. 409 * 410 * <p> 411 * Note that path expressions have a syntax and sometimes require quoting 412 * (see {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}). 413 * 414 * @param path 415 * the path expression 416 * @return true if a non-null value is present at the path 417 * @throws ConfigException.BadPath 418 * if the path expression is invalid 419 */ 420 boolean hasPath(String path); 421 422 /** 423 * Checks whether a value is present at the given path, even 424 * if the value is null. Most of the getters on 425 * <code>Config</code> will throw if you try to get a null 426 * value, so if you plan to call {@link #getValue(String)}, 427 * {@link #getInt(String)}, or another getter you may want to 428 * use plain {@link #hasPath(String)} rather than this method. 429 * 430 * <p> 431 * To handle all three cases (unset, null, and a non-null value) 432 * the code might look like: 433 * <pre><code> 434 * if (config.hasPathOrNull(path)) { 435 * if (config.getIsNull(path)) { 436 * // handle null setting 437 * } else { 438 * // get and use non-null setting 439 * } 440 * } else { 441 * // handle entirely unset path 442 * } 443 * </code></pre> 444 * 445 * <p> However, the usual thing is to allow entirely unset 446 * paths to be a bug that throws an exception (because you set 447 * a default in your <code>reference.conf</code>), so in that 448 * case it's OK to call {@link #getIsNull(String)} without 449 * checking <code>hasPathOrNull</code> first. 450 * 451 * <p> 452 * Note that path expressions have a syntax and sometimes require quoting 453 * (see {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}). 454 * 455 * @param path 456 * the path expression 457 * @return true if a value is present at the path, even if the value is null 458 * @throws ConfigException.BadPath 459 * if the path expression is invalid 460 */ 461 boolean hasPathOrNull(String path); 462 463 /** 464 * Returns true if the {@code Config}'s root object contains no key-value 465 * pairs. 466 * 467 * @return true if the configuration is empty 468 */ 469 boolean isEmpty(); 470 471 /** 472 * Returns the set of path-value pairs, excluding any null values, found by 473 * recursing {@link #root() the root object}. Note that this is very 474 * different from <code>root().entrySet()</code> which returns the set of 475 * immediate-child keys in the root object and includes null values. 476 * <p> 477 * Entries contain <em>path expressions</em> meaning there may be quoting 478 * and escaping involved. Parse path expressions with 479 * {@link ConfigUtil#splitPath}. 480 * <p> 481 * Because a <code>Config</code> is conceptually a single-level map from 482 * paths to values, there will not be any {@link ConfigObject} values in the 483 * entries (that is, all entries represent leaf nodes). Use 484 * {@link ConfigObject} rather than <code>Config</code> if you want a tree. 485 * (OK, this is a slight lie: <code>Config</code> entries may contain 486 * {@link ConfigList} and the lists may contain objects. But no objects are 487 * directly included as entry values.) 488 * 489 * @return set of paths with non-null values, built up by recursing the 490 * entire tree of {@link ConfigObject} and creating an entry for 491 * each leaf value. 492 */ 493 Set<Map.Entry<String, ConfigValue>> entrySet(); 494 495 /** 496 * Checks whether a value is set to null at the given path, 497 * but throws an exception if the value is entirely 498 * unset. This method will not throw if {@link 499 * #hasPathOrNull(String)} returned true for the same path, so 500 * to avoid any possible exception check 501 * <code>hasPathOrNull()</code> first. However, an exception 502 * for unset paths will usually be the right thing (because a 503 * <code>reference.conf</code> should exist that has the path 504 * set, the path should never be unset unless something is 505 * broken). 506 * 507 * <p> 508 * Note that path expressions have a syntax and sometimes require quoting 509 * (see {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}). 510 * 511 * @param path 512 * the path expression 513 * @return true if the value exists and is null, false if it 514 * exists and is not null 515 * @throws ConfigException.BadPath 516 * if the path expression is invalid 517 * @throws ConfigException.Missing 518 * if value is not set at all 519 */ 520 boolean getIsNull(String path); 521 522 /** 523 * 524 * @param path 525 * path expression 526 * @return the boolean value at the requested path 527 * @throws ConfigException.Missing 528 * if value is absent or null 529 * @throws ConfigException.WrongType 530 * if value is not convertible to boolean 531 */ 532 boolean getBoolean(String path); 533 534 /** 535 * @param path 536 * path expression 537 * @return the numeric value at the requested path 538 * @throws ConfigException.Missing 539 * if value is absent or null 540 * @throws ConfigException.WrongType 541 * if value is not convertible to a number 542 */ 543 Number getNumber(String path); 544 545 /** 546 * Gets the integer at the given path. If the value at the 547 * path has a fractional (floating point) component, it 548 * will be discarded and only the integer part will be 549 * returned (it works like a "narrowing primitive conversion" 550 * in the Java language specification). 551 * 552 * @param path 553 * path expression 554 * @return the 32-bit integer value at the requested path 555 * @throws ConfigException.Missing 556 * if value is absent or null 557 * @throws ConfigException.WrongType 558 * if value is not convertible to an int (for example it is out 559 * of range, or it's a boolean value) 560 */ 561 int getInt(String path); 562 563 /** 564 * Gets the long integer at the given path. If the value at 565 * the path has a fractional (floating point) component, it 566 * will be discarded and only the integer part will be 567 * returned (it works like a "narrowing primitive conversion" 568 * in the Java language specification). 569 * 570 * @param path 571 * path expression 572 * @return the 64-bit long value at the requested path 573 * @throws ConfigException.Missing 574 * if value is absent or null 575 * @throws ConfigException.WrongType 576 * if value is not convertible to a long 577 */ 578 long getLong(String path); 579 580 /** 581 * @param path 582 * path expression 583 * @return the floating-point value at the requested path 584 * @throws ConfigException.Missing 585 * if value is absent or null 586 * @throws ConfigException.WrongType 587 * if value is not convertible to a double 588 */ 589 double getDouble(String path); 590 591 /** 592 * @param path 593 * path expression 594 * @return the string value at the requested path 595 * @throws ConfigException.Missing 596 * if value is absent or null 597 * @throws ConfigException.WrongType 598 * if value is not convertible to a string 599 */ 600 String getString(String path); 601 602 /** 603 * @param enumClass 604 * an enum class 605 * @param <T> 606 * a generic denoting a specific type of enum 607 * @param path 608 * path expression 609 * @return the {@code Enum} value at the requested path 610 * of the requested enum class 611 * @throws ConfigException.Missing 612 * if value is absent or null 613 * @throws ConfigException.WrongType 614 * if value is not convertible to an Enum 615 */ 616 public <T extends Enum<T>> T getEnum(Class<T> enumClass, String path); 617 618 /** 619 * @param path 620 * path expression 621 * @return the {@link ConfigObject} value at the requested path 622 * @throws ConfigException.Missing 623 * if value is absent or null 624 * @throws ConfigException.WrongType 625 * if value is not convertible to an object 626 */ 627 ConfigObject getObject(String path); 628 629 /** 630 * @param path 631 * path expression 632 * @return the nested {@code Config} value at the requested path 633 * @throws ConfigException.Missing 634 * if value is absent or null 635 * @throws ConfigException.WrongType 636 * if value is not convertible to a Config 637 */ 638 Config getConfig(String path); 639 640 /** 641 * Gets the value at the path as an unwrapped Java boxed value ( 642 * {@link java.lang.Boolean Boolean}, {@link java.lang.Integer Integer}, and 643 * so on - see {@link ConfigValue#unwrapped()}). 644 * 645 * @param path 646 * path expression 647 * @return the unwrapped value at the requested path 648 * @throws ConfigException.Missing 649 * if value is absent or null 650 */ 651 Object getAnyRef(String path); 652 653 /** 654 * Gets the value at the given path, unless the value is a 655 * null value or missing, in which case it throws just like 656 * the other getters. Use {@code get()} on the {@link 657 * Config#root()} object (or other object in the tree) if you 658 * want an unprocessed value. 659 * 660 * @param path 661 * path expression 662 * @return the value at the requested path 663 * @throws ConfigException.Missing 664 * if value is absent or null 665 */ 666 ConfigValue getValue(String path); 667 668 /** 669 * Gets a value as a size in bytes (parses special strings like "128M"). If 670 * the value is already a number, then it's left alone; if it's a string, 671 * it's parsed understanding unit suffixes such as "128K", as documented in 672 * the <a 673 * href="https://github.com/lightbend/config/blob/master/HOCON.md">the 674 * spec</a>. 675 * 676 * @param path 677 * path expression 678 * @return the value at the requested path, in bytes 679 * @throws ConfigException.Missing 680 * if value is absent or null 681 * @throws ConfigException.WrongType 682 * if value is not convertible to Long or String 683 * @throws ConfigException.BadValue 684 * if value cannot be parsed as a size in bytes 685 */ 686 Long getBytes(String path); 687 688 /** 689 * Gets a value as an amount of memory (parses special strings like "128M"). If 690 * the value is already a number, then it's left alone; if it's a string, 691 * it's parsed understanding unit suffixes such as "128K", as documented in 692 * the <a 693 * href="https://github.com/lightbend/config/blob/master/HOCON.md">the 694 * spec</a>. 695 * 696 * @since 1.3.0 697 * 698 * @param path 699 * path expression 700 * @return the value at the requested path, in bytes 701 * @throws ConfigException.Missing 702 * if value is absent or null 703 * @throws ConfigException.WrongType 704 * if value is not convertible to Long or String 705 * @throws ConfigException.BadValue 706 * if value cannot be parsed as a size in bytes 707 */ 708 ConfigMemorySize getMemorySize(String path); 709 710 /** 711 * Get value as a duration in milliseconds. If the value is already a 712 * number, then it's left alone; if it's a string, it's parsed understanding 713 * units suffixes like "10m" or "5ns" as documented in the <a 714 * href="https://github.com/lightbend/config/blob/master/HOCON.md">the 715 * spec</a>. 716 * 717 * @deprecated As of release 1.1, replaced by {@link #getDuration(String, TimeUnit)} 718 * 719 * @param path 720 * path expression 721 * @return the duration value at the requested path, in milliseconds 722 * @throws ConfigException.Missing 723 * if value is absent or null 724 * @throws ConfigException.WrongType 725 * if value is not convertible to Long or String 726 * @throws ConfigException.BadValue 727 * if value cannot be parsed as a number of milliseconds 728 */ 729 @Deprecated Long getMilliseconds(String path); 730 731 /** 732 * Get value as a duration in nanoseconds. If the value is already a number 733 * it's taken as milliseconds and converted to nanoseconds. If it's a 734 * string, it's parsed understanding unit suffixes, as for 735 * {@link #getDuration(String, TimeUnit)}. 736 * 737 * @deprecated As of release 1.1, replaced by {@link #getDuration(String, TimeUnit)} 738 * 739 * @param path 740 * path expression 741 * @return the duration value at the requested path, in nanoseconds 742 * @throws ConfigException.Missing 743 * if value is absent or null 744 * @throws ConfigException.WrongType 745 * if value is not convertible to Long or String 746 * @throws ConfigException.BadValue 747 * if value cannot be parsed as a number of nanoseconds 748 */ 749 @Deprecated Long getNanoseconds(String path); 750 751 /** 752 * Gets a value as a duration in a specified 753 * {@link java.util.concurrent.TimeUnit TimeUnit}. If the value is already a 754 * number, then it's taken as milliseconds and then converted to the 755 * requested TimeUnit; if it's a string, it's parsed understanding units 756 * suffixes like "10m" or "5ns" as documented in the <a 757 * href="https://github.com/lightbend/config/blob/master/HOCON.md">the 758 * spec</a>. 759 * 760 * @since 1.2.0 761 * 762 * @param path 763 * path expression 764 * @param unit 765 * convert the return value to this time unit 766 * @return the duration value at the requested path, in the given TimeUnit 767 * @throws ConfigException.Missing 768 * if value is absent or null 769 * @throws ConfigException.WrongType 770 * if value is not convertible to Long or String 771 * @throws ConfigException.BadValue 772 * if value cannot be parsed as a number of the given TimeUnit 773 */ 774 long getDuration(String path, TimeUnit unit); 775 776 /** 777 * Gets a value as a java.time.Duration. If the value is 778 * already a number, then it's taken as milliseconds; if it's 779 * a string, it's parsed understanding units suffixes like 780 * "10m" or "5ns" as documented in the <a 781 * href="https://github.com/lightbend/config/blob/master/HOCON.md">the 782 * spec</a>. This method never returns null. 783 * 784 * @since 1.3.0 785 * 786 * @param path 787 * path expression 788 * @return the duration value at the requested path 789 * @throws ConfigException.Missing 790 * if value is absent or null 791 * @throws ConfigException.WrongType 792 * if value is not convertible to Long or String 793 * @throws ConfigException.BadValue 794 * if value cannot be parsed as a number of the given TimeUnit 795 */ 796 Duration getDuration(String path); 797 798 /** 799 * Gets a value as a java.time.Period. If the value is 800 * already a number, then it's taken as days; if it's 801 * a string, it's parsed understanding units suffixes like 802 * "10d" or "5w" as documented in the <a 803 * href="https://github.com/lightbend/config/blob/master/HOCON.md">the 804 * spec</a>. This method never returns null. 805 * 806 * @since 1.3.0 807 * 808 * @param path 809 * path expression 810 * @return the period value at the requested path 811 * @throws ConfigException.Missing 812 * if value is absent or null 813 * @throws ConfigException.WrongType 814 * if value is not convertible to Long or String 815 * @throws ConfigException.BadValue 816 * if value cannot be parsed as a number of the given TimeUnit 817 */ 818 Period getPeriod(String path); 819 820 /** 821 * Gets a value as a java.time.temporal.TemporalAmount. 822 * This method will first try get get the value as a java.time.Duration, and if unsuccessful, 823 * then as a java.time.Period. 824 * This means that values like "5m" will be parsed as 5 minutes rather than 5 months 825 * @param path path expression 826 * @return the temporal value at the requested path 827 * @throws ConfigException.Missing 828 * if value is absent or null 829 * @throws ConfigException.WrongType 830 * if value is not convertible to Long or String 831 * @throws ConfigException.BadValue 832 * if value cannot be parsed as a TemporalAmount 833 */ 834 TemporalAmount getTemporal(String path); 835 836 /** 837 * Gets a list value (with any element type) as a {@link ConfigList}, which 838 * implements {@code java.util.List<ConfigValue>}. Throws if the path is 839 * unset or null. 840 * 841 * @param path 842 * the path to the list value. 843 * @return the {@link ConfigList} at the path 844 * @throws ConfigException.Missing 845 * if value is absent or null 846 * @throws ConfigException.WrongType 847 * if value is not convertible to a ConfigList 848 */ 849 ConfigList getList(String path); 850 851 /** 852 * Gets a list value with boolean elements. Throws if the 853 * path is unset or null or not a list or contains values not 854 * convertible to boolean. 855 * 856 * @param path 857 * the path to the list value. 858 * @return the list at the path 859 * @throws ConfigException.Missing 860 * if value is absent or null 861 * @throws ConfigException.WrongType 862 * if value is not convertible to a list of booleans 863 */ 864 List<Boolean> getBooleanList(String path); 865 866 /** 867 * Gets a list value with number elements. Throws if the 868 * path is unset or null or not a list or contains values not 869 * convertible to number. 870 * 871 * @param path 872 * the path to the list value. 873 * @return the list at the path 874 * @throws ConfigException.Missing 875 * if value is absent or null 876 * @throws ConfigException.WrongType 877 * if value is not convertible to a list of numbers 878 */ 879 List<Number> getNumberList(String path); 880 881 /** 882 * Gets a list value with int elements. Throws if the 883 * path is unset or null or not a list or contains values not 884 * convertible to int. 885 * 886 * @param path 887 * the path to the list value. 888 * @return the list at the path 889 * @throws ConfigException.Missing 890 * if value is absent or null 891 * @throws ConfigException.WrongType 892 * if value is not convertible to a list of ints 893 */ 894 List<Integer> getIntList(String path); 895 896 /** 897 * Gets a list value with long elements. Throws if the 898 * path is unset or null or not a list or contains values not 899 * convertible to long. 900 * 901 * @param path 902 * the path to the list value. 903 * @return the list at the path 904 * @throws ConfigException.Missing 905 * if value is absent or null 906 * @throws ConfigException.WrongType 907 * if value is not convertible to a list of longs 908 */ 909 List<Long> getLongList(String path); 910 911 /** 912 * Gets a list value with double elements. Throws if the 913 * path is unset or null or not a list or contains values not 914 * convertible to double. 915 * 916 * @param path 917 * the path to the list value. 918 * @return the list at the path 919 * @throws ConfigException.Missing 920 * if value is absent or null 921 * @throws ConfigException.WrongType 922 * if value is not convertible to a list of doubles 923 */ 924 List<Double> getDoubleList(String path); 925 926 /** 927 * Gets a list value with string elements. Throws if the 928 * path is unset or null or not a list or contains values not 929 * convertible to string. 930 * 931 * @param path 932 * the path to the list value. 933 * @return the list at the path 934 * @throws ConfigException.Missing 935 * if value is absent or null 936 * @throws ConfigException.WrongType 937 * if value is not convertible to a list of strings 938 */ 939 List<String> getStringList(String path); 940 941 /** 942 * Gets a list value with {@code Enum} elements. Throws if the 943 * path is unset or null or not a list or contains values not 944 * convertible to {@code Enum}. 945 * 946 * @param enumClass 947 * the enum class 948 * @param <T> 949 * a generic denoting a specific type of enum 950 * @param path 951 * the path to the list value. 952 * @return the list at the path 953 * @throws ConfigException.Missing 954 * if value is absent or null 955 * @throws ConfigException.WrongType 956 * if value is not convertible to a list of {@code Enum} 957 */ 958 <T extends Enum<T>> List<T> getEnumList(Class<T> enumClass, String path); 959 960 /** 961 * Gets a list value with object elements. Throws if the 962 * path is unset or null or not a list or contains values not 963 * convertible to <code>ConfigObject</code>. 964 * 965 * @param path 966 * the path to the list value. 967 * @return the list at the path 968 * @throws ConfigException.Missing 969 * if value is absent or null 970 * @throws ConfigException.WrongType 971 * if value is not convertible to a list of objects 972 */ 973 List<? extends ConfigObject> getObjectList(String path); 974 975 /** 976 * Gets a list value with <code>Config</code> elements. 977 * Throws if the path is unset or null or not a list or 978 * contains values not convertible to <code>Config</code>. 979 * 980 * @param path 981 * the path to the list value. 982 * @return the list at the path 983 * @throws ConfigException.Missing 984 * if value is absent or null 985 * @throws ConfigException.WrongType 986 * if value is not convertible to a list of configs 987 */ 988 List<? extends Config> getConfigList(String path); 989 990 /** 991 * Gets a list value with any kind of elements. Throws if the 992 * path is unset or null or not a list. Each element is 993 * "unwrapped" (see {@link ConfigValue#unwrapped()}). 994 * 995 * @param path 996 * the path to the list value. 997 * @return the list at the path 998 * @throws ConfigException.Missing 999 * if value is absent or null 1000 * @throws ConfigException.WrongType 1001 * if value is not convertible to a list 1002 */ 1003 List<? extends Object> getAnyRefList(String path); 1004 1005 /** 1006 * Gets a list value with elements representing a size in 1007 * bytes. Throws if the path is unset or null or not a list 1008 * or contains values not convertible to memory sizes. 1009 * 1010 * @param path 1011 * the path to the list value. 1012 * @return the list at the path 1013 * @throws ConfigException.Missing 1014 * if value is absent or null 1015 * @throws ConfigException.WrongType 1016 * if value is not convertible to a list of memory sizes 1017 */ 1018 List<Long> getBytesList(String path); 1019 1020 /** 1021 * Gets a list, converting each value in the list to a memory size, using the 1022 * same rules as {@link #getMemorySize(String)}. 1023 * 1024 * @since 1.3.0 1025 * @param path 1026 * a path expression 1027 * @return list of memory sizes 1028 * @throws ConfigException.Missing 1029 * if value is absent or null 1030 * @throws ConfigException.WrongType 1031 * if value is not convertible to a list of memory sizes 1032 */ 1033 List<ConfigMemorySize> getMemorySizeList(String path); 1034 1035 /** 1036 * @deprecated As of release 1.1, replaced by {@link #getDurationList(String, TimeUnit)} 1037 * @param path the path 1038 * @return list of millisecond values 1039 */ 1040 @Deprecated List<Long> getMillisecondsList(String path); 1041 1042 /** 1043 * @deprecated As of release 1.1, replaced by {@link #getDurationList(String, TimeUnit)} 1044 * @param path the path 1045 * @return list of nanosecond values 1046 */ 1047 @Deprecated List<Long> getNanosecondsList(String path); 1048 1049 /** 1050 * Gets a list, converting each value in the list to a duration, using the 1051 * same rules as {@link #getDuration(String, TimeUnit)}. 1052 * 1053 * @since 1.2.0 1054 * @param path 1055 * a path expression 1056 * @param unit 1057 * time units of the returned values 1058 * @return list of durations, in the requested units 1059 */ 1060 List<Long> getDurationList(String path, TimeUnit unit); 1061 1062 /** 1063 * Gets a list, converting each value in the list to a duration, using the 1064 * same rules as {@link #getDuration(String)}. 1065 * 1066 * @since 1.3.0 1067 * @param path 1068 * a path expression 1069 * @return list of durations 1070 */ 1071 List<Duration> getDurationList(String path); 1072 1073 /** 1074 * Clone the config with only the given path (and its children) retained; 1075 * all sibling paths are removed. 1076 * <p> 1077 * Note that path expressions have a syntax and sometimes require quoting 1078 * (see {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}). 1079 * 1080 * @param path 1081 * path to keep 1082 * @return a copy of the config minus all paths except the one specified 1083 */ 1084 Config withOnlyPath(String path); 1085 1086 /** 1087 * Clone the config with the given path removed. 1088 * <p> 1089 * Note that path expressions have a syntax and sometimes require quoting 1090 * (see {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}). 1091 * 1092 * @param path 1093 * path expression to remove 1094 * @return a copy of the config minus the specified path 1095 */ 1096 Config withoutPath(String path); 1097 1098 /** 1099 * Places the config inside another {@code Config} at the given path. 1100 * <p> 1101 * Note that path expressions have a syntax and sometimes require quoting 1102 * (see {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}). 1103 * 1104 * @param path 1105 * path expression to store this config at. 1106 * @return a {@code Config} instance containing this config at the given 1107 * path. 1108 */ 1109 Config atPath(String path); 1110 1111 /** 1112 * Places the config inside a {@code Config} at the given key. See also 1113 * atPath(). Note that a key is NOT a path expression (see 1114 * {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}). 1115 * 1116 * @param key 1117 * key to store this config at. 1118 * @return a {@code Config} instance containing this config at the given 1119 * key. 1120 */ 1121 Config atKey(String key); 1122 1123 /** 1124 * Returns a {@code Config} based on this one, but with the given path set 1125 * to the given value. Does not modify this instance (since it's immutable). 1126 * If the path already has a value, that value is replaced. To remove a 1127 * value, use withoutPath(). 1128 * <p> 1129 * Note that path expressions have a syntax and sometimes require quoting 1130 * (see {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}). 1131 * 1132 * @param path 1133 * path expression for the value's new location 1134 * @param value 1135 * value at the new path 1136 * @return the new instance with the new map entry 1137 */ 1138 Config withValue(String path, ConfigValue value); 1139}