IAtomicReference (Hazelcast Root 3.12-BETA-1 API)

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, RaftAtomicRefProxy
```
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

Interface IAtomicReference<E>

Method Summary

Methods inherited from interface com.hazelcast.core.DistributedObject

Method Detail

compareAndSet

get

set

getAndSet

setAndGet

isNull

clear

contains

alter

alterAndGet

getAndAlter

apply

compareAndSetAsync

getAsync

setAsync

getAndSetAsync

isNullAsync

clearAsync

containsAsync

alterAsync

alterAndGetAsync

getAndAlterAsync

applyAsync