org.apache.tamaya.mutableconfig.spi

## Interface MutablePropertySource

- All Superinterfaces:
    org.apache.tamaya.spi.PropertySource
  All Known Implementing Classes:
    AbstractMutablePropertySource, MutablePropertiesPropertySource, MutableXmlPropertiesPropertySource

      public interface MutablePropertySource
      extends org.apache.tamaya.spi.PropertySource

  This interface models a writable backend for configuration data. As a consequence clients should first check, using the corresponding methods, if entries are to edited or removedProperties actually are eligible for change/creation or removal.

- - ### Field Summary

    - ### Fields inherited from interface org.apache.tamaya.spi.PropertySource

      `EMPTY, TAMAYA_ORDINAL`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `commitTransaction(UUID transactionId)` Commits the request.
    `boolean` | `isRemovable(String key)` Checks if a configuration key is removable.
    `boolean` | `isWritable(String key)` Checks if a configuration key is writable (or it can be added).
    `MutablePropertySource` | `put(UUID transactionId, String key, String value)` Sets a property.
    `MutablePropertySource` | `putAll(UUID transactionId, Map<String,String> properties)` Puts all given configuration entries.
    `MutablePropertySource` | `remove(UUID transactionId, Collection<String> keys)` Removes all given configuration entries.
    `MutablePropertySource` | `remove(UUID transactionId, String... keys)` Removes all given configuration entries.
    `void` | `rollbackTransaction(UUID transactionId)` Rollback any changes leaving everything unchanged.
    `void` | `startTransaction(UUID transactionId)` Start a new transaction context with the given isolation policy.

    - ### Methods inherited from interface org.apache.tamaya.spi.PropertySource

      `get, getName, getOrdinal, getProperties, isScannable`

- - ### Method Detail

    - #### isWritable

          boolean isWritable(String key)

      Checks if a configuration key is writable (or it can be added).
      Parameters:
        `key` - the key to be checked for write access (including creation), not null.
      Returns:
        true if the key can be added or updated.

    - #### isRemovable

          boolean isRemovable(String key)

      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:
        `key` - the key to be checked for removal, not null.
      Returns:
        true, if the key can be removed.

    - #### put

          MutablePropertySource put(UUID transactionId,
                                  String key,
                                  String value)

      Sets a property.
      Parameters:
        `key` - the property's key, not null.
        `value` - the property's value, not null.
        `transactionId` - the transactionId used to isolate the change, not null.
      Returns:
        this instance for optional chaining of operations, nrvrt null.
      Throws:
        `org.apache.tamaya.ConfigException` - if the key/value cannot be added, or the request is read-only.

    - #### putAll

          MutablePropertySource putAll(UUID transactionId,
                                     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:
        `transactionId` - the transactionId used to isolate the change, not null.
        `properties` - the properties tobe written, not null.
      Returns:
        this instance for optional chaining of operations, nrvrt null.
      Throws:
        `org.apache.tamaya.ConfigException` - if any of the given properties could not be written, or the request is read-only.

    - #### remove

          MutablePropertySource remove(UUID transactionId,
                                     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:
        `transactionId` - the transactionId used to isolate the change, not null.
        `keys` - the property's keys to be removedProperties, not null.
      Returns:
        this instance for optional chaining of operations, nrvrt null.
      Throws:
        `org.apache.tamaya.ConfigException` - if any of the given keys could not be removedProperties, or the request is read-only.

    - #### remove

          MutablePropertySource remove(UUID transactionId,
                                     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:
        `transactionId` - the transactionId used to isolate the change, not null.
        `keys` - the property's keys to be removedProperties, not null.
      Returns:
        this instance for optional chaining of operations, nrvrt null.
      Throws:
        `org.apache.tamaya.ConfigException` - if any of the given keys could not be removedProperties, or the request is read-only.

    - #### commitTransaction

          void commitTransaction(UUID transactionId)

      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.
      Parameters:
        `transactionId` - the transaction id, not null.
      Throws:
        `org.apache.tamaya.ConfigException` - if the request already has been committed or cancelled, or the commit fails.

    - #### rollbackTransaction

          void rollbackTransaction(UUID transactionId)

      Rollback any changes leaving everything unchanged. This will rollback all changes applied since the last commit.
      Parameters:
        `transactionId` - the transaction id, not null.

    - #### startTransaction

          void startTransaction(UUID transactionId)

      Start a new transaction context with the given isolation policy.
      Parameters:
        `transactionId` - the transaction id, not null.

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