    001/**
    002 *   Copyright (C) 2011-2012 Typesafe Inc. <http://typesafe.com>
    003 */
    004package com.typesafe.config;
    005
    006import java.util.Map;
    007
    008import com.typesafe.config.impl.ConfigImpl;
    009
    010/**
    011 * This class holds some static factory methods for building {@link ConfigValue}
    012 * instances. See also {@link ConfigFactory} which has methods for parsing files
    013 * and certain in-memory data structures.
    014 */
    015public final class ConfigValueFactory {
    016    private ConfigValueFactory() {
    017    }
    018
    019    /**
    020     * Creates a {@link ConfigValue} from a plain Java boxed value, which may be
    021     * a <code>Boolean</code>, <code>Number</code>, <code>String</code>,
    022     * <code>Map</code>, <code>Iterable</code>, or <code>null</code>. A
    023     * <code>Map</code> must be a <code>Map</code> from String to more values
    024     * that can be supplied to <code>fromAnyRef()</code>. An
    025     * <code>Iterable</code> must iterate over more values that can be supplied
    026     * to <code>fromAnyRef()</code>. A <code>Map</code> will become a
    027     * {@link ConfigObject} and an <code>Iterable</code> will become a
    028     * {@link ConfigList}. If the <code>Iterable</code> is not an ordered
    029     * collection, results could be strange, since <code>ConfigList</code> is
    030     * ordered.
    031     *
    032     * <p>
    033     * In a <code>Map</code> passed to <code>fromAnyRef()</code>, the map's keys
    034     * are plain keys, not path expressions. So if your <code>Map</code> has a
    035     * key "foo.bar" then you will get one object with a key called "foo.bar",
    036     * rather than an object with a key "foo" containing another object with a
    037     * key "bar".
    038     *
    039     * <p>
    040     * The originDescription will be used to set the origin() field on the
    041     * ConfigValue. It should normally be the name of the file the values came
    042     * from, or something short describing the value such as "default settings".
    043     * The originDescription is prefixed to error messages so users can tell
    044     * where problematic values are coming from.
    045     *
    046     * <p>
    047     * Supplying the result of ConfigValue.unwrapped() to this function is
    048     * guaranteed to work and should give you back a ConfigValue that matches
    049     * the one you unwrapped. The re-wrapped ConfigValue will lose some
    050     * information that was present in the original such as its origin, but it
    051     * will have matching values.
    052     *
    053     * <p>
    054     * If you pass in a <code>ConfigValue</code> to this
    055     * function, it will be returned unmodified. (The
    056     * <code>originDescription</code> will be ignored in this
    057     * case.)
    058     *
    059     * <p>
    060     * This function throws if you supply a value that cannot be converted to a
    061     * ConfigValue, but supplying such a value is a bug in your program, so you
    062     * should never handle the exception. Just fix your program (or report a bug
    063     * against this library).
    064     *
    065     * @param object
    066     *            object to convert to ConfigValue
    067     * @param originDescription
    068     *            name of origin file or brief description of what the value is
    069     * @return a new value
    070     */
    071    public static ConfigValue fromAnyRef(Object object, String originDescription) {
    072        return ConfigImpl.fromAnyRef(object, originDescription);
    073    }
    074
    075    /**
    076     * See the {@link #fromAnyRef(Object,String)} documentation for details.
    077     * This is a typesafe wrapper that only works on {@link java.util.Map} and
    078     * returns {@link ConfigObject} rather than {@link ConfigValue}.
    079     *
    080     * <p>
    081     * If your <code>Map</code> has a key "foo.bar" then you will get one object
    082     * with a key called "foo.bar", rather than an object with a key "foo"
    083     * containing another object with a key "bar". The keys in the map are keys;
    084     * not path expressions. That is, the <code>Map</code> corresponds exactly
    085     * to a single {@code ConfigObject}. The keys will not be parsed or
    086     * modified, and the values are wrapped in ConfigValue. To get nested
    087     * {@code ConfigObject}, some of the values in the map would have to be more
    088     * maps.
    089     *
    090     * <p>
    091     * See also {@link ConfigFactory#parseMap(Map,String)} which interprets the
    092     * keys in the map as path expressions.
    093     *
    094     * @param values map from keys to plain Java values
    095     * @param originDescription description to use in {@link ConfigOrigin} of created values
    096     * @return a new {@link ConfigObject} value
    097     */
    098    public static ConfigObject fromMap(Map<String, ? extends Object> values,
    099            String originDescription) {
    100        return (ConfigObject) fromAnyRef(values, originDescription);
    101    }
    102
    103    /**
    104     * See the {@link #fromAnyRef(Object,String)} documentation for details.
    105     * This is a typesafe wrapper that only works on {@link java.lang.Iterable}
    106     * and returns {@link ConfigList} rather than {@link ConfigValue}.
    107     *
    108     * @param values list of plain Java values
    109     * @param originDescription description to use in {@link ConfigOrigin} of created values
    110     * @return a new {@link ConfigList} value
    111     */
    112    public static ConfigList fromIterable(Iterable<? extends Object> values,
    113            String originDescription) {
    114        return (ConfigList) fromAnyRef(values, originDescription);
    115    }
    116
    117    /**
    118     * See the other overload {@link #fromAnyRef(Object,String)} for details,
    119     * this one just uses a default origin description.
    120     *
    121     * @param object a plain Java value
    122     * @return a new {@link ConfigValue}
    123     */
    124    public static ConfigValue fromAnyRef(Object object) {
    125        return fromAnyRef(object, null);
    126    }
    127
    128    /**
    129     * See the other overload {@link #fromMap(Map,String)} for details, this one
    130     * just uses a default origin description.
    131     *
    132     * <p>
    133     * See also {@link ConfigFactory#parseMap(Map)} which interprets the keys in
    134     * the map as path expressions.
    135     *
    136     * @param values map from keys to plain Java values
    137     * @return a new {@link ConfigObject}
    138     */
    139    public static ConfigObject fromMap(Map<String, ? extends Object> values) {
    140        return fromMap(values, null);
    141    }
    142
    143    /**
    144     * See the other overload of {@link #fromIterable(Iterable, String)} for
    145     * details, this one just uses a default origin description.
    146     *
    147     * @param values list of plain Java values
    148     * @return a new {@link ConfigList}
    149     */
    150    public static ConfigList fromIterable(Iterable<? extends Object> values) {
    151        return fromIterable(values, null);
    152    }
    153}