com.hazelcast.core

## Interface IAtomicReference<E>

- Type Parameters:
    `E` - the type of object referred to by this reference
  All Superinterfaces:
    DistributedObject
  All Known Subinterfaces:
    AsyncAtomicReference<E>
  All Known Implementing Classes:
    AtomicReferenceProxy, ClientAtomicReferenceProxy

      public interface IAtomicReference<E>
      extends DistributedObject

  IAtomicReference is a redundant and highly available distributed alternative to the `AtomicReference`.

  Asynchronous variants have been introduced in version 3.7. Async methods immediately return an `ICompletableFuture` from which the operation's result can be obtained either in a blocking manner or by registering a callback to be executed upon completion. For example:

       ICompletableFuture future = atomicRef.getAsync();
       future.andThen(new ExecutionCallback() {
           void onResponse(Long response) {
               // do something with the result
           }

           void onFailure(Throwable t) {
               // handle failure
           }
       });

  As of version 3.12, Hazelcast offers 2 different `IAtomicReference` impls. Behaviour of `IAtomicReference` under failure scenarios, including network partitions, depends on the impl. The first impl is the good old `IAtomicReference` that is accessed via `HazelcastInstance.getAtomicReference(String)`. It works on top of Hazelcast's async replication algorithm and does not guarantee linearizability during failures. It is possible for an `IAtomicReference` instance to exist in each of the partitioned clusters or to not exist at all. Under these circumstances, the values held in the `IAtomicReference` instance may diverge. Once the network partition heals, Hazelcast will use the configured split-brain merge policy to resolve conflicting values.

  This `IAtomicReference` impl also supports Quorum `QuorumConfig` in cluster versions 3.10 and higher. However, Hazelcast quorums do not guarantee strong consistency under failure scenarios.

  The second impl is a new one introduced with the `CPSubsystem` in version 3.12. It is accessed via `CPSubsystem.getAtomicReference(String)`. It has a major difference to the old implementation, that is, it works on top of the Raft consensus algorithm. It offers linearizability during crash failures and network partitions. It is CP with respect to the CAP principle. If a network partition occurs, it remains available on at most one side of the partition.

  The CP IAtomicReference impl does not offer exactly-once / effectively-once execution semantics. It goes with at-least-once execution semantics by default and can cause an API call to be committed multiple times in case of CP member failures. It can be tuned to offer at-most-once execution semantics. Please see `CPSubsystemConfig.setFailOnIndeterminateOperationState(boolean)`

  Since:
    3.2
  See Also:
    `IAtomicLong`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `alter(IFunction<E,E> function)` Alters the currently stored reference by applying a function on it.
    `E` | `alterAndGet(IFunction<E,E> function)` Alters the currently stored reference by applying a function on it and gets the result.
    `ICompletableFuture<E>` | `alterAndGetAsync(IFunction<E,E> function)` Alters the currently stored reference by applying a function on it and gets the result.
    `ICompletableFuture<Void>` | `alterAsync(IFunction<E,E> function)` Alters the currently stored reference by applying a function on it.
    `<R> R` | `apply(IFunction<E,R> function)` Applies a function on the value, the actual stored value will not change.
    `<R> ICompletableFuture<R>` | `applyAsync(IFunction<E,R> function)` Applies a function on the value, the actual stored value will not change.
    `void` | `clear()` Clears the current stored reference.
    `ICompletableFuture<Void>` | `clearAsync()` Clears the current stored reference.
    `boolean` | `compareAndSet(E expect, E update)` Atomically sets the value to the given updated value only if the current value `==` the expected value.
    `ICompletableFuture<Boolean>` | `compareAndSetAsync(E expect, E update)` Atomically sets the value to the given updated value only if the current value `==` the expected value.
    `boolean` | `contains(E value)` Checks if the reference contains the value.
    `ICompletableFuture<Boolean>` | `containsAsync(E expected)` Checks if the reference contains the value.
    `E` | `get()` Gets the current value.
    `E` | `getAndAlter(IFunction<E,E> function)` Alters the currently stored reference by applying a function on it on and gets the old value.
    `ICompletableFuture<E>` | `getAndAlterAsync(IFunction<E,E> function)` Alters the currently stored reference by applying a function on it on and gets the old value.
    `E` | `getAndSet(E newValue)` Gets the old value and sets the new value.
    `ICompletableFuture<E>` | `getAndSetAsync(E newValue)` Gets the value and sets the new value.
    `ICompletableFuture<E>` | `getAsync()` Gets the current value.
    `boolean` | `isNull()` Checks if the stored reference is `null`.
    `ICompletableFuture<Boolean>` | `isNullAsync()` Checks if the stored reference is `null`.
    `void` | `set(E newValue)` Atomically sets the given value.
    `E` | `setAndGet(E update)` Deprecated. will be removed from Hazelcast 3.4 since it doesn't really serve a purpose
    `ICompletableFuture<Void>` | `setAsync(E newValue)` Atomically sets the given value.

    - ### Methods inherited from interface com.hazelcast.core.DistributedObject

      `destroy, getName, getPartitionKey, getServiceName`

- - ### Method Detail

    - #### compareAndSet

          boolean compareAndSet(E expect,
                                E update)

      Atomically sets the value to the given updated value only if the current value `==` the expected value.
      Parameters:
        `expect` - the expected value
        `update` - the new value
      Returns:
        `true` if successful; or `false` if the actual value was not equal to the expected value

    - #### get

          E get()

      Gets the current value.
      Returns:
        the current value

    - #### set

          void set(E newValue)

      Atomically sets the given value.
      Parameters:
        `newValue` - the new value

    - #### getAndSet

          E getAndSet(E newValue)

      Gets the old value and sets the new value.
      Parameters:
        `newValue` - the new value
      Returns:
        the old value

    - #### setAndGet

          E setAndGet(E update)

      Deprecated. will be removed from Hazelcast 3.4 since it doesn't really serve a purpose
      Sets and gets the value.
      Parameters:
        `update` - the new value
      Returns:
        the new value

    - #### isNull

          boolean isNull()

      Checks if the stored reference is `null`.
      Returns:
        `true` if `null`, `false` otherwise

    - #### clear

          void clear()

      Clears the current stored reference.

    - #### contains

          boolean contains(E value)

      Checks if the reference contains the value.
      Parameters:
        `value` - the value to check (is allowed to be `null`)
      Returns:
        `true` if the value is found, `false` otherwise

    - #### alter

          void alter(IFunction<E,E> function)

      Alters the currently stored reference by applying a function on it.
      Parameters:
        `function` - the function that alters the currently stored reference
      Throws:
        `IllegalArgumentException` - if function is `null`

    - #### alterAndGet

          E alterAndGet(IFunction<E,E> function)

      Alters the currently stored reference by applying a function on it and gets the result.
      Parameters:
        `function` - the function that alters the currently stored reference
      Returns:
        the new value, the result of the applied function
      Throws:
        `IllegalArgumentException` - if function is `null`

    - #### getAndAlter

          E getAndAlter(IFunction<E,E> function)

      Alters the currently stored reference by applying a function on it on and gets the old value.
      Parameters:
        `function` - the function that alters the currently stored reference
      Returns:
        the old value, the value before the function is applied
      Throws:
        `IllegalArgumentException` - if function is `null`

    - #### apply

          <R> R apply(IFunction<E,R> function)

      Applies a function on the value, the actual stored value will not change.
      Parameters:
        `function` - the function applied on the value, the stored value does not change
      Returns:
        the result of the function application
      Throws:
        `IllegalArgumentException` - if function is `null`

    - #### compareAndSetAsync

          ICompletableFuture<Boolean> compareAndSetAsync(E expect,
                                                         E update)

      Atomically sets the value to the given updated value only if the current value `==` the expected value.
      Parameters:
        `expect` - the expected value
        `update` - the new value
      Returns:
        `true` if successful; or `false` if the actual value was not equal to the expected value

    - #### getAsync

          ICompletableFuture<E> getAsync()

      Gets the current value.
      Returns:
        the current value

    - #### setAsync

          ICompletableFuture<Void> setAsync(E newValue)

      Atomically sets the given value.
      Parameters:
        `newValue` - the new value

    - #### getAndSetAsync

          ICompletableFuture<E> getAndSetAsync(E newValue)

      Gets the value and sets the new value.
      Parameters:
        `newValue` - the new value
      Returns:
        the old value

    - #### isNullAsync

          ICompletableFuture<Boolean> isNullAsync()

      Checks if the stored reference is `null`.
      Returns:
        `true` if `null`, `false` otherwise

    - #### clearAsync

          ICompletableFuture<Void> clearAsync()

      Clears the current stored reference.

    - #### containsAsync

          ICompletableFuture<Boolean> containsAsync(E expected)

      Checks if the reference contains the value.
      Parameters:
        `expected` - the value to check (is allowed to be null)
      Returns:
        `true` if the value is found, `false` otherwise

    - #### alterAsync

          ICompletableFuture<Void> alterAsync(IFunction<E,E> function)

      Alters the currently stored reference by applying a function on it.
      Parameters:
        `function` - the function
      Throws:
        `IllegalArgumentException` - if function is `null`

    - #### alterAndGetAsync

          ICompletableFuture<E> alterAndGetAsync(IFunction<E,E> function)

      Alters the currently stored reference by applying a function on it and gets the result.
      Parameters:
        `function` - the function
      Returns:
        the new value
      Throws:
        `IllegalArgumentException` - if function is `null`

    - #### getAndAlterAsync

          ICompletableFuture<E> getAndAlterAsync(IFunction<E,E> function)

      Alters the currently stored reference by applying a function on it on and gets the old value.
      Parameters:
        `function` - the function
      Returns:
        the old value
      Throws:
        `IllegalArgumentException` - if function is `null`

    - #### applyAsync

          <R> ICompletableFuture<R> applyAsync(IFunction<E,R> function)

      Applies a function on the value, the actual stored value will not change.
      Parameters:
        `function` - the function
      Returns:
        the result of the function application
      Throws:
        `IllegalArgumentException` - if function is `null`

Copyright © 2019. All rights reserved.