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/master/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}