Package 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

All Methods Static Methods Concrete Methods
`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