001/** 002 * Copyright (C) 2011-2012 Typesafe Inc. <http://typesafe.com> 003 */ 004package com.typesafe.config; 005 006import java.io.File; 007import java.io.Reader; 008import java.net.MalformedURLException; 009import java.net.URL; 010import java.util.Map; 011import java.util.Properties; 012import java.util.concurrent.Callable; 013 014import com.typesafe.config.impl.ConfigImpl; 015import com.typesafe.config.impl.Parseable; 016 017/** 018 * Contains static methods for creating {@link Config} instances. 019 * 020 * <p> 021 * See also {@link ConfigValueFactory} which contains static methods for 022 * converting Java values into a {@link ConfigObject}. You can then convert a 023 * {@code ConfigObject} into a {@code Config} with {@link ConfigObject#toConfig}. 024 * 025 * <p> 026 * The static methods with "load" in the name do some sort of higher-level 027 * operation potentially parsing multiple resources and resolving substitutions, 028 * while the ones with "parse" in the name just create a {@link ConfigValue} 029 * from a resource and nothing else. 030 * 031 * <p> You can find an example app and library <a 032 * href="https://github.com/typesafehub/config/tree/master/examples">on 033 * GitHub</a>. Also be sure to read the <a 034 * href="package-summary.html#package_description">package 035 * overview</a> which describes the big picture as shown in those 036 * examples. 037 */ 038public final class ConfigFactory { 039 private ConfigFactory() { 040 } 041 042 /** 043 * Loads an application's configuration from the given classpath resource or 044 * classpath resource basename, sandwiches it between default reference 045 * config and default overrides, and then resolves it. The classpath 046 * resource is "raw" (it should have no "/" prefix, and is not made relative 047 * to any package, so it's like {@link ClassLoader#getResource} not 048 * {@link Class#getResource}). 049 * 050 * <p> 051 * Resources are loaded from the current thread's 052 * {@link Thread#getContextClassLoader()}. In general, a library needs its 053 * configuration to come from the class loader used to load that library, so 054 * the proper "reference.conf" are present. 055 * 056 * <p> 057 * The loaded object will already be resolved (substitutions have already 058 * been processed). As a result, if you add more fallbacks then they won't 059 * be seen by substitutions. Substitutions are the "${foo.bar}" syntax. If 060 * you want to parse additional files or something then you need to use 061 * {@link #load(Config)}. 062 * 063 * <p> 064 * To load a standalone resource (without the default reference and default 065 * overrides), use {@link #parseResourcesAnySyntax(String)} rather than this 066 * method. To load only the reference config use {@link #defaultReference()} 067 * and to load only the overrides use {@link #defaultOverrides()}. 068 * 069 * @param resourceBasename 070 * name (optionally without extension) of a resource on classpath 071 * @return configuration for an application relative to context class loader 072 */ 073 public static Config load(String resourceBasename) { 074 return load(resourceBasename, ConfigParseOptions.defaults(), 075 ConfigResolveOptions.defaults()); 076 } 077 078 /** 079 * Like {@link #load(String)} but uses the supplied class loader instead of 080 * the current thread's context class loader. 081 * 082 * <p> 083 * To load a standalone resource (without the default reference and default 084 * overrides), use {@link #parseResourcesAnySyntax(ClassLoader, String)} 085 * rather than this method. To load only the reference config use 086 * {@link #defaultReference(ClassLoader)} and to load only the overrides use 087 * {@link #defaultOverrides(ClassLoader)}. 088 * 089 * @param loader class loader to look for resources in 090 * @param resourceBasename basename (no .conf/.json/.properties suffix) 091 * @return configuration for an application relative to given class loader 092 */ 093 public static Config load(ClassLoader loader, String resourceBasename) { 094 return load(resourceBasename, ConfigParseOptions.defaults().setClassLoader(loader), 095 ConfigResolveOptions.defaults()); 096 } 097 098 /** 099 * Like {@link #load(String)} but allows you to specify parse and resolve 100 * options. 101 * 102 * @param resourceBasename 103 * the classpath resource name with optional extension 104 * @param parseOptions 105 * options to use when parsing the resource 106 * @param resolveOptions 107 * options to use when resolving the stack 108 * @return configuration for an application 109 */ 110 public static Config load(String resourceBasename, ConfigParseOptions parseOptions, 111 ConfigResolveOptions resolveOptions) { 112 ConfigParseOptions withLoader = ensureClassLoader(parseOptions, "load"); 113 Config appConfig = ConfigFactory.parseResourcesAnySyntax(resourceBasename, withLoader); 114 return load(withLoader.getClassLoader(), appConfig, resolveOptions); 115 } 116 117 /** 118 * Like {@link #load(String,ConfigParseOptions,ConfigResolveOptions)} but 119 * has a class loader parameter that overrides any from the 120 * {@code ConfigParseOptions}. 121 * 122 * @param loader 123 * class loader in which to find resources (overrides loader in 124 * parse options) 125 * @param resourceBasename 126 * the classpath resource name with optional extension 127 * @param parseOptions 128 * options to use when parsing the resource (class loader 129 * overridden) 130 * @param resolveOptions 131 * options to use when resolving the stack 132 * @return configuration for an application 133 */ 134 public static Config load(ClassLoader loader, String resourceBasename, 135 ConfigParseOptions parseOptions, ConfigResolveOptions resolveOptions) { 136 return load(resourceBasename, parseOptions.setClassLoader(loader), resolveOptions); 137 } 138 139 private static ClassLoader checkedContextClassLoader(String methodName) { 140 ClassLoader loader = Thread.currentThread().getContextClassLoader(); 141 if (loader == null) 142 throw new ConfigException.BugOrBroken("Context class loader is not set for the current thread; " 143 + "if Thread.currentThread().getContextClassLoader() returns null, you must pass a ClassLoader " 144 + "explicitly to ConfigFactory." + methodName); 145 else 146 return loader; 147 } 148 149 private static ConfigParseOptions ensureClassLoader(ConfigParseOptions options, String methodName) { 150 if (options.getClassLoader() == null) 151 return options.setClassLoader(checkedContextClassLoader(methodName)); 152 else 153 return options; 154 } 155 156 /** 157 * Assembles a standard configuration using a custom <code>Config</code> 158 * object rather than loading "application.conf". The <code>Config</code> 159 * object will be sandwiched between the default reference config and 160 * default overrides and then resolved. 161 * 162 * @param config 163 * the application's portion of the configuration 164 * @return resolved configuration with overrides and fallbacks added 165 */ 166 public static Config load(Config config) { 167 return load(checkedContextClassLoader("load"), config); 168 } 169 170 /** 171 * Like {@link #load(Config)} but allows you to specify 172 * the class loader for looking up resources. 173 * 174 * @param loader 175 * the class loader to use to find resources 176 * @param config 177 * the application's portion of the configuration 178 * @return resolved configuration with overrides and fallbacks added 179 */ 180 public static Config load(ClassLoader loader, Config config) { 181 return load(loader, config, ConfigResolveOptions.defaults()); 182 } 183 184 /** 185 * Like {@link #load(Config)} but allows you to specify 186 * {@link ConfigResolveOptions}. 187 * 188 * @param config 189 * the application's portion of the configuration 190 * @param resolveOptions 191 * options for resolving the assembled config stack 192 * @return resolved configuration with overrides and fallbacks added 193 */ 194 public static Config load(Config config, ConfigResolveOptions resolveOptions) { 195 return load(checkedContextClassLoader("load"), config, resolveOptions); 196 } 197 198 /** 199 * Like {@link #load(Config,ConfigResolveOptions)} but allows you to specify 200 * a class loader other than the context class loader. 201 * 202 * @param loader 203 * class loader to use when looking up override and reference 204 * configs 205 * @param config 206 * the application's portion of the configuration 207 * @param resolveOptions 208 * options for resolving the assembled config stack 209 * @return resolved configuration with overrides and fallbacks added 210 */ 211 public static Config load(ClassLoader loader, Config config, ConfigResolveOptions resolveOptions) { 212 return defaultOverrides(loader).withFallback(config).withFallback(defaultReference(loader)) 213 .resolve(resolveOptions); 214 } 215 216 private static Config parseApplicationConfig(ConfigParseOptions parseOptions) { 217 ClassLoader loader = parseOptions.getClassLoader(); 218 if (loader == null) 219 throw new ConfigException.BugOrBroken( 220 "ClassLoader should have been set here; bug in ConfigFactory. " 221 + "(You can probably work around this bug by passing in a class loader or calling currentThread().setContextClassLoader() though.)"); 222 223 int specified = 0; 224 225 // override application.conf with config.file, config.resource, 226 // config.url if requested. 227 String resource = System.getProperty("config.resource"); 228 if (resource != null) 229 specified += 1; 230 String file = System.getProperty("config.file"); 231 if (file != null) 232 specified += 1; 233 String url = System.getProperty("config.url"); 234 if (url != null) 235 specified += 1; 236 237 if (specified == 0) { 238 return ConfigFactory.parseResourcesAnySyntax("application", parseOptions); 239 } else if (specified > 1) { 240 throw new ConfigException.Generic("You set more than one of config.file='" + file 241 + "', config.url='" + url + "', config.resource='" + resource 242 + "'; don't know which one to use!"); 243 } else { 244 // the override file/url/resource MUST be present or it's an error 245 ConfigParseOptions overrideOptions = parseOptions.setAllowMissing(false); 246 if (resource != null) { 247 if (resource.startsWith("/")) 248 resource = resource.substring(1); 249 // this deliberately does not parseResourcesAnySyntax; if 250 // people want that they can use an include statement. 251 return parseResources(loader, resource, overrideOptions); 252 } else if (file != null) { 253 return parseFile(new File(file), overrideOptions); 254 } else { 255 try { 256 return parseURL(new URL(url), overrideOptions); 257 } catch (MalformedURLException e) { 258 throw new ConfigException.Generic("Bad URL in config.url system property: '" 259 + url + "': " + e.getMessage(), e); 260 } 261 } 262 } 263 } 264 265 /** 266 * Loads a default configuration, equivalent to {@link #load(Config) 267 * load(defaultApplication())} in most cases. This configuration should be used by 268 * libraries and frameworks unless an application provides a different one. 269 * <p> 270 * This method may return a cached singleton so will not see changes to 271 * system properties or config files. (Use {@link #invalidateCaches()} to 272 * force it to reload.) 273 * 274 * @return configuration for an application 275 */ 276 public static Config load() { 277 ClassLoader loader = checkedContextClassLoader("load"); 278 return load(loader); 279 } 280 281 /** 282 * Like {@link #load()} but allows specifying parse options. 283 * 284 * @param parseOptions 285 * Options for parsing resources 286 * @return configuration for an application 287 */ 288 public static Config load(ConfigParseOptions parseOptions) { 289 return load(parseOptions, ConfigResolveOptions.defaults()); 290 } 291 292 /** 293 * Like {@link #load()} but allows specifying a class loader other than the 294 * thread's current context class loader. 295 * 296 * @param loader 297 * class loader for finding resources 298 * @return configuration for an application 299 */ 300 public static Config load(final ClassLoader loader) { 301 final ConfigParseOptions withLoader = ConfigParseOptions.defaults().setClassLoader(loader); 302 return ConfigImpl.computeCachedConfig(loader, "load", new Callable<Config>() { 303 @Override 304 public Config call() { 305 return load(loader, defaultApplication(withLoader)); 306 } 307 }); 308 } 309 310 /** 311 * Like {@link #load()} but allows specifying a class loader other than the 312 * thread's current context class loader and also specify parse options. 313 * 314 * @param loader 315 * class loader for finding resources (overrides any loader in parseOptions) 316 * @param parseOptions 317 * Options for parsing resources 318 * @return configuration for an application 319 */ 320 public static Config load(ClassLoader loader, ConfigParseOptions parseOptions) { 321 return load(parseOptions.setClassLoader(loader)); 322 } 323 324 /** 325 * Like {@link #load()} but allows specifying a class loader other than the 326 * thread's current context class loader and also specify resolve options. 327 * 328 * @param loader 329 * class loader for finding resources 330 * @param resolveOptions 331 * options for resolving the assembled config stack 332 * @return configuration for an application 333 */ 334 public static Config load(ClassLoader loader, ConfigResolveOptions resolveOptions) { 335 return load(loader, ConfigParseOptions.defaults(), resolveOptions); 336 } 337 338 339 /** 340 * Like {@link #load()} but allows specifying a class loader other than the 341 * thread's current context class loader, parse options, and resolve options. 342 * 343 * @param loader 344 * class loader for finding resources (overrides any loader in parseOptions) 345 * @param parseOptions 346 * Options for parsing resources 347 * @param resolveOptions 348 * options for resolving the assembled config stack 349 * @return configuration for an application 350 */ 351 public static Config load(ClassLoader loader, ConfigParseOptions parseOptions, ConfigResolveOptions resolveOptions) { 352 final ConfigParseOptions withLoader = ensureClassLoader(parseOptions, "load"); 353 return load(loader, defaultApplication(withLoader), resolveOptions); 354 } 355 356 /** 357 * Like {@link #load()} but allows specifying parse options and resolve 358 * options. 359 * 360 * @param parseOptions 361 * Options for parsing resources 362 * @param resolveOptions 363 * options for resolving the assembled config stack 364 * @return configuration for an application 365 * 366 * @since 1.3.0 367 */ 368 public static Config load(ConfigParseOptions parseOptions, final ConfigResolveOptions resolveOptions) { 369 final ConfigParseOptions withLoader = ensureClassLoader(parseOptions, "load"); 370 return load(defaultApplication(withLoader), resolveOptions); 371 } 372 373 /** 374 * Obtains the default reference configuration, which is currently created 375 * by merging all resources "reference.conf" found on the classpath and 376 * overriding the result with system properties. The returned reference 377 * configuration will already have substitutions resolved. 378 * 379 * <p> 380 * Libraries and frameworks should ship with a "reference.conf" in their 381 * jar. 382 * 383 * <p> 384 * The reference config must be looked up in the class loader that contains 385 * the libraries that you want to use with this config, so the 386 * "reference.conf" for each library can be found. Use 387 * {@link #defaultReference(ClassLoader)} if the context class loader is not 388 * suitable. 389 * 390 * <p> 391 * The {@link #load()} methods merge this configuration for you 392 * automatically. 393 * 394 * <p> 395 * Future versions may look for reference configuration in more places. It 396 * is not guaranteed that this method <em>only</em> looks at 397 * "reference.conf". 398 * 399 * @return the default reference config for context class loader 400 */ 401 public static Config defaultReference() { 402 return defaultReference(checkedContextClassLoader("defaultReference")); 403 } 404 405 /** 406 * Like {@link #defaultReference()} but allows you to specify a class loader 407 * to use rather than the current context class loader. 408 * 409 * @param loader class loader to look for resources in 410 * @return the default reference config for this class loader 411 */ 412 public static Config defaultReference(ClassLoader loader) { 413 return ConfigImpl.defaultReference(loader); 414 } 415 416 /** 417 * Obtains the default override configuration, which currently consists of 418 * system properties. The returned override configuration will already have 419 * substitutions resolved. 420 * 421 * <p> 422 * The {@link #load()} methods merge this configuration for you 423 * automatically. 424 * 425 * <p> 426 * Future versions may get overrides in more places. It is not guaranteed 427 * that this method <em>only</em> uses system properties. 428 * 429 * @return the default override configuration 430 */ 431 public static Config defaultOverrides() { 432 return systemProperties(); 433 } 434 435 /** 436 * Like {@link #defaultOverrides()} but allows you to specify a class loader 437 * to use rather than the current context class loader. 438 * 439 * @param loader class loader to look for resources in 440 * @return the default override configuration 441 */ 442 public static Config defaultOverrides(ClassLoader loader) { 443 return systemProperties(); 444 } 445 446 /** 447 * Obtains the default application-specific configuration, 448 * which defaults to parsing <code>application.conf</code>, 449 * <code>application.json</code>, and 450 * <code>application.properties</code> on the classpath, but 451 * can also be rerouted using the <code>config.file</code>, 452 * <code>config.resource</code>, and <code>config.url</code> 453 * system properties. 454 * 455 * <p> The no-arguments {@link #load()} method automatically 456 * stacks the {@link #defaultReference()}, {@link 457 * #defaultApplication()}, and {@link #defaultOverrides()} 458 * configs. You would use <code>defaultApplication()</code> 459 * directly only if you're somehow customizing behavior by 460 * reimplementing <code>load()</code>. 461 * 462 * <p>The configuration returned by 463 * <code>defaultApplication()</code> will not be resolved 464 * already, in contrast to <code>defaultReference()</code> and 465 * <code>defaultOverrides()</code>. This is because 466 * application.conf would normally be resolved <em>after</em> 467 * merging with the reference and override configs. 468 * 469 * <p> 470 * If the system properties <code>config.resource</code>, 471 * <code>config.file</code>, or <code>config.url</code> are set, then the 472 * classpath resource, file, or URL specified in those properties will be 473 * used rather than the default 474 * <code>application.{conf,json,properties}</code> classpath resources. 475 * These system properties should not be set in code (after all, you can 476 * just parse whatever you want manually and then use {@link #load(Config)} 477 * if you don't want to use <code>application.conf</code>). The properties 478 * are intended for use by the person or script launching the application. 479 * For example someone might have a <code>production.conf</code> that 480 * include <code>application.conf</code> but then change a couple of values. 481 * When launching the app they could specify 482 * <code>-Dconfig.resource=production.conf</code> to get production mode. 483 * 484 * <p> 485 * If no system properties are set to change the location of the default 486 * configuration, <code>defaultApplication()</code> is equivalent to 487 * <code>ConfigFactory.parseResources("application")</code>. 488 * 489 * @since 1.3.0 490 * 491 * @return the default application.conf or system-property-configured configuration 492 */ 493 public static Config defaultApplication() { 494 return defaultApplication(ConfigParseOptions.defaults()); 495 } 496 497 /** 498 * Like {@link #defaultApplication()} but allows you to specify a class loader 499 * to use rather than the current context class loader. 500 * 501 * @since 1.3.0 502 * 503 * @param loader class loader to look for resources in 504 * @return the default application configuration 505 */ 506 public static Config defaultApplication(ClassLoader loader) { 507 return defaultApplication(ConfigParseOptions.defaults().setClassLoader(loader)); 508 } 509 510 /** 511 * Like {@link #defaultApplication()} but allows you to specify parse options. 512 * 513 * @since 1.3.0 514 * 515 * @param options the options 516 * @return the default application configuration 517 */ 518 public static Config defaultApplication(ConfigParseOptions options) { 519 return parseApplicationConfig(ensureClassLoader(options, "defaultApplication")); 520 } 521 522 /** 523 * Reloads any cached configs, picking up changes to system properties for 524 * example. Because a {@link Config} is immutable, anyone with a reference 525 * to the old configs will still have the same outdated objects. However, 526 * new calls to {@link #load()} or {@link #defaultOverrides()} or 527 * {@link #defaultReference} may return a new object. 528 * <p> 529 * This method is primarily intended for use in unit tests, for example, 530 * that may want to update a system property then confirm that it's used 531 * correctly. In many cases, use of this method may indicate there's a 532 * better way to set up your code. 533 * <p> 534 * Caches may be reloaded immediately or lazily; once you call this method, 535 * the reload can occur at any time, even during the invalidation process. 536 * So FIRST make the changes you'd like the caches to notice, then SECOND 537 * call this method to invalidate caches. Don't expect that invalidating, 538 * making changes, then calling {@link #load()}, will work. Make changes 539 * before you invalidate. 540 */ 541 public static void invalidateCaches() { 542 // We rely on this having the side effect that it drops 543 // all caches 544 ConfigImpl.reloadSystemPropertiesConfig(); 545 } 546 547 /** 548 * Gets an empty configuration. See also {@link #empty(String)} to create an 549 * empty configuration with a description, which may improve user-visible 550 * error messages. 551 * 552 * @return an empty configuration 553 */ 554 public static Config empty() { 555 return empty(null); 556 } 557 558 /** 559 * Gets an empty configuration with a description to be used to create a 560 * {@link ConfigOrigin} for this <code>Config</code>. The description should 561 * be very short and say what the configuration is, like "default settings" 562 * or "foo settings" or something. (Presumably you will merge some actual 563 * settings into this empty config using {@link Config#withFallback}, making 564 * the description more useful.) 565 * 566 * @param originDescription 567 * description of the config 568 * @return an empty configuration 569 */ 570 public static Config empty(String originDescription) { 571 return ConfigImpl.emptyConfig(originDescription); 572 } 573 574 /** 575 * Gets a <code>Config</code> containing the system properties from 576 * {@link java.lang.System#getProperties()}, parsed and converted as with 577 * {@link #parseProperties}. 578 * <p> 579 * This method can return a global immutable singleton, so it's preferred 580 * over parsing system properties yourself. 581 * <p> 582 * {@link #load} will include the system properties as overrides already, as 583 * will {@link #defaultReference} and {@link #defaultOverrides}. 584 * 585 * <p> 586 * Because this returns a singleton, it will not notice changes to system 587 * properties made after the first time this method is called. Use 588 * {@link #invalidateCaches()} to force the singleton to reload if you 589 * modify system properties. 590 * 591 * @return system properties parsed into a <code>Config</code> 592 */ 593 public static Config systemProperties() { 594 return ConfigImpl.systemPropertiesAsConfig(); 595 } 596 597 /** 598 * Gets a <code>Config</code> containing the system's environment variables. 599 * This method can return a global immutable singleton. 600 * 601 * <p> 602 * Environment variables are used as fallbacks when resolving substitutions 603 * whether or not this object is included in the config being resolved, so 604 * you probably don't need to use this method for most purposes. It can be a 605 * nicer API for accessing environment variables than raw 606 * {@link java.lang.System#getenv(String)} though, since you can use methods 607 * such as {@link Config#getInt}. 608 * 609 * @return system environment variables parsed into a <code>Config</code> 610 */ 611 public static Config systemEnvironment() { 612 return ConfigImpl.envVariablesAsConfig(); 613 } 614 615 /** 616 * Converts a Java {@link java.util.Properties} object to a 617 * {@link ConfigObject} using the rules documented in the <a 618 * href="https://github.com/typesafehub/config/blob/master/HOCON.md">HOCON 619 * spec</a>. The keys in the <code>Properties</code> object are split on the 620 * period character '.' and treated as paths. The values will all end up as 621 * string values. If you have both "a=foo" and "a.b=bar" in your properties 622 * file, so "a" is both the object containing "b" and the string "foo", then 623 * the string value is dropped. 624 * 625 * <p> 626 * If you want to have <code>System.getProperties()</code> as a 627 * ConfigObject, it's better to use the {@link #systemProperties()} method 628 * which returns a cached global singleton. 629 * 630 * @param properties 631 * a Java Properties object 632 * @param options 633 * the parse options 634 * @return the parsed configuration 635 */ 636 public static Config parseProperties(Properties properties, 637 ConfigParseOptions options) { 638 return Parseable.newProperties(properties, options).parse().toConfig(); 639 } 640 641 /** 642 * Like {@link #parseProperties(Properties, ConfigParseOptions)} but uses default 643 * parse options. 644 * @param properties 645 * a Java Properties object 646 * @return the parsed configuration 647 */ 648 public static Config parseProperties(Properties properties) { 649 return parseProperties(properties, ConfigParseOptions.defaults()); 650 } 651 652 /** 653 * Parses a Reader into a Config instance. Does not call 654 * {@link Config#resolve} or merge the parsed stream with any 655 * other configuration; this method parses a single stream and 656 * does nothing else. It does process "include" statements in 657 * the parsed stream, and may end up doing other IO due to those 658 * statements. 659 * 660 * @param reader 661 * the reader to parse 662 * @param options 663 * parse options to control how the reader is interpreted 664 * @return the parsed configuration 665 * @throws ConfigException on IO or parse errors 666 */ 667 public static Config parseReader(Reader reader, ConfigParseOptions options) { 668 return Parseable.newReader(reader, options).parse().toConfig(); 669 } 670 671 /** 672 * Parses a reader into a Config instance as with 673 * {@link #parseReader(Reader,ConfigParseOptions)} but always uses the 674 * default parse options. 675 * 676 * @param reader 677 * the reader to parse 678 * @return the parsed configuration 679 * @throws ConfigException on IO or parse errors 680 */ 681 public static Config parseReader(Reader reader) { 682 return parseReader(reader, ConfigParseOptions.defaults()); 683 } 684 685 /** 686 * Parses a URL into a Config instance. Does not call 687 * {@link Config#resolve} or merge the parsed stream with any 688 * other configuration; this method parses a single stream and 689 * does nothing else. It does process "include" statements in 690 * the parsed stream, and may end up doing other IO due to those 691 * statements. 692 * 693 * @param url 694 * the url to parse 695 * @param options 696 * parse options to control how the url is interpreted 697 * @return the parsed configuration 698 * @throws ConfigException on IO or parse errors 699 */ 700 public static Config parseURL(URL url, ConfigParseOptions options) { 701 return Parseable.newURL(url, options).parse().toConfig(); 702 } 703 704 /** 705 * Parses a url into a Config instance as with 706 * {@link #parseURL(URL,ConfigParseOptions)} but always uses the 707 * default parse options. 708 * 709 * @param url 710 * the url to parse 711 * @return the parsed configuration 712 * @throws ConfigException on IO or parse errors 713 */ 714 public static Config parseURL(URL url) { 715 return parseURL(url, ConfigParseOptions.defaults()); 716 } 717 718 /** 719 * Parses a file into a Config instance. Does not call 720 * {@link Config#resolve} or merge the file with any other 721 * configuration; this method parses a single file and does 722 * nothing else. It does process "include" statements in the 723 * parsed file, and may end up doing other IO due to those 724 * statements. 725 * 726 * @param file 727 * the file to parse 728 * @param options 729 * parse options to control how the file is interpreted 730 * @return the parsed configuration 731 * @throws ConfigException on IO or parse errors 732 */ 733 public static Config parseFile(File file, ConfigParseOptions options) { 734 return Parseable.newFile(file, options).parse().toConfig(); 735 } 736 737 /** 738 * Parses a file into a Config instance as with 739 * {@link #parseFile(File,ConfigParseOptions)} but always uses the 740 * default parse options. 741 * 742 * @param file 743 * the file to parse 744 * @return the parsed configuration 745 * @throws ConfigException on IO or parse errors 746 */ 747 public static Config parseFile(File file) { 748 return parseFile(file, ConfigParseOptions.defaults()); 749 } 750 751 /** 752 * Parses a file with a flexible extension. If the <code>fileBasename</code> 753 * already ends in a known extension, this method parses it according to 754 * that extension (the file's syntax must match its extension). If the 755 * <code>fileBasename</code> does not end in an extension, it parses files 756 * with all known extensions and merges whatever is found. 757 * 758 * <p> 759 * In the current implementation, the extension ".conf" forces 760 * {@link ConfigSyntax#CONF}, ".json" forces {@link ConfigSyntax#JSON}, and 761 * ".properties" forces {@link ConfigSyntax#PROPERTIES}. When merging files, 762 * ".conf" falls back to ".json" falls back to ".properties". 763 * 764 * <p> 765 * Future versions of the implementation may add additional syntaxes or 766 * additional extensions. However, the ordering (fallback priority) of the 767 * three current extensions will remain the same. 768 * 769 * <p> 770 * If <code>options</code> forces a specific syntax, this method only parses 771 * files with an extension matching that syntax. 772 * 773 * <p> 774 * If {@link ConfigParseOptions#getAllowMissing options.getAllowMissing()} 775 * is true, then no files have to exist; if false, then at least one file 776 * has to exist. 777 * 778 * @param fileBasename 779 * a filename with or without extension 780 * @param options 781 * parse options 782 * @return the parsed configuration 783 */ 784 public static Config parseFileAnySyntax(File fileBasename, 785 ConfigParseOptions options) { 786 return ConfigImpl.parseFileAnySyntax(fileBasename, options).toConfig(); 787 } 788 789 /** 790 * Like {@link #parseFileAnySyntax(File,ConfigParseOptions)} but always uses 791 * default parse options. 792 * 793 * @param fileBasename 794 * a filename with or without extension 795 * @return the parsed configuration 796 */ 797 public static Config parseFileAnySyntax(File fileBasename) { 798 return parseFileAnySyntax(fileBasename, ConfigParseOptions.defaults()); 799 } 800 801 /** 802 * Parses all resources on the classpath with the given name and merges them 803 * into a single <code>Config</code>. 804 * 805 * <p> 806 * If the resource name does not begin with a "/", it will have the supplied 807 * class's package added to it, in the same way as 808 * {@link java.lang.Class#getResource}. 809 * 810 * <p> 811 * Duplicate resources with the same name are merged such that ones returned 812 * earlier from {@link ClassLoader#getResources} fall back to (have higher 813 * priority than) the ones returned later. This implies that resources 814 * earlier in the classpath override those later in the classpath when they 815 * configure the same setting. However, in practice real applications may 816 * not be consistent about classpath ordering, so be careful. It may be best 817 * to avoid assuming too much. 818 * 819 * @param klass 820 * <code>klass.getClassLoader()</code> will be used to load 821 * resources, and non-absolute resource names will have this 822 * class's package added 823 * @param resource 824 * resource to look up, relative to <code>klass</code>'s package 825 * or absolute starting with a "/" 826 * @param options 827 * parse options 828 * @return the parsed configuration 829 */ 830 public static Config parseResources(Class<?> klass, String resource, 831 ConfigParseOptions options) { 832 return Parseable.newResources(klass, resource, options).parse() 833 .toConfig(); 834 } 835 836 /** 837 * Like {@link #parseResources(Class,String,ConfigParseOptions)} but always uses 838 * default parse options. 839 * 840 * @param klass 841 * <code>klass.getClassLoader()</code> will be used to load 842 * resources, and non-absolute resource names will have this 843 * class's package added 844 * @param resource 845 * resource to look up, relative to <code>klass</code>'s package 846 * or absolute starting with a "/" 847 * @return the parsed configuration 848 */ 849 public static Config parseResources(Class<?> klass, String resource) { 850 return parseResources(klass, resource, ConfigParseOptions.defaults()); 851 } 852 853 /** 854 * Parses classpath resources with a flexible extension. In general, this 855 * method has the same behavior as 856 * {@link #parseFileAnySyntax(File,ConfigParseOptions)} but for classpath 857 * resources instead, as in {@link #parseResources}. 858 * 859 * <p> 860 * There is a thorny problem with this method, which is that 861 * {@link java.lang.ClassLoader#getResources} must be called separately for 862 * each possible extension. The implementation ends up with separate lists 863 * of resources called "basename.conf" and "basename.json" for example. As a 864 * result, the ideal ordering between two files with different extensions is 865 * unknown; there is no way to figure out how to merge the two lists in 866 * classpath order. To keep it simple, the lists are simply concatenated, 867 * with the same syntax priorities as 868 * {@link #parseFileAnySyntax(File,ConfigParseOptions) parseFileAnySyntax()} 869 * - all ".conf" resources are ahead of all ".json" resources which are 870 * ahead of all ".properties" resources. 871 * 872 * @param klass 873 * class which determines the <code>ClassLoader</code> and the 874 * package for relative resource names 875 * @param resourceBasename 876 * a resource name as in {@link java.lang.Class#getResource}, 877 * with or without extension 878 * @param options 879 * parse options (class loader is ignored in favor of the one 880 * from klass) 881 * @return the parsed configuration 882 */ 883 public static Config parseResourcesAnySyntax(Class<?> klass, String resourceBasename, 884 ConfigParseOptions options) { 885 return ConfigImpl.parseResourcesAnySyntax(klass, resourceBasename, 886 options).toConfig(); 887 } 888 889 /** 890 * Like {@link #parseResourcesAnySyntax(Class,String,ConfigParseOptions)} 891 * but always uses default parse options. 892 * 893 * @param klass 894 * <code>klass.getClassLoader()</code> will be used to load 895 * resources, and non-absolute resource names will have this 896 * class's package added 897 * @param resourceBasename 898 * a resource name as in {@link java.lang.Class#getResource}, 899 * with or without extension 900 * @return the parsed configuration 901 */ 902 public static Config parseResourcesAnySyntax(Class<?> klass, String resourceBasename) { 903 return parseResourcesAnySyntax(klass, resourceBasename, ConfigParseOptions.defaults()); 904 } 905 906 /** 907 * Parses all resources on the classpath with the given name and merges them 908 * into a single <code>Config</code>. 909 * 910 * <p> 911 * This works like {@link java.lang.ClassLoader#getResource}, not like 912 * {@link java.lang.Class#getResource}, so the name never begins with a 913 * slash. 914 * 915 * <p> 916 * See {@link #parseResources(Class,String,ConfigParseOptions)} for full 917 * details. 918 * 919 * @param loader 920 * will be used to load resources by setting this loader on the 921 * provided options 922 * @param resource 923 * resource to look up 924 * @param options 925 * parse options (class loader is ignored) 926 * @return the parsed configuration 927 */ 928 public static Config parseResources(ClassLoader loader, String resource, 929 ConfigParseOptions options) { 930 return parseResources(resource, options.setClassLoader(loader)); 931 } 932 933 /** 934 * Like {@link #parseResources(ClassLoader,String,ConfigParseOptions)} but always uses 935 * default parse options. 936 * 937 * @param loader 938 * will be used to load resources 939 * @param resource 940 * resource to look up in the loader 941 * @return the parsed configuration 942 */ 943 public static Config parseResources(ClassLoader loader, String resource) { 944 return parseResources(loader, resource, ConfigParseOptions.defaults()); 945 } 946 947 /** 948 * Parses classpath resources with a flexible extension. In general, this 949 * method has the same behavior as 950 * {@link #parseFileAnySyntax(File,ConfigParseOptions)} but for classpath 951 * resources instead, as in 952 * {@link #parseResources(ClassLoader,String,ConfigParseOptions)}. 953 * 954 * <p> 955 * {@link #parseResourcesAnySyntax(Class,String,ConfigParseOptions)} differs 956 * in the syntax for the resource name, but otherwise see 957 * {@link #parseResourcesAnySyntax(Class,String,ConfigParseOptions)} for 958 * some details and caveats on this method. 959 * 960 * @param loader 961 * class loader to look up resources in, will be set on options 962 * @param resourceBasename 963 * a resource name as in 964 * {@link java.lang.ClassLoader#getResource}, with or without 965 * extension 966 * @param options 967 * parse options (class loader ignored) 968 * @return the parsed configuration 969 */ 970 public static Config parseResourcesAnySyntax(ClassLoader loader, String resourceBasename, 971 ConfigParseOptions options) { 972 return ConfigImpl.parseResourcesAnySyntax(resourceBasename, options.setClassLoader(loader)) 973 .toConfig(); 974 } 975 976 /** 977 * Like {@link #parseResourcesAnySyntax(ClassLoader,String,ConfigParseOptions)} but always uses 978 * default parse options. 979 * 980 * @param loader 981 * will be used to load resources 982 * @param resourceBasename 983 * a resource name as in 984 * {@link java.lang.ClassLoader#getResource}, with or without 985 * extension 986 * @return the parsed configuration 987 */ 988 public static Config parseResourcesAnySyntax(ClassLoader loader, String resourceBasename) { 989 return parseResourcesAnySyntax(loader, resourceBasename, ConfigParseOptions.defaults()); 990 } 991 992 /** 993 * Like {@link #parseResources(ClassLoader,String,ConfigParseOptions)} but 994 * uses thread's current context class loader if none is set in the 995 * ConfigParseOptions. 996 * @param resource the resource name 997 * @param options parse options 998 * @return the parsed configuration 999 */ 1000 public static Config parseResources(String resource, ConfigParseOptions options) { 1001 ConfigParseOptions withLoader = ensureClassLoader(options, "parseResources"); 1002 return Parseable.newResources(resource, withLoader).parse().toConfig(); 1003 } 1004 1005 /** 1006 * Like {@link #parseResources(ClassLoader,String)} but uses thread's 1007 * current context class loader. 1008 * @param resource the resource name 1009 * @return the parsed configuration 1010 */ 1011 public static Config parseResources(String resource) { 1012 return parseResources(resource, ConfigParseOptions.defaults()); 1013 } 1014 1015 /** 1016 * Like 1017 * {@link #parseResourcesAnySyntax(ClassLoader,String,ConfigParseOptions)} 1018 * but uses thread's current context class loader. 1019 * @param resourceBasename the resource basename (no file type suffix) 1020 * @param options parse options 1021 * @return the parsed configuration 1022 */ 1023 public static Config parseResourcesAnySyntax(String resourceBasename, ConfigParseOptions options) { 1024 return ConfigImpl.parseResourcesAnySyntax(resourceBasename, options).toConfig(); 1025 } 1026 1027 /** 1028 * Like {@link #parseResourcesAnySyntax(ClassLoader,String)} but uses 1029 * thread's current context class loader. 1030 * @param resourceBasename the resource basename (no file type suffix) 1031 * @return the parsed configuration 1032 */ 1033 public static Config parseResourcesAnySyntax(String resourceBasename) { 1034 return parseResourcesAnySyntax(resourceBasename, ConfigParseOptions.defaults()); 1035 } 1036 1037 /** 1038 * Parses a string (which should be valid HOCON or JSON by default, or 1039 * the syntax specified in the options otherwise). 1040 * 1041 * @param s string to parse 1042 * @param options parse options 1043 * @return the parsed configuration 1044 */ 1045 public static Config parseString(String s, ConfigParseOptions options) { 1046 return Parseable.newString(s, options).parse().toConfig(); 1047 } 1048 1049 /** 1050 * Parses a string (which should be valid HOCON or JSON). 1051 * 1052 * @param s string to parse 1053 * @return the parsed configuration 1054 */ 1055 public static Config parseString(String s) { 1056 return parseString(s, ConfigParseOptions.defaults()); 1057 } 1058 1059 /** 1060 * Creates a {@code Config} based on a {@link java.util.Map} from paths to 1061 * plain Java values. Similar to 1062 * {@link ConfigValueFactory#fromMap(Map,String)}, except the keys in the 1063 * map are path expressions, rather than keys; and correspondingly it 1064 * returns a {@code Config} instead of a {@code ConfigObject}. This is more 1065 * convenient if you are writing literal maps in code, and less convenient 1066 * if you are getting your maps from some data source such as a parser. 1067 * 1068 * <p> 1069 * An exception will be thrown (and it is a bug in the caller of the method) 1070 * if a path is both an object and a value, for example if you had both 1071 * "a=foo" and "a.b=bar", then "a" is both the string "foo" and the parent 1072 * object of "b". The caller of this method should ensure that doesn't 1073 * happen. 1074 * 1075 * @param values map from paths to plain Java objects 1076 * @param originDescription 1077 * description of what this map represents, like a filename, or 1078 * "default settings" (origin description is used in error 1079 * messages) 1080 * @return the map converted to a {@code Config} 1081 */ 1082 public static Config parseMap(Map<String, ? extends Object> values, 1083 String originDescription) { 1084 return ConfigImpl.fromPathMap(values, originDescription).toConfig(); 1085 } 1086 1087 /** 1088 * See the other overload of {@link #parseMap(Map, String)} for details, 1089 * this one just uses a default origin description. 1090 * 1091 * @param values map from paths to plain Java values 1092 * @return the map converted to a {@code Config} 1093 */ 1094 public static Config parseMap(Map<String, ? extends Object> values) { 1095 return parseMap(values, null); 1096 } 1097}