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