org.apache.tamaya.inject.api

## Interface DynamicValue<T>

- Type Parameters:
    `T` - The type of the value.
  All Known Implementing Classes:
    BaseDynamicValue

      public interface DynamicValue<T>

  A accessor for a single configured value. This can be used to support values that may change during runtime, reconfigured or final. Hereby external code (could be Tamaya configuration listners or client code), can set a new value. Depending on the `UpdatePolicy` the new value is immedeately active or it requires an active commit by client code. Similarly an instance also can ignore all later changes to the value.

  Types of this interface can be used as injection targets in injected beans or as template resiult on configuration templates.

  ### Implementation Specification

  Implementation of this interface must be
  - Serializable, when also the item stored is serializable
  - Thread safe

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addListener(PropertyChangeListener l)` Add a listener to be called as weak reference, when this value has been changed.
    `void` | `commit()` Commits a new value that has not been committed yet, make it the new value of the instance.
    `T` | `commitAndGet()` Performs a commit, if necessary, and returns the current value.
    `T` | `evaluateValue()` Evaluates the current value dynamically from the underlying configuration.
    `T` | `get()` If a value is present in this `DynamicValue`, returns the value, otherwise throws `ConfigException`.
    `T` | `getNewValue()` Access a new value that has not yet been committed.
    `UpdatePolicy` | `getUpdatePolicy()` Access the `UpdatePolicy` used for updating this value.
    `boolean` | `isPresent()` Return `true` if there is a value present, otherwise `false`.
    `T` | `orElse(T other)` Return the value if present, otherwise return `other`.
    `T` | `orElseGet(ConfiguredItemSupplier<? extends T> other)` Return the value if present, otherwise invoke `other` and return the result of that invocation.
    `<X extends Throwable> T` | `orElseThrow(ConfiguredItemSupplier<? extends X> exceptionSupplier)` Return the contained value, if present, otherwise throw an exception to be created by the provided supplier.
    `void` | `removeListener(PropertyChangeListener l)` Removes a listener to be called, when this value has been changed.
    `void` | `setUpdatePolicy(UpdatePolicy updatePolicy)` Sets a new `UpdatePolicy`.
    `boolean` | `updateValue()` Method to check for and apply a new value.

- - ### Method Detail

    - #### commitAndGet

          T commitAndGet()

      Performs a commit, if necessary, and returns the current value.
      Returns:
        the non-null value held by this `DynamicValue`
      Throws:
        `org.apache.tamaya.ConfigException` - if there is no value present
      See Also:
        `isPresent()`

    - #### commit

          void commit()

      Commits a new value that has not been committed yet, make it the new value of the instance. On change any registered listeners will be triggered.

    - #### getUpdatePolicy

          UpdatePolicy getUpdatePolicy()

      Access the `UpdatePolicy` used for updating this value.
      Returns:
        the update policy, never null.

    - #### addListener

          void addListener(PropertyChangeListener l)

      Add a listener to be called as weak reference, when this value has been changed.
      Parameters:
        `l` - the listener, not null

    - #### removeListener

          void removeListener(PropertyChangeListener l)

      Removes a listener to be called, when this value has been changed.
      Parameters:
        `l` - the listner to be removed, not null

    - #### get

          T get()

      If a value is present in this `DynamicValue`, returns the value, otherwise throws `ConfigException`.
      Returns:
        the non-null value held by this `Optional`
      Throws:
        `org.apache.tamaya.ConfigException` - if there is no value present
      See Also:
        `isPresent()`

    - #### updateValue

          boolean updateValue()

      Method to check for and apply a new value. Depending on the `UpdatePolicy` the value is immediately or deferred visible (or it may even be ignored completely).
      Returns:
        true, if a new value has been detected. The value may not be visible depending on the current `UpdatePolicy` in place.

    - #### evaluateValue

          T evaluateValue()

      Evaluates the current value dynamically from the underlying configuration.
      Returns:
        the current actual value, or null.

    - #### setUpdatePolicy

          void setUpdatePolicy(UpdatePolicy updatePolicy)

      Sets a new `UpdatePolicy`.
      Parameters:
        `updatePolicy` - the new policy, not null.

    - #### getNewValue

          T getNewValue()

      Access a new value that has not yet been committed.
      Returns:
        the uncommitted new value, or null.

    - #### isPresent

          boolean isPresent()

      Return `true` if there is a value present, otherwise `false`.
      Returns:
        `true` if there is a value present, otherwise `false`

    - #### orElse

          T orElse(T other)

      Return the value if present, otherwise return `other`.
      Parameters:
        `other` - the value to be returned if there is no value present, may be null
      Returns:
        the value, if present, otherwise `other`

    - #### orElseGet

          T orElseGet(ConfiguredItemSupplier<? extends T> other)

      Return the value if present, otherwise invoke `other` and return the result of that invocation.
      Parameters:
        `other` - a `ConfiguredItemSupplier` whose result is returned if no value is present
      Returns:
        the value if present otherwise the result of `other.get()`
      Throws:
        `NullPointerException` - if value is not present and `other` is null

    - #### orElseThrow

          <X extends Throwable> T orElseThrow(ConfiguredItemSupplier<? extends X> exceptionSupplier)
                        throws X extends Throwable

      Return the contained value, if present, otherwise throw an exception to be created by the provided supplier. NOTE A method reference to the exception constructor with an empty argument list can be used as the supplier. For example, `IllegalStateException::new`
      Type Parameters:
        `X` - Type of the exception to be thrown
      Parameters:
        `exceptionSupplier` - The supplier which will return the exception to be thrown
      Returns:
        the present value
      Throws:
        `X` - if there is no value present
        `NullPointerException` - if no value is present and `exceptionSupplier` is null
        `X extends Throwable`

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