com.hazelcast.core

## Interface IAtomicLong

- All Superinterfaces:
    DistributedObject
  All Known Subinterfaces:
    AsyncAtomicLong
  All Known Implementing Classes:
    AtomicLongProxy, ClientAtomicLongProxy

      public interface IAtomicLong
      extends DistributedObject

  IAtomicLong is a redundant and highly available distributed alternative to the `AtomicLong`.

  Asynchronous variants of all methods 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 = atomicLong.addAndGetAsync(13);
       future.andThen(new ExecutionCallback<Long>() {
           void onResponse(Long response) {
               // do something with the result
           }

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

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

  This `IAtomicLong` 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.getAtomicLong(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 IAtomicLong 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)`

  See Also:
    `IAtomicReference`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `long` | `addAndGet(long delta)` Atomically adds the given value to the current value.
    `ICompletableFuture<Long>` | `addAndGetAsync(long delta)` Atomically adds the given value to the current value.
    `void` | `alter(IFunction<Long,Long> function)` Alters the currently stored value by applying a function on it.
    `long` | `alterAndGet(IFunction<Long,Long> function)` Alters the currently stored value by applying a function on it and gets the result.
    `ICompletableFuture<Long>` | `alterAndGetAsync(IFunction<Long,Long> function)` Alters the currently stored value by applying a function on it and gets the result.
    `ICompletableFuture<Void>` | `alterAsync(IFunction<Long,Long> function)` Alters the currently stored value by applying a function on it.
    `<R> R` | `apply(IFunction<Long,R> function)` Applies a function on the value, the actual stored value will not change.
    `<R> ICompletableFuture<R>` | `applyAsync(IFunction<Long,R> function)` Applies a function on the value, the actual stored value will not change.
    `boolean` | `compareAndSet(long expect, long update)` Atomically sets the value to the given updated value only if the current value `==` the expected value.
    `ICompletableFuture<Boolean>` | `compareAndSetAsync(long expect, long update)` Atomically sets the value to the given updated value only if the current value `==` the expected value.
    `long` | `decrementAndGet()` Atomically decrements the current value by one.
    `ICompletableFuture<Long>` | `decrementAndGetAsync()` Atomically decrements the current value by one.
    `long` | `get()` Gets the current value.
    `long` | `getAndAdd(long delta)` Atomically adds the given value to the current value.
    `ICompletableFuture<Long>` | `getAndAddAsync(long delta)` Atomically adds the given value to the current value.
    `long` | `getAndAlter(IFunction<Long,Long> function)` Alters the currently stored value by applying a function on it on and gets the old value.
    `ICompletableFuture<Long>` | `getAndAlterAsync(IFunction<Long,Long> function)` Alters the currently stored value by applying a function on it on and gets the old value.
    `long` | `getAndIncrement()` Atomically increments the current value by one.
    `ICompletableFuture<Long>` | `getAndIncrementAsync()` Atomically increments the current value by one.
    `long` | `getAndSet(long newValue)` Atomically sets the given value and returns the old value.
    `ICompletableFuture<Long>` | `getAndSetAsync(long newValue)` Atomically sets the given value and returns the old value.
    `ICompletableFuture<Long>` | `getAsync()` Gets the current value.
    `String` | `getName()` Returns the name of this IAtomicLong instance.
    `long` | `incrementAndGet()` Atomically increments the current value by one.
    `ICompletableFuture<Long>` | `incrementAndGetAsync()` Atomically increments the current value by one.
    `void` | `set(long newValue)` Atomically sets the given value.
    `ICompletableFuture<Void>` | `setAsync(long newValue)` Atomically sets the given value.

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

      `destroy, getPartitionKey, getServiceName`

- - ### Method Detail

    - #### getName

          String getName()

      Returns the name of this IAtomicLong instance.
      Specified by:
        `getName` in interface `DistributedObject`
      Returns:
        the name of this IAtomicLong instance

    - #### addAndGet

          long addAndGet(long delta)

      Atomically adds the given value to the current value.
      Parameters:
        `delta` - the value to add to the current value
      Returns:
        the updated value, the given value added to the current value

    - #### compareAndSet

          boolean compareAndSet(long expect,
                                long 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.

    - #### decrementAndGet

          long decrementAndGet()

      Atomically decrements the current value by one.
      Returns:
        the updated value, the current value decremented by one

    - #### get

          long get()

      Gets the current value.
      Returns:
        the current value

    - #### getAndAdd

          long getAndAdd(long delta)

      Atomically adds the given value to the current value.
      Parameters:
        `delta` - the value to add to the current value
      Returns:
        the old value before the add

    - #### getAndSet

          long getAndSet(long newValue)

      Atomically sets the given value and returns the old value.
      Parameters:
        `newValue` - the new value
      Returns:
        the old value

    - #### incrementAndGet

          long incrementAndGet()

      Atomically increments the current value by one.
      Returns:
        the updated value, the current value incremented by one

    - #### getAndIncrement

          long getAndIncrement()

      Atomically increments the current value by one.
      Returns:
        the old value

    - #### set

          void set(long newValue)

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

    - #### alter

          void alter(IFunction<Long,Long> function)

      Alters the currently stored value by applying a function on it.
      Parameters:
        `function` - the function applied to the currently stored value
      Throws:
        `IllegalArgumentException` - if function is `null`
      Since:
        3.2

    - #### alterAndGet

          long alterAndGet(IFunction<Long,Long> function)

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

    - #### getAndAlter

          long getAndAlter(IFunction<Long,Long> function)

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

    - #### apply

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

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

    - #### addAndGetAsync

          ICompletableFuture<Long> addAndGetAsync(long delta)

      Atomically adds the given value to the current value.

      This method will dispatch a request and return immediately an `ICompletableFuture`.

      The operations result can be obtained in a blocking way, or a callback can be provided for execution upon completion, as demonstrated in the following examples:

           ICompletableFuture future = atomicLong.addAndGetAsync(13);
           // do something else, then read the result

           // this method will block until the result is available
           Long result = future.get();

           ICompletableFuture future = atomicLong.addAndGetAsync(13);
           future.andThen(new ExecutionCallback<Long>() {
               void onResponse(Long response) {
                   // do something with the result
               }

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

      Parameters:
        `delta` - the value to add
      Returns:
        an `ICompletableFuture` bearing the response
      Since:
        3.7

    - #### compareAndSetAsync

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

      Atomically sets the value to the given updated value only if the current value `==` the expected value.

      This method will dispatch a request and return immediately an `ICompletableFuture`.

      Parameters:
        `expect` - the expected value
        `update` - the new value
      Returns:
        an `ICompletableFuture` with value `true` if successful; or `false` if the actual value was not equal to the expected value
      Since:
        3.7

    - #### decrementAndGetAsync

          ICompletableFuture<Long> decrementAndGetAsync()

      Atomically decrements the current value by one.

      This method will dispatch a request and return immediately an `ICompletableFuture`.

      Returns:
        an `ICompletableFuture` with the updated value
      Since:
        3.7

    - #### getAsync

          ICompletableFuture<Long> getAsync()

      Gets the current value. This method will dispatch a request and return immediately an `ICompletableFuture`.
      Returns:
        an `ICompletableFuture` with the current value
      Since:
        3.7

    - #### getAndAddAsync

          ICompletableFuture<Long> getAndAddAsync(long delta)

      Atomically adds the given value to the current value.

      This method will dispatch a request and return immediately an `ICompletableFuture`.

      Parameters:
        `delta` - the value to add
      Returns:
        an `ICompletableFuture` with the old value before the addition
      Since:
        3.7

    - #### getAndSetAsync

          ICompletableFuture<Long> getAndSetAsync(long newValue)

      Atomically sets the given value and returns the old value.

      This method will dispatch a request and return immediately an `ICompletableFuture`.

      Parameters:
        `newValue` - the new value
      Returns:
        an `ICompletableFuture` with the old value
      Since:
        3.7

    - #### incrementAndGetAsync

          ICompletableFuture<Long> incrementAndGetAsync()

      Atomically increments the current value by one.

      This method will dispatch a request and return immediately an `ICompletableFuture`.

      Returns:
        an `ICompletableFuture` with the updated value
      Since:
        3.7

    - #### getAndIncrementAsync

          ICompletableFuture<Long> getAndIncrementAsync()

      Atomically increments the current value by one.

      This method will dispatch a request and return immediately an `ICompletableFuture`.

      Returns:
        an `ICompletableFuture` with the old value
      Since:
        3.7

    - #### setAsync

          ICompletableFuture<Void> setAsync(long newValue)

      Atomically sets the given value.

      This method will dispatch a request and return immediately an `ICompletableFuture`.

      Parameters:
        `newValue` - the new value
      Returns:
        an `ICompletableFuture`
      Since:
        3.7

    - #### alterAsync

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

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

      This method will dispatch a request and return immediately an `ICompletableFuture`.

      Parameters:
        `function` - the function
      Returns:
        an `ICompletableFuture` with the new value
      Throws:
        `IllegalArgumentException` - if function is `null`
      Since:
        3.7

    - #### alterAndGetAsync

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

      Alters the currently stored value by applying a function on it and gets the result.

      This method will dispatch a request and return immediately an `ICompletableFuture`.

      Parameters:
        `function` - the function
      Returns:
        an `ICompletableFuture` with the new value
      Throws:
        `IllegalArgumentException` - if function is `null`
      Since:
        3.7

    - #### getAndAlterAsync

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

      Alters the currently stored value by applying a function on it on and gets the old value.

      This method will dispatch a request and return immediately an `ICompletableFuture`.

      Parameters:
        `function` - the function
      Returns:
        an `ICompletableFuture` with the old value
      Throws:
        `IllegalArgumentException` - if function is `null`
      Since:
        3.7

    - #### applyAsync

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

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

      This method will dispatch a request and return immediately an `ICompletableFuture`. For example:

           class IsOneFunction implements IFunction {
               @Override
               public Boolean apply(Long input) {
                   return input.equals(1L);
               }
           }

           ICompletableFuture future = atomicLong.applyAsync(new IsOneFunction());
           future.andThen(new ExecutionCallback<;Boolean>() {
              void onResponse(Boolean response) {
                  // do something with the response
              }

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

      Parameters:
        `function` - the function
      Returns:
        an `ICompletableFuture` with the result of the function application
      Throws:
        `IllegalArgumentException` - if function is `null`
      Since:
        3.7

Copyright © 2019. All rights reserved.