Package org.apache.commons.lang3.concurrent

Class 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 
      Modifier and Type Method 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

        equals, 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