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}