ConfigBag (Apache Brooklyn)

java.lang.Object
- brooklyn.util.config.ConfigBag

```
public class ConfigBag
extends java.lang.Object
```
Stores config in such a way that usage can be tracked. Either ConfigKey or String keys can be inserted; they will be stored internally as strings. It is recommended to use ConfigKey instances to access, although in some cases (such as setting fields from flags, or copying a map) it may be necessary to mark things as used, or put, when only a string key is available.
This bag is order-preserving and thread-safe except where otherwise indicated, currently by synching on this instance (but that behaviour may change).

Field Summary

Fields
Modifier and Type Field and Description

static ConfigBag EMPTY
an immutable, empty ConfigBag

Fields
Modifier and Type	Field and Description
`static ConfigBag`	`EMPTY` an immutable, empty ConfigBag

Constructor Summary

Constructors
Constructor and Description

ConfigBag()

Constructors
Constructor and Description
`ConfigBag()`

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`clear()`
`static <T> T`	`coerceFirstNonNullKeyValue(ConfigKey<T> key, java.lang.Object... values)` returns the first non-null value to be the type indicated by the key, or the keys default value if no non-null values are supplied
`<T> ConfigBag`	`configure(ConfigKey<T> key, T value)` as `put(ConfigKey, Object)` but returning this ConfigBag for fluent-style coding
`<T> ConfigBag`	`configureStringKey(java.lang.String key, T value)`
`boolean`	`containsKey(ConfigKey.HasConfigKey<?> key)`
`boolean`	`containsKey(ConfigKey<?> key)`
`boolean`	`containsKey(java.lang.String key)`
`ConfigBag`	`copy(ConfigBag other)`
`<T> T`	`get(ConfigKey<T> key)` returns the value of this config key, falling back to its default (use containsKey to see whether it was contained); also marks it as having been used (use peek to prevent marking as used)
`java.util.Map<java.lang.String,java.lang.Object>`	`getAllConfig()` current values for all entries
`java.util.Map<ConfigKey<?>,?>`	`getAllConfigAsConfigKeyMap()` current values for all entries in a map where the keys are converted to `ConfigKey` instances
`java.util.Map<java.lang.String,java.lang.Object>`	`getAllConfigMutable()` Returns the internal map containing the current values for all entries; for use where the caller wants to modify this directly and knows it is safe to do so
`java.util.Map<java.lang.String,java.lang.Object>`	`getAllConfigRaw()`
`java.lang.String`	`getDescription()` optional description used to provide context for operations
`<T> T`	`getFirst(ConfigKey<T> preferredKey, ConfigKey<T>... otherCurrentKeysInOrderOfPreference)` returns the first key in the list for which a value is explicitly set, then defaulting to defaulting value of preferred key
`java.lang.Object`	`getStringKey(java.lang.String key)` gets a value from a string-valued key or null; ConfigKey is preferred, but this is useful in some contexts (e.g.
`Maybe<java.lang.Object>`	`getStringKeyMaybe(java.lang.String key)` gets a `Maybe`-wrapped value from a string-valued key; ConfigKey is preferred, but this is useful in some contexts (e.g.
`java.util.Map<java.lang.String,java.lang.Object>`	`getUnusedConfig()` current values for all entries which have not yet been used
`java.util.Map<java.lang.String,java.lang.Object>`	`getUnusedConfigMutable()` Returns the internal map containing the current values for all entries which have not yet been used; for use where the caller wants to modify this directly and knows it is safe to do so
`java.lang.Object`	`getWithDeprecation(ConfigKey<?>[] currentKeysInOrderOfPreference, ConfigKey<?>... deprecatedKeys)` returns the value for the first key in the list for which a value is set, warning if any of the deprecated keys have a value which is different to that set on the first set current key (including warning if a deprecated key has a value but no current key does)
`java.lang.Object`	`getWithDeprecation(ConfigKey<?> key, ConfigKey<?>... deprecatedKeys)` convenience for @see #getWithDeprecation(ConfigKey[], ConfigKey...)
`boolean`	`isEmpty()`
`boolean`	`isUnused(ConfigKey<?> key)`
`ConfigBag`	`markAll(java.lang.Iterable<java.lang.String> usedFlags)`
`void`	`markUsed(java.lang.String key)` indicates that a string key in the config map has been accessed
`static ConfigBag`	`newInstance()` creates a new ConfigBag instance, empty and ready for population
`static ConfigBag`	`newInstance(java.util.Map<?,?> config)`
`static ConfigBag`	`newInstanceCopying(ConfigBag configBag)` creates a new ConfigBag instance which includes all of the supplied ConfigBag's values, but which tracks usage separately (already used values are marked as such, but uses in the original set will not be marked here, and vice versa)
`static ConfigBag`	`newInstanceExtending(ConfigBag parentBag)` creates a new ConfigBag instance which includes all of the supplied ConfigBag's values, plus an additional set of <ConfigKey,Object> or <String,Object> pairs
`static ConfigBag`	`newInstanceExtending(ConfigBag configBag, java.util.Map<?,?> optionalAdditionalValues)` As `newInstanceExtending(ConfigBag)` but also putting the supplied values.
`static ConfigBag`	`newInstanceWithInnerClass(ConfigBag configBag, java.util.Map<?,?> optionalAdditionalValues)` Deprecated. since 0.7.0, not used; kept only for rebind compatibility where the inner class is used (now replaced by a static class above)
`static ConfigBag`	`newLiveInstance(java.util.Map<java.lang.String,java.lang.Object> storage)` Creates an instance that is backed by a "live map" (e.g.
`<T> T`	`peek(ConfigKey<T> key)` like get, but without marking it as used
`<T> T`	`put(ConfigKey<T> key, T value)`
`ConfigBag`	`putAll(ConfigBag addlConfig)`
`ConfigBag`	`putAll(java.util.Map<?,?> addlConfig)`
`ConfigBag`	`putAsStringKeyIfAbsent(java.lang.Object key, java.lang.Object value)`
`ConfigBag`	`putIfAbsent(ConfigBag addlConfig)`
`<T> ConfigBag`	`putIfAbsent(ConfigKey<T> key, T value)`
`ConfigBag`	`putIfAbsent(java.util.Map<?,?> propertiesToSet)`
`<T> ConfigBag`	`putIfAbsentAndNotNull(ConfigKey<T> key, T value)`
`<T> ConfigBag`	`putIfNotNull(ConfigKey<T> key, T value)`
`java.lang.Object`	`putStringKey(java.lang.String key, java.lang.Object value)` recommended to use `put(ConfigKey, Object)` but there are times (e.g.
`java.lang.Object`	`putStringKeyIfHasValue(java.lang.String key, Maybe<?> value)`
`java.lang.Object`	`putStringKeyIfNotNull(java.lang.String key, java.lang.Object value)`
`void`	`remove(ConfigKey<?> key)`
`void`	`remove(java.lang.String key)`
`ConfigBag`	`removeAll(ConfigKey<?>... keys)`
`ConfigBag`	`removeAll(java.lang.Iterable<java.lang.String> keys)`
`ConfigBag`	`seal()` makes this config bag immutable; any attempts to change subsequently (apart from marking fields as used) will throw an exception
`ConfigBag`	`setDescription(java.lang.String description)`
`int`	`size()`
`java.lang.String`	`toString()`

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - EMPTY
```
public static final ConfigBag EMPTY
```
    an immutable, empty ConfigBag
- Constructor Detail
  - ConfigBag
```
public ConfigBag()
```
- Method Detail
  - newInstance
```
public static ConfigBag newInstance()
```
    creates a new ConfigBag instance, empty and ready for population
  - newLiveInstance
```
public static ConfigBag newLiveInstance(java.util.Map<java.lang.String,java.lang.Object> storage)
```
    Creates an instance that is backed by a "live map" (e.g. storage in a datagrid). The order-preserving nature of this class is only guaranteed if the provided storage has those properties. External modifications to the store can cause ConcurrentModificationException to be thrown, here or elsewhere.
  - newInstance
```
public static ConfigBag newInstance(java.util.Map<?,?> config)
```
  - newInstanceCopying
```
public static ConfigBag newInstanceCopying(ConfigBag configBag)
```
    creates a new ConfigBag instance which includes all of the supplied ConfigBag's values, but which tracks usage separately (already used values are marked as such, but uses in the original set will not be marked here, and vice versa)
  - newInstanceExtending
```
@Beta
public static ConfigBag newInstanceExtending(ConfigBag parentBag)
```
    creates a new ConfigBag instance which includes all of the supplied ConfigBag's values, plus an additional set of <ConfigKey,Object> or <String,Object> pairs
    values from the original set which are used here will be marked as used in the original set (note: this applies even for values which are overridden and the overridden value is used); however subsequent uses in the original set will not be marked here
  - newInstanceExtending
```
@Beta
public static ConfigBag newInstanceExtending(ConfigBag configBag,
                                  java.util.Map<?,?> optionalAdditionalValues)
```
    As newInstanceExtending(ConfigBag) but also putting the supplied values.
  - newInstanceWithInnerClass
```
@Beta
@Deprecated
public static ConfigBag newInstanceWithInnerClass(ConfigBag configBag,
                                                  java.util.Map<?,?> optionalAdditionalValues)
```
    Deprecated. since 0.7.0, not used; kept only for rebind compatibility where the inner class is used (now replaced by a static class above)
  - setDescription
```
public ConfigBag setDescription(java.lang.String description)
```
  - getDescription
```
public java.lang.String getDescription()
```
    optional description used to provide context for operations
  - getAllConfig
```
public java.util.Map<java.lang.String,java.lang.Object> getAllConfig()
```
    current values for all entries
    
    Returns:
    non-modifiable map of strings to object
  - getAllConfigAsConfigKeyMap
```
public java.util.Map<ConfigKey<?>,?> getAllConfigAsConfigKeyMap()
```
    current values for all entries in a map where the keys are converted to ConfigKey instances
  - getAllConfigMutable
```
public java.util.Map<java.lang.String,java.lang.Object> getAllConfigMutable()
```
    Returns the internal map containing the current values for all entries; for use where the caller wants to modify this directly and knows it is safe to do so
    Accesses to the returned map must be synchronized on this bag if the thread-safe behaviour is required.
  - getUnusedConfig
```
public java.util.Map<java.lang.String,java.lang.Object> getUnusedConfig()
```
    current values for all entries which have not yet been used
    
    Returns:
    non-modifiable map of strings to object
  - getUnusedConfigMutable
```
public java.util.Map<java.lang.String,java.lang.Object> getUnusedConfigMutable()
```
    Returns the internal map containing the current values for all entries which have not yet been used; for use where the caller wants to modify this directly and knows it is safe to do so
    Accesses to the returned map must be synchronized on this bag if the thread-safe behaviour is required.
  - putAll
```
public ConfigBag putAll(java.util.Map<?,?> addlConfig)
```
  - putAll
```
public ConfigBag putAll(ConfigBag addlConfig)
```
  - putIfAbsent
```
public <T> ConfigBag putIfAbsent(ConfigKey<T> key,
                        T value)
```
  - putAsStringKeyIfAbsent
```
public ConfigBag putAsStringKeyIfAbsent(java.lang.Object key,
                               java.lang.Object value)
```
  - putIfAbsent
```
public ConfigBag putIfAbsent(java.util.Map<?,?> propertiesToSet)
```
  - putIfAbsent
```
public ConfigBag putIfAbsent(ConfigBag addlConfig)
```
  - put
```
public <T> T put(ConfigKey<T> key,
        T value)
```
  - putIfNotNull
```
public <T> ConfigBag putIfNotNull(ConfigKey<T> key,
                         T value)
```
  - putIfAbsentAndNotNull
```
public <T> ConfigBag putIfAbsentAndNotNull(ConfigKey<T> key,
                                  T value)
```
  - configure
```
public <T> ConfigBag configure(ConfigKey<T> key,
                      T value)
```
    as put(ConfigKey, Object) but returning this ConfigBag for fluent-style coding
  - configureStringKey
```
public <T> ConfigBag configureStringKey(java.lang.String key,
                               T value)
```
  - putStringKey
```
public java.lang.Object putStringKey(java.lang.String key,
                            java.lang.Object value)
```
    recommended to use put(ConfigKey, Object) but there are times (e.g. when copying a map) where we want to put a string key directly
  - putStringKeyIfHasValue
```
public java.lang.Object putStringKeyIfHasValue(java.lang.String key,
                                      Maybe<?> value)
```
  - putStringKeyIfNotNull
```
public java.lang.Object putStringKeyIfNotNull(java.lang.String key,
                                     java.lang.Object value)
```
  - containsKey
```
public boolean containsKey(ConfigKey.HasConfigKey<?> key)
```
  - containsKey
```
public boolean containsKey(ConfigKey<?> key)
```
  - containsKey
```
public boolean containsKey(java.lang.String key)
```
  - get
```
public <T> T get(ConfigKey<T> key)
```
    returns the value of this config key, falling back to its default (use containsKey to see whether it was contained); also marks it as having been used (use peek to prevent marking as used)
  - getStringKey
```
public java.lang.Object getStringKey(java.lang.String key)
```
    gets a value from a string-valued key or null; ConfigKey is preferred, but this is useful in some contexts (e.g. setting from flags)
  - getStringKeyMaybe
```
@Nonnull
public Maybe<java.lang.Object> getStringKeyMaybe(java.lang.String key)
```
    gets a Maybe-wrapped value from a string-valued key; ConfigKey is preferred, but this is useful in some contexts (e.g. setting from flags)
  - peek
```
public <T> T peek(ConfigKey<T> key)
```
    like get, but without marking it as used
  - getFirst
```
public <T> T getFirst(ConfigKey<T> preferredKey,
             ConfigKey<T>... otherCurrentKeysInOrderOfPreference)
```
    returns the first key in the list for which a value is explicitly set, then defaulting to defaulting value of preferred key
  - getWithDeprecation
```
public java.lang.Object getWithDeprecation(ConfigKey<?> key,
                                  ConfigKey<?>... deprecatedKeys)
```
    convenience for @see #getWithDeprecation(ConfigKey[], ConfigKey...)
  - getWithDeprecation
```
public java.lang.Object getWithDeprecation(ConfigKey<?>[] currentKeysInOrderOfPreference,
                                  ConfigKey<?>... deprecatedKeys)
```
    returns the value for the first key in the list for which a value is set, warning if any of the deprecated keys have a value which is different to that set on the first set current key (including warning if a deprecated key has a value but no current key does)
  - coerceFirstNonNullKeyValue
```
public static <T> T coerceFirstNonNullKeyValue(ConfigKey<T> key,
                               java.lang.Object... values)
```
    returns the first non-null value to be the type indicated by the key, or the keys default value if no non-null values are supplied
  - markUsed
```
public void markUsed(java.lang.String key)
```
    indicates that a string key in the config map has been accessed
  - clear
```
public void clear()
```
  - removeAll
```
public ConfigBag removeAll(ConfigKey<?>... keys)
```
  - remove
```
public void remove(ConfigKey<?> key)
```
  - removeAll
```
public ConfigBag removeAll(java.lang.Iterable<java.lang.String> keys)
```
  - remove
```
public void remove(java.lang.String key)
```
  - copy
```
public ConfigBag copy(ConfigBag other)
```
  - size
```
public int size()
```
  - isEmpty
```
public boolean isEmpty()
```
  - markAll
```
public ConfigBag markAll(java.lang.Iterable<java.lang.String> usedFlags)
```
  - isUnused
```
public boolean isUnused(ConfigKey<?> key)
```
  - seal
```
public ConfigBag seal()
```
    makes this config bag immutable; any attempts to change subsequently (apart from marking fields as used) will throw an exception
    copies will be unsealed however
    returns this for convenience (fluent usage)
  - getAllConfigRaw
```
public java.util.Map<java.lang.String,java.lang.Object> getAllConfigRaw()
```
    See Also:
    getAllConfigMutable()
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object

Class ConfigBag

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

EMPTY

Constructor Detail

ConfigBag

Method Detail

newInstance

newLiveInstance

newInstance

newInstanceCopying

newInstanceExtending

newInstanceExtending

newInstanceWithInnerClass

setDescription

getDescription

getAllConfig

getAllConfigAsConfigKeyMap

getAllConfigMutable

getUnusedConfig

getUnusedConfigMutable

putAll

putAll

putIfAbsent

putAsStringKeyIfAbsent

putIfAbsent

putIfAbsent

put

putIfNotNull

putIfAbsentAndNotNull

configure

configureStringKey

putStringKey

putStringKeyIfHasValue

putStringKeyIfNotNull

containsKey

containsKey

containsKey

get

getStringKey

getStringKeyMaybe

peek

getFirst

getWithDeprecation

getWithDeprecation

coerceFirstNonNullKeyValue

markUsed

clear

removeAll

remove

removeAll

remove

copy

size

isEmpty

markAll

isUnused

seal

getAllConfigRaw

toString