org.apache.tamaya.mutableconfig

## Interface MutableConfiguration

- All Superinterfaces:
    org.apache.tamaya.Configuration
  All Known Implementing Classes:
    DefaultMutableConfiguration

      public interface MutableConfiguration
      extends org.apache.tamaya.Configuration

  This interface extends the Configuration interface hereby adding methods to change configuration entries. Hereby not all configuration entries are necessarily mutable, since some entries may be read from non mutable areas of configuration. Of course, it is always possible to add a mutable shadow layer on top of all property sources to persist/control any changes applied. The exact management and storage persistence algorithm should be transparent. As a consequence clients should first check, using the corresponding methods, if entries can be added/updated or removed. This class should only used in a single threaded context, though all methods inherited from `Configuration` must be thread-safe. Methods handling configuration changes are expected to be used in a single threaded environment only. For multi-threaded us create a new instance of `MutableConfiguration` for each thread.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `commitTransaction()` Commits the request.
    `boolean` | `getAutoCommit()` Get the current autoCommit policy.
    `ChangePropagationPolicy` | `getChangePropagationPolicy()` Access the active `ChangePropagationPolicy`.This policy controls how configuration changes are written/published to the known `MutablePropertySource` instances of a `Configuration`.
    `List<MutablePropertySource>` | `getMutablePropertySources()` Identifies the configuration backend that are targeted by this instance and which are also responsible for writing back the changes applied.
    `List<MutablePropertySource>` | `getPropertySourcesThatCanRemove(String keyExpression)` Identifies the configuration backend that know the given key(s) and support removing it/them.
    `List<MutablePropertySource>` | `getPropertySourcesThatCanWrite(String keyExpression)` Identifies the configuration backends that supports writing the given key(s).
    `List<MutablePropertySource>` | `getPropertySourcesThatKnow(String keyExpression)` Identifies the configuration backend that know the given key(s).
    `UUID` | `getTransactionId()` Get the current transaction id.
    `boolean` | `isExisting(String keyExpression)` Checks if any keys of the given type already exist in the write backend.
    `boolean` | `isRemovable(String keyExpression)` Checks if a configuration key is removable.
    `boolean` | `isWritable(String keyExpression)` Checks if a configuration key is writable (or it can be added).
    `MutableConfiguration` | `put(String key, String value)` Sets a property.
    `MutableConfiguration` | `putAll(Map<String,String> properties)` Puts all given configuration entries.
    `MutableConfiguration` | `remove(Collection<String> keys)` Removes all given configuration entries.
    `MutableConfiguration` | `remove(String... keys)` Removes all given configuration entries.
    `void` | `rollbackTransaction()` Rollback any changes leaving everything unchanged.
    `void` | `setAutoCommit(boolean autoCommit)` Set the autoCommit policy to be used for this configuration instance.
    `void` | `setChangePropagationPolicy(ChangePropagationPolicy changePropagationPolicy)` Set the `ChangePropagationPolicy`.
    `UUID` | `startTransaction()` Starts a new transaction, if necessary, and returns the transaction id.

    - ### Methods inherited from interface org.apache.tamaya.Configuration

      `get, get, get, getContext, getOrDefault, getOrDefault, getOrDefault, getProperties, query, with`

- - ### Method Detail

    - #### startTransaction

          UUID startTransaction()

      Starts a new transaction, if necessary, and returns the transaction id. New transaction are, similar to Java EE, bound to the current thread. As a consequences all properties added , updated or removed must be managed by a corresponding context, isolated by thread. The `MutablePropertySource` get the right transaction id passed, when writing (committing) any changes applied.
      Returns:
        the transaction id, not null.

    - #### commitTransaction

          void commitTransaction()

      Commits the request. After a commit the change is not editable anymore. All changes applied will be written to the corresponding configuration backend. NOTE that changes applied must not necessarily be visible in the current `Configuration` instance, since visibility of changes also depends on the ordinals set on the `PropertySource`s configured.
      Throws:
        `org.apache.tamaya.ConfigException` - if the request already has been committed or cancelled, or the commit fails.

    - #### rollbackTransaction

          void rollbackTransaction()

      Rollback any changes leaving everything unchanged. This will rollback all changes applied since the last commit.

    - #### getTransactionId

          UUID getTransactionId()

      Get the current transaction id.
      Returns:
        the current transaction id, or null, if no transaction is active.

    - #### getAutoCommit

          boolean getAutoCommit()

      Get the current autoCommit policy. AutoCommit will commit the transaction after each change applied.
      Returns:
        the current autoCommit policy, by default false.

    - #### setChangePropagationPolicy

          void setChangePropagationPolicy(ChangePropagationPolicy changePropagationPolicy)

      Set the `ChangePropagationPolicy`.
      Parameters:
        `changePropagationPolicy` - the policy, not null.
      See Also:
        `getChangePropagationPolicy()`

    - #### getChangePropagationPolicy

          ChangePropagationPolicy getChangePropagationPolicy()

      Access the active `ChangePropagationPolicy`.This policy controls how configuration changes are written/published to the known `MutablePropertySource` instances of a `Configuration`.
      Returns:
        he active `ChangePropagationPolicy`, never null.

    - #### setAutoCommit

          void setAutoCommit(boolean autoCommit)

      Set the autoCommit policy to be used for this configuration instance.
      Parameters:
        `autoCommit` - the new autoCommit policy.
      Throws:
        `IllegalStateException` - when there are uncommitted changes.

    - #### getMutablePropertySources

          List<MutablePropertySource> getMutablePropertySources()

      Identifies the configuration backend that are targeted by this instance and which are also responsible for writing back the changes applied.
      Returns:
        the property sources identified, in order of their occurrence/priority (most significant first).

    - #### isWritable

          boolean isWritable(String keyExpression)

      Checks if a configuration key is writable (or it can be added).
      Parameters:
        `keyExpression` - the key to be checked for write access (including creation), not null. Here this could also be a regular expression, such "as a.b.c.*".
      Returns:
        the boolean

    - #### getPropertySourcesThatCanWrite

          List<MutablePropertySource> getPropertySourcesThatCanWrite(String keyExpression)

      Identifies the configuration backends that supports writing the given key(s).
      Parameters:
        `keyExpression` - the key to be checked for write access (including creation), not null. Here this could also be a regular expression, such "as a.b.c.*".
      Returns:
        the property sources identified, in order of their occurrence/priority (most significant first).

    - #### isRemovable

          boolean isRemovable(String keyExpression)

      Checks if a configuration key is removable. This also implies that it is writable, but there might be writable keys that cannot be removedProperties.
      Parameters:
        `keyExpression` - the keyExpression the key to be checked for write access (including creation), not null. Here this could also be a regular expression, such "as a.b.c.*".
      Returns:
        the boolean

    - #### getPropertySourcesThatCanRemove

          List<MutablePropertySource> getPropertySourcesThatCanRemove(String keyExpression)

      Identifies the configuration backend that know the given key(s) and support removing it/them.
      Parameters:
        `keyExpression` - the key to be checked for write access (including creation), not null. Here this could also be a regular expression, such "as a.b.c.*".
      Returns:
        the property sources identified, in order of their occurrence/priority (most significant first).

    - #### isExisting

          boolean isExisting(String keyExpression)

      Checks if any keys of the given type already exist in the write backend. NOTE: there may be backends that are not able to support lookups with regular expressions. In most such cases you should pass the keys to lookup explicitly.
      Parameters:
        `keyExpression` - the key to be checked for write access (including creation), not null. Here this could also be a regular expression, such "as a.b.c.*".
      Returns:
        true, if there is any key found matching the expression.

    - #### getPropertySourcesThatKnow

          List<MutablePropertySource> getPropertySourcesThatKnow(String keyExpression)

      Identifies the configuration backend that know the given key(s).
      Parameters:
        `keyExpression` - the key to be checked for write access (including creation), not null. Here this could also be a regular expression, such "as a.b.c.*".
      Returns:
        the property sources identified, in order of their occurrence/priority (most significant first).

    - #### put

          MutableConfiguration put(String key,
                                 String value)

      Sets a property.
      Parameters:
        `key` - the property's key, not null.
        `value` - the property's value, not null.
      Returns:
        the former property value, or null.
      Throws:
        `org.apache.tamaya.ConfigException` - if the key/value cannot be added, or the request is read-only.

    - #### putAll

          MutableConfiguration putAll(Map<String,String> properties)

      Puts all given configuration entries. This method should check that all given properties are basically removable, as defined by #isWritable. If any of the passed keys is not writable during this initial check, the operation should not perform any configuration changes and throw a `ConfigException`. If errors occur afterwards, when the properties are effectively written back to the backends, the errors should be collected and returned as part of the ConfigException payload. Nevertheless the operation should in that case remove all entries as far as possible and abort the writing operation.
      Parameters:
        `properties` - the properties tobe written, not null.
      Returns:
        the config change request
      Throws:
        `org.apache.tamaya.ConfigException` - if any of the given properties could not be written, or the request is read-only.

    - #### remove

          MutableConfiguration remove(Collection<String> keys)

      Removes all given configuration entries. This method should check that all given properties are basically removable, as defined by #isRemovable. If any of the passed keys is not removable during this initial check, the operation should not perform any configuration changes and throw a `ConfigException`. If errors occur afterwards, when the properties are effectively written back to the backends, the errors should be collected and returned as part of the ConfigException payload. Nevertheless the operation should in that case remove all entries as far as possible and abort the writing operation.
      Parameters:
        `keys` - the property's keys to be removedProperties, not null.
      Returns:
        the config change request
      Throws:
        `org.apache.tamaya.ConfigException` - if any of the given keys could not be removedProperties, or the request is read-only.

    - #### remove

          MutableConfiguration remove(String... keys)

      Removes all given configuration entries. This method should check that all given properties are basically removable, as defined by #isRemovable. If any of the passed keys is not removable during this initial check, the operation should not perform any configuration changes and throw a `ConfigException`. If errors occur afterwards, when the properties are effectively written back to the backends, the errors should be collected and returned as part of the ConfigException payload. Nevertheless the operation should in that case remove all entries as far as possible and abort the writing operation.
      Parameters:
        `keys` - the property's keys to be removedProperties, not null.
      Returns:
        the config change request
      Throws:
        `org.apache.tamaya.ConfigException` - if any of the given keys could not be removedProperties, or the request is read-only.

Copyright © 2014–2016 Apache Software Foundation. All rights reserved.