Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.lang3.concurrent
Class ConcurrentUtils

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

    public class ConcurrentUtils

extends Object

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

Since:
  3.0
Version:
  $Id: ConcurrentUtils.java 1199894 2011-11-09 17:53:59Z ggregory $

Method Summary
`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 Detail

### 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

### 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

### 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2011 The Apache Software Foundation. All Rights Reserved.