ConcurrentUtils
Date: 2017-02-08

org.apache.commons.lang3.concurrent

## Class ConcurrentUtils

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

-     public class ConcurrentUtils
      extends java.lang.Object

  An utility class providing functionality related to the `java.util.concurrent` package.

  Since:
    3.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <T> java.util.concurrent.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(java.util.concurrent.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(java.util.concurrent.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(java.util.concurrent.ExecutionException ex)` Inspects the cause of the specified `ExecutionException` and creates a `ConcurrentException` with the checked cause if necessary.
    `static ConcurrentRuntimeException` | `extractCauseUnchecked(java.util.concurrent.ExecutionException ex)` Inspects the cause of the specified `ExecutionException` and creates a `ConcurrentRuntimeException` with the checked cause if necessary.
    `static void` | `handleCause(java.util.concurrent.ExecutionException ex)` Handles the specified `ExecutionException`.
    `static void` | `handleCauseUnchecked(java.util.concurrent.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(java.util.concurrent.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 Detail

    - #### extractCause

          public static ConcurrentException extractCause(java.util.concurrent.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(java.util.concurrent.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(java.util.concurrent.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(java.util.concurrent.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(java.util.concurrent.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

    - #### createIfAbsent

          public static <K,V> V createIfAbsent(java.util.concurrent.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(java.util.concurrent.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

    - #### constantFuture

          public static <T> java.util.concurrent.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