org.deephacks.tools4j.config.internal.core.runtime.typesafe.ConfigMergeable Maven / Gradle / Ivy
/**
* Copyright (C) 2011-2012 Typesafe Inc.
*/
package org.deephacks.tools4j.config.internal.core.runtime.typesafe;
/**
* Marker for types whose instances can be merged, that is {@link Config} and
* {@link ConfigValue}. Instances of {@code Config} and {@code ConfigValue} can
* be combined into a single new instance using the
* {@link ConfigMergeable#withFallback withFallback()} method.
*
*
* Do not implement this interface; it should only be implemented by
* the typesafe library. Arbitrary implementations will not work because the
* library internals assume a specific concrete implementation. Also, this
* interface is likely to grow new methods over time, so third-party
* implementations will break.
*/
public interface ConfigMergeable {
/**
* Returns a new value computed by merging this value with another, with
* keys in this value "winning" over the other one. Only
* {@link ConfigObject} and {@link Config} instances do anything in this
* method (they need to merge the fallback keys into themselves). All other
* values just return the original value, since they automatically override
* any fallback.
*
*
The semantics of merging are described in the spec
* for HOCON. Merging typically occurs when either the
* same object is created twice in the same file, or two
* typesafe files are both loaded. For example:
*
* foo = { a: 42 }
* foo = { b: 43 }
*
* Here, the two objects are merged as if you had written:
*
* foo = { a: 42, b: 43 }
*
*
*
* Note that objects do not merge "across" non-objects; if you write
* object.withFallback(nonObject).withFallback(otherObject),
* then otherObject will simply be ignored. This is an
* intentional part of how merging works, because non-objects such as
* strings and integers replace (rather than merging with) any
* prior value:
*
* foo = { a: 42 }
* foo = 10
*
* Here, the number 10 "wins" and the value of foo would be
* simply 10. Again, for details see the spec.
*
* @param other
* an object whose keys should be used if the keys are not
* present in this one
* @return a new object (or the original one, if the fallback doesn't get
* used)
*/
ConfigMergeable withFallback(ConfigMergeable other);
}