    001/**
    002 *   Copyright (C) 2011-2012 Typesafe Inc. <http://typesafe.com>
    003 */
    004package com.typesafe.config;
    005
    006/**
    007 * Marker for types whose instances can be merged, that is {@link Config} and
    008 * {@link ConfigValue}. Instances of {@code Config} and {@code ConfigValue} can
    009 * be combined into a single new instance using the
    010 * {@link ConfigMergeable#withFallback withFallback()} method.
    011 *
    012 * <p>
    013 * <em>Do not implement this interface</em>; it should only be implemented by
    014 * the config library. Arbitrary implementations will not work because the
    015 * library internals assume a specific concrete implementation. Also, this
    016 * interface is likely to grow new methods over time, so third-party
    017 * implementations will break.
    018 */
    019public interface ConfigMergeable {
    020    /**
    021     * Returns a new value computed by merging this value with another, with
    022     * keys in this value "winning" over the other one.
    023     *
    024     * <p>
    025     * This associative operation may be used to combine configurations from
    026     * multiple sources (such as multiple configuration files).
    027     *
    028     * <p>
    029     * The semantics of merging are described in the <a
    030     * href="https://github.com/lightbend/config/blob/main/HOCON.md">spec
    031     * for HOCON</a>. Merging typically occurs when either the same object is
    032     * created twice in the same file, or two config files are both loaded. For
    033     * example:
    034     *
    035     * <pre>
    036     *  foo = { a: 42 }
    037     *  foo = { b: 43 }
    038     * </pre>
    039     *
    040     * Here, the two objects are merged as if you had written:
    041     *
    042     * <pre>
    043     *  foo = { a: 42, b: 43 }
    044     * </pre>
    045     *
    046     * <p>
    047     * Only {@link ConfigObject} and {@link Config} instances do anything in
    048     * this method (they need to merge the fallback keys into themselves). All
    049     * other values just return the original value, since they automatically
    050     * override any fallback. This means that objects do not merge "across"
    051     * non-objects; if you write
    052     * <code>object.withFallback(nonObject).withFallback(otherObject)</code>,
    053     * then <code>otherObject</code> will simply be ignored. This is an
    054     * intentional part of how merging works, because non-objects such as
    055     * strings and integers replace (rather than merging with) any prior value:
    056     *
    057     * <pre>
    058     * foo = { a: 42 }
    059     * foo = 10
    060     * </pre>
    061     *
    062     * Here, the number 10 "wins" and the value of <code>foo</code> would be
    063     * simply 10. Again, for details see the spec.
    064     *
    065     * @param other
    066     *            an object whose keys should be used as fallbacks, if the keys
    067     *            are not present in this one
    068     * @return a new object (or the original one, if the fallback doesn't get
    069     *         used)
    070     */
    071    ConfigMergeable withFallback(ConfigMergeable other);
    072}