Package com.hazelcast.cp

Interface IAtomicReference<E>

Type Parameters:

E - the type of object referred to by this reference

All Superinterfaces:

DistributedObject

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 a CompletionStage 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:

 CompletionStage<E> future = atomicRef.getAsync();
 future.whenCompleteAsync((v, throwable) -> {
     if (throwable == null) {
         // do something with the old value returned by put operation
     } else {
         // handle failure
     }
 });
 

Actions supplied for dependent completions of default non-async methods and async methods without an explicit Executor argument are performed by the ForkJoinPool.commonPool() (unless it does not support a parallelism level of at least 2, in which case a new Thread is created per task).

IAtomicReference is accessed via CPSubsystem.getAtomicReference(String). 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.

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

Modifier and Type	Method	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.
java.util.concurrent.CompletionStage<E>	alterAndGetAsync(IFunction<E,E> function)	Alters the currently stored reference by applying a function on it and gets the result.
java.util.concurrent.CompletionStage<java.lang.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> java.util.concurrent.CompletionStage<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.
java.util.concurrent.CompletionStage<java.lang.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.
java.util.concurrent.CompletionStage<java.lang.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.
java.util.concurrent.CompletionStage<java.lang.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.
java.util.concurrent.CompletionStage<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.
java.util.concurrent.CompletionStage<E>	getAndSetAsync(E newValue)	Gets the value and sets the new value.
java.util.concurrent.CompletionStage<E>	getAsync()	Gets the current value.
boolean	isNull()	Checks if the stored reference is null.
java.util.concurrent.CompletionStage<java.lang.Boolean>	isNullAsync()	Checks if the stored reference is null.
void	set(E newValue)	Atomically sets the given value.
java.util.concurrent.CompletionStage<java.lang.Void>	setAsync(E newValue)	Atomically sets the given value.

Methods inherited from interface com.hazelcast.core.DistributedObject

destroy, getDestroyContextForTenant, 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

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:

java.lang.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:

java.lang.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:

java.lang.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.

Type Parameters:

R - the result type of the function

Parameters:

function - the function applied on the value, the stored value does not change

Returns:

the result of the function application

Throws:

java.lang.IllegalArgumentException - if function is null

compareAndSetAsync

java.util.concurrent.CompletionStage<java.lang.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

java.util.concurrent.CompletionStage<E> getAsync()

Gets the current value.

Returns:

the current value

setAsync

java.util.concurrent.CompletionStage<java.lang.Void> setAsync(E newValue)

Atomically sets the given value.

Parameters:

newValue - the new value

getAndSetAsync

java.util.concurrent.CompletionStage<E> getAndSetAsync(E newValue)

Gets the value and sets the new value.

Parameters:

newValue - the new value

Returns:

the old value

isNullAsync

java.util.concurrent.CompletionStage<java.lang.Boolean> isNullAsync()

Checks if the stored reference is null.

Returns:

true if null, false otherwise

clearAsync

java.util.concurrent.CompletionStage<java.lang.Void> clearAsync()

Clears the current stored reference.

containsAsync

java.util.concurrent.CompletionStage<java.lang.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

java.util.concurrent.CompletionStage<java.lang.Void> alterAsync(IFunction<E,E> function)

Alters the currently stored reference by applying a function on it.

Parameters:

function - the function

Throws:

java.lang.IllegalArgumentException - if function is null

alterAndGetAsync

java.util.concurrent.CompletionStage<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:

java.lang.IllegalArgumentException - if function is null

getAndAlterAsync

java.util.concurrent.CompletionStage<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:

java.lang.IllegalArgumentException - if function is null

applyAsync

<R> java.util.concurrent.CompletionStage<R> applyAsync(IFunction<E,R> function)

Applies a function on the value, the actual stored value will not change.

Type Parameters:

R - the result type of the function

Parameters:

function - the function

Returns:

the result of the function application

Throws:

java.lang.IllegalArgumentException - if function is null