ConcurrentUtils (Apache Commons Lang 3.17.0 API)
Description: declaration: package: org.apache.commons.lang3.concurrent, class: ConcurrentUtils

Package org.apache.commons.lang3.concurrent

# Class ConcurrentUtils

java.lang.Object
org.apache.commons.lang3.concurrent.ConcurrentUtils

public class ConcurrentUtils extends Object
A utility class providing functionality related to the `java.util.concurrent` package.

Since:
  3.0

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <T> Future<T>`
  `constantFuture(T value)`
  Gets an implementation of `Future` that is immediately done and returns the specified constant value.
  `static <K, V> V`
  `createIfAbsent(ConcurrentMap<K,V> map, K key, ConcurrentInitializer<V> init)`
  Checks if a concurrent map contains a key and creates a corresponding value if not.
  `static <K, V> V`
  `createIfAbsentUnchecked(ConcurrentMap<K,V> map, K key, ConcurrentInitializer<V> init)`
  Checks if a concurrent map contains a key and creates a corresponding value if not, suppressing checked exceptions.
  `static ConcurrentException`
  `extractCause(ExecutionException ex)`
  Inspects the cause of the specified `ExecutionException` and creates a `ConcurrentException` with the checked cause if necessary.
  `static ConcurrentRuntimeException`
  `extractCauseUnchecked(ExecutionException ex)`
  Inspects the cause of the specified `ExecutionException` and creates a `ConcurrentRuntimeException` with the checked cause if necessary.
  `static void`
  `handleCause(ExecutionException ex)`
  Handles the specified `ExecutionException`.
  `static void`
  `handleCauseUnchecked(ExecutionException ex)`
  Handles the specified `ExecutionException` and transforms it into a runtime exception.
  `static <T> T`
  `initialize(ConcurrentInitializer<T> initializer)`
  Invokes the specified `ConcurrentInitializer` and returns the object produced by the initializer.
  `static <T> T`
  `initializeUnchecked(ConcurrentInitializer<T> initializer)`
  Invokes the specified `ConcurrentInitializer` and transforms occurring exceptions to runtime exceptions.
  `static <K, V> V`
  `putIfAbsent(ConcurrentMap<K,V> map, K key, V value)`
  Puts a value in the specified `ConcurrentMap` if the key is not yet present.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### constantFuture

    public static <T> Future<T> constantFuture(T value)
    Gets an implementation of `Future` that is immediately done and returns the specified constant value.

    This can be useful to return a simple constant immediately from the concurrent processing, perhaps as part of avoiding nulls. A constant future can also be useful in testing.

    Type Parameters:
      `T` - the type of the value used by this `Future` object
    Parameters:
      `value` - the constant value to return, may be null
    Returns:
      an instance of Future that will return the value, never null

  - ### createIfAbsent

    public static <K, V> V createIfAbsent(ConcurrentMap<K,V> map, K key, ConcurrentInitializer<V> init) throws ConcurrentException
    Checks if a concurrent map contains a key and creates a corresponding value if not. This method first checks the presence of the key in the given map. If it is already contained, its value is returned. Otherwise the `get()` method of the passed in `ConcurrentInitializer` is called. With the resulting object `putIfAbsent(ConcurrentMap, Object, Object)` is called. This handles the case that in the meantime another thread has added the key to the map. Both the map and the initializer can be null; in this case this method simply returns null.
    Type Parameters:
      `K` - the type of the keys of the map
      `V` - the type of the values of the map
    Parameters:
      `map` - the map to be modified
      `key` - the key of the value to be added
      `init` - the `ConcurrentInitializer` for creating the value
    Returns:
      the value stored in the map after this operation; this may or may not be the object created by the `ConcurrentInitializer`
    Throws:
      `ConcurrentException` - if the initializer throws an exception

  - ### createIfAbsentUnchecked

    public static <K, V> V createIfAbsentUnchecked(ConcurrentMap<K,V> map, K key, ConcurrentInitializer<V> init)
    Checks if a concurrent map contains a key and creates a corresponding value if not, suppressing checked exceptions. This method calls `createIfAbsent()`. If a `ConcurrentException` is thrown, it is caught and re-thrown as a `ConcurrentRuntimeException`.
    Type Parameters:
      `K` - the type of the keys of the map
      `V` - the type of the values of the map
    Parameters:
      `map` - the map to be modified
      `key` - the key of the value to be added
      `init` - the `ConcurrentInitializer` for creating the value
    Returns:
      the value stored in the map after this operation; this may or may not be the object created by the `ConcurrentInitializer`
    Throws:
      `ConcurrentRuntimeException` - if the initializer throws an exception

  - ### extractCause

    public static ConcurrentException extractCause(ExecutionException ex)
    Inspects the cause of the specified `ExecutionException` and creates a `ConcurrentException` with the checked cause if necessary. This method performs the following checks on the cause of the passed in exception:
    - If the passed in exception is null or the cause is null, this method returns null.
    - If the cause is a runtime exception, it is directly thrown.
    - If the cause is an error, it is directly thrown, too.
    - In any other case the cause is a checked exception. The method then creates a `ConcurrentException`, initializes it with the cause, and returns it.
    Parameters:
      `ex` - the exception to be processed
    Returns:
      a `ConcurrentException` with the checked cause

  - ### extractCauseUnchecked

    public static ConcurrentRuntimeException extractCauseUnchecked(ExecutionException ex)
    Inspects the cause of the specified `ExecutionException` and creates a `ConcurrentRuntimeException` with the checked cause if necessary. This method works exactly like `extractCause(ExecutionException)`. The only difference is that the cause of the specified `ExecutionException` is extracted as a runtime exception. This is an alternative for client code that does not want to deal with checked exceptions.
    Parameters:
      `ex` - the exception to be processed
    Returns:
      a `ConcurrentRuntimeException` with the checked cause

  - ### handleCause

    public static void handleCause(ExecutionException ex) throws ConcurrentException
    Handles the specified `ExecutionException`. This method calls `extractCause(ExecutionException)` for obtaining the cause of the exception - which might already cause an unchecked exception or an error being thrown. If the cause is a checked exception however, it is wrapped in a `ConcurrentException`, which is thrown. If the passed in exception is null or has no cause, the method simply returns without throwing an exception.
    Parameters:
      `ex` - the exception to be handled
    Throws:
      `ConcurrentException` - if the cause of the `ExecutionException` is a checked exception

  - ### handleCauseUnchecked

    public static void handleCauseUnchecked(ExecutionException ex)
    Handles the specified `ExecutionException` and transforms it into a runtime exception. This method works exactly like `handleCause(ExecutionException)`, but instead of a `ConcurrentException` it throws a `ConcurrentRuntimeException`. This is an alternative for client code that does not want to deal with checked exceptions.
    Parameters:
      `ex` - the exception to be handled
    Throws:
      `ConcurrentRuntimeException` - if the cause of the `ExecutionException` is a checked exception; this exception is then wrapped in the thrown runtime exception

  - ### initialize

    public static <T> T initialize(ConcurrentInitializer<T> initializer) throws ConcurrentException
    Invokes the specified `ConcurrentInitializer` and returns the object produced by the initializer. This method just invokes the `get()` method of the given `ConcurrentInitializer`. It is null-safe: if the argument is null, result is also null.
    Type Parameters:
      `T` - the type of the object produced by the initializer
    Parameters:
      `initializer` - the `ConcurrentInitializer` to be invoked
    Returns:
      the object managed by the `ConcurrentInitializer`
    Throws:
      `ConcurrentException` - if the `ConcurrentInitializer` throws an exception

  - ### initializeUnchecked

    public static <T> T initializeUnchecked(ConcurrentInitializer<T> initializer)
    Invokes the specified `ConcurrentInitializer` and transforms occurring exceptions to runtime exceptions. This method works like `initialize(ConcurrentInitializer)`, but if the `ConcurrentInitializer` throws a `ConcurrentException`, it is caught, and the cause is wrapped in a `ConcurrentRuntimeException`. So client code does not have to deal with checked exceptions.
    Type Parameters:
      `T` - the type of the object produced by the initializer
    Parameters:
      `initializer` - the `ConcurrentInitializer` to be invoked
    Returns:
      the object managed by the `ConcurrentInitializer`
    Throws:
      `ConcurrentRuntimeException` - if the initializer throws an exception

  - ### putIfAbsent

    public static <K, V> V putIfAbsent(ConcurrentMap<K,V> map, K key, V value)
    Puts a value in the specified `ConcurrentMap` if the key is not yet present. This method works similar to the `putIfAbsent()` method of the `ConcurrentMap` interface, but the value returned is different. Basically, this method is equivalent to the following code fragment:

         if (!map.containsKey(key)) {
             map.put(key, value);
             return value;
         } else {
             return map.get(key);
         }

    except that the action is performed atomically. So this method always returns the value which is stored in the map.

    This method is null-safe: It accepts a null map as input without throwing an exception. In this case the return value is null, too.

    Type Parameters:
      `K` - the type of the keys of the map
      `V` - the type of the values of the map
    Parameters:
      `map` - the map to be modified
      `key` - the key of the value to be added
      `value` - the value to be added
    Returns:
      the value stored in the map after this operation