    001/**
    002 *   Copyright (C) 2011-2012 Typesafe Inc. <http://typesafe.com>
    003 */
    004package com.typesafe.config;
    005
    006/**
    007 * An immutable value, following the <a href="http://json.org">JSON</a> type
    008 * schema.
    009 *
    010 * <p>
    011 * Because this object is immutable, it is safe to use from multiple threads and
    012 * there's no need for "defensive copies."
    013 *
    014 * <p>
    015 * <em>Do not implement interface {@code ConfigValue}</em>; it should only be
    016 * implemented by the config library. Arbitrary implementations will not work
    017 * because the library internals assume a specific concrete implementation.
    018 * Also, this interface is likely to grow new methods over time, so third-party
    019 * implementations will break.
    020 */
    021public interface ConfigValue extends ConfigMergeable {
    022    /**
    023     * The origin of the value (file, line number, etc.), for debugging and
    024     * error messages.
    025     *
    026     * @return where the value came from
    027     */
    028    ConfigOrigin origin();
    029
    030    /**
    031     * The {@link ConfigValueType} of the value; matches the JSON type schema.
    032     *
    033     * @return value's type
    034     */
    035    ConfigValueType valueType();
    036
    037    /**
    038     * Returns the value as a plain Java boxed value, that is, a {@code String},
    039     * {@code Number}, {@code Boolean}, {@code Map<String,Object>},
    040     * {@code List<Object>}, or {@code null}, matching the {@link #valueType()}
    041     * of this {@code ConfigValue}. If the value is a {@link ConfigObject} or
    042     * {@link ConfigList}, it is recursively unwrapped.
    043     * @return a plain Java value corresponding to this ConfigValue
    044     */
    045    Object unwrapped();
    046
    047    /**
    048     * Renders the config value as a HOCON string. This method is primarily
    049     * intended for debugging, so it tries to add helpful comments and
    050     * whitespace.
    051     *
    052     * <p>
    053     * If the config value has not been resolved (see {@link Config#resolve}),
    054     * it's possible that it can't be rendered as valid HOCON. In that case the
    055     * rendering should still be useful for debugging but you might not be able
    056     * to parse it. If the value has been resolved, it will always be parseable.
    057     *
    058     * <p>
    059     * This method is equivalent to
    060     * {@code render(ConfigRenderOptions.defaults())}.
    061     *
    062     * @return the rendered value
    063     */
    064    String render();
    065
    066    /**
    067     * Renders the config value to a string, using the provided options.
    068     *
    069     * <p>
    070     * If the config value has not been resolved (see {@link Config#resolve}),
    071     * it's possible that it can't be rendered as valid HOCON. In that case the
    072     * rendering should still be useful for debugging but you might not be able
    073     * to parse it. If the value has been resolved, it will always be parseable.
    074     *
    075     * <p>
    076     * If the config value has been resolved and the options disable all
    077     * HOCON-specific features (such as comments), the rendering will be valid
    078     * JSON. If you enable HOCON-only features such as comments, the rendering
    079     * will not be valid JSON.
    080     *
    081     * @param options
    082     *            the rendering options
    083     * @return the rendered value
    084     */
    085    String render(ConfigRenderOptions options);
    086
    087    @Override
    088    ConfigValue withFallback(ConfigMergeable other);
    089
    090    /**
    091     * Places the value inside a {@link Config} at the given path. See also
    092     * {@link ConfigValue#atKey(String)}.
    093     *
    094     * @param path
    095     *            path to store this value at.
    096     * @return a {@code Config} instance containing this value at the given
    097     *         path.
    098     */
    099    Config atPath(String path);
    100
    101    /**
    102     * Places the value inside a {@link Config} at the given key. See also
    103     * {@link ConfigValue#atPath(String)}.
    104     *
    105     * @param key
    106     *            key to store this value at.
    107     * @return a {@code Config} instance containing this value at the given key.
    108     */
    109    Config atKey(String key);
    110
    111    /**
    112     * Returns a {@code ConfigValue} based on this one, but with the given
    113     * origin. This is useful when you are parsing a new format of file or setting
    114     * comments for a single ConfigValue.
    115     *
    116     * @since 1.3.0
    117     *
    118     * @param origin the origin set on the returned value
    119     * @return the new ConfigValue with the given origin
    120     */
    121    ConfigValue withOrigin(ConfigOrigin origin);
    122}