001package com.typesafe.config;
002
003import com.typesafe.config.impl.ConfigBeanImpl;
004
005/**
006 * Factory for automatically creating a Java class from a {@link Config}.
007 * See {@link #create(Config,Class)}.
008 *
009 * @since 1.3.0
010 */
011public class ConfigBeanFactory {
012
013    /**
014     * Creates an instance of a class, initializing its fields from a {@link Config}.
015     *
016     * Example usage:
017     *
018     * <pre>
019     * Config configSource = ConfigFactory.load().getConfig("foo");
020     * FooConfig config = ConfigBeanFactory.create(configSource, FooConfig.class);
021     * </pre>
022     *
023     * The Java class should follow JavaBean conventions. Field types
024     * can be any of the types you can normally get from a {@link
025     * Config}, including <code>java.time.Duration</code> or {@link
026     * ConfigMemorySize}. Fields may also be another JavaBean-style
027     * class.
028     *
029     * Fields are mapped to config by converting the config key to
030     * camel case.  So the key <code>foo-bar</code> becomes JavaBean
031     * setter <code>setFooBar</code>.
032     *
033     * @since 1.3.0
034     *
035     * @param config source of config information
036     * @param clazz class to be instantiated
037     * @param <T> the type of the class to be instantiated
038     * @return an instance of the class populated with data from the config
039     * @throws ConfigException.BadBean
040     *     If something is wrong with the JavaBean
041     * @throws ConfigException.ValidationFailed
042     *     If the config doesn't conform to the bean's implied schema. Unknown
043     *     config keys are ignored.
044     * @throws ConfigException
045     *     Can throw the same exceptions as the getters on <code>Config</code>
046     */
047    public static <T> T create(Config config, Class<T> clazz) {
048        return ConfigBeanImpl.createInternal(config, clazz, true);
049    }
050
051    /**
052     * Creates an instance of a class, initializing its fields from a {@link Config}.
053     *
054     * Example usage:
055     *
056     * <pre>
057     * Config configSource = ConfigFactory.load().getConfig("foo");
058     * FooConfig config = ConfigBeanFactory.create(configSource, FooConfig.class, false);
059     * </pre>
060     *
061     * The Java class should follow JavaBean conventions. Field types
062     * can be any of the types you can normally get from a {@link
063     * Config}, including <code>java.time.Duration</code> or {@link
064     * ConfigMemorySize}. Fields may also be another JavaBean-style
065     * class.
066     *
067     * Fields are mapped to config by converting the config key to
068     * camel case.  So the key <code>foo-bar</code> becomes JavaBean
069     * setter <code>setFooBar</code>.
070     *
071     * @since 1.4.9
072     *
073     * @param config source of config information
074     * @param clazz class to be instantiated
075     * @param allowUnknownConfigKeys if false, throw a validation error when
076     *     the config has keys that do not map to bean properties
077     * @param <T> the type of the class to be instantiated
078     * @return an instance of the class populated with data from the config
079     * @throws ConfigException.BadBean
080     *     If something is wrong with the JavaBean
081     * @throws ConfigException.ValidationFailed
082     *     If the config doesn't conform to the bean's implied schema, including
083     *     unknown config keys when <code>allowUnknownConfigKeys</code> is false
084     * @throws ConfigException
085     *     Can throw the same exceptions as the getters on <code>Config</code>
086     */
087    public static <T> T create(Config config, Class<T> clazz, boolean allowUnknownConfigKeys) {
088        return ConfigBeanImpl.createInternal(config, clazz, allowUnknownConfigKeys);
089    }
090}