/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.lang3.concurrent;

import java.util.concurrent.ConcurrentMap;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;

import org.apache.commons.lang3.Validate;

 An utility class providing functionality related to the 
java.util.concurrent package. 
Since:
3.0/**
 * <p>
 * An utility class providing functionality related to the {@code
 * java.util.concurrent} package.
 * </p>
 *
 * @since 3.0
 */
public class ConcurrentUtils {

    
Private constructor so that no instances can be created. This class
contains only static utility methods.
/**
     * Private constructor so that no instances can be created. This class
     * contains only static utility methods.
     */
    private ConcurrentUtils() {
    }

    
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.

Params:
ex – the exception to be processed
Returns:
a ConcurrentException with the checked cause/**
     * Inspects the cause of the specified {@code ExecutionException} and
     * creates a {@code ConcurrentException} with the checked cause if
     * necessary. This method performs the following checks on the cause of the
     * passed in exception:
     * <ul>
     * <li>If the passed in exception is <b>null</b> or the cause is
     * <b>null</b>, this method returns <b>null</b>.</li>
     * <li>If the cause is a runtime exception, it is directly thrown.</li>
     * <li>If the cause is an error, it is directly thrown, too.</li>
     * <li>In any other case the cause is a checked exception. The method then
     * creates a {@link ConcurrentException}, initializes it with the cause, and
     * returns it.</li>
     * </ul>
     *
     * @param ex the exception to be processed
     * @return a {@code ConcurrentException} with the checked cause
     */
    public static ConcurrentException extractCause(final ExecutionException ex) {
        if (ex == null || ex.getCause() == null) {
            return null;
        }

        throwCause(ex);
        return new ConcurrentException(ex.getMessage(), ex.getCause());
    }

    
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. 
Params:
ex – the exception to be processed
Returns:
a ConcurrentRuntimeException with the checked cause/**
     * Inspects the cause of the specified {@code ExecutionException} and
     * creates a {@code ConcurrentRuntimeException} with the checked cause if
     * necessary. This method works exactly like
     * {@link #extractCause(ExecutionException)}. The only difference is that
     * the cause of the specified {@code ExecutionException} is extracted as a
     * runtime exception. This is an alternative for client code that does not
     * want to deal with checked exceptions.
     *
     * @param ex the exception to be processed
     * @return a {@code ConcurrentRuntimeException} with the checked cause
     */
    public static ConcurrentRuntimeException extractCauseUnchecked(
            final ExecutionException ex) {
        if (ex == null || ex.getCause() == null) {
            return null;
        }

        throwCause(ex);
        return new ConcurrentRuntimeException(ex.getMessage(), ex.getCause());
    }

    
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.
Params:
ex – the exception to be handled
Throws:
ConcurrentException – if the cause of the 
ExecutionException is a checked exception/**
     * Handles the specified {@code ExecutionException}. This method calls
     * {@link #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 {@code ConcurrentException}, which is thrown. If the passed in
     * exception is <b>null</b> or has no cause, the method simply returns
     * without throwing an exception.
     *
     * @param ex the exception to be handled
     * @throws ConcurrentException if the cause of the {@code
     * ExecutionException} is a checked exception
     */
    public static void handleCause(final ExecutionException ex)
            throws ConcurrentException {
        final ConcurrentException cex = extractCause(ex);

        if (cex != null) {
            throw cex;
        }
    }

    
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. 
Params:
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/**
     * Handles the specified {@code ExecutionException} and transforms it into a
     * runtime exception. This method works exactly like
     * {@link #handleCause(ExecutionException)}, but instead of a
     * {@link ConcurrentException} it throws a
     * {@link ConcurrentRuntimeException}. This is an alternative for client
     * code that does not want to deal with checked exceptions.
     *
     * @param ex the exception to be handled
     * @throws ConcurrentRuntimeException if the cause of the {@code
     * ExecutionException} is a checked exception; this exception is then
     * wrapped in the thrown runtime exception
     */
    public static void handleCauseUnchecked(final ExecutionException ex) {
        final ConcurrentRuntimeException crex = extractCauseUnchecked(ex);

        if (crex != null) {
            throw crex;
        }
    }

    
Tests whether the specified Throwable is a checked exception. If not, an exception is thrown. 
Params:
ex – the Throwable to check
Throws:
IllegalArgumentException – if the Throwable is not a checked exception
Returns:
a flag whether the passed in exception is a checked exception/**
     * Tests whether the specified {@code Throwable} is a checked exception. If
     * not, an exception is thrown.
     *
     * @param ex the {@code Throwable} to check
     * @return a flag whether the passed in exception is a checked exception
     * @throws IllegalArgumentException if the {@code Throwable} is not a
     * checked exception
     */
    static Throwable checkedException(final Throwable ex) {
        Validate.isTrue(ex != null && !(ex instanceof RuntimeException)
                && !(ex instanceof Error), "Not a checked exception: " + ex);

        return ex;
    }

    
Tests whether the cause of the specified ExecutionException should be thrown and does it if necessary. 
Params:
ex – the exception in question/**
     * Tests whether the cause of the specified {@code ExecutionException}
     * should be thrown and does it if necessary.
     *
     * @param ex the exception in question
     */
    private static void throwCause(final ExecutionException ex) {
        if (ex.getCause() instanceof RuntimeException) {
            throw (RuntimeException) ex.getCause();
        }

        if (ex.getCause() instanceof Error) {
            throw (Error) ex.getCause();
        }
    }

    //-----------------------------------------------------------------------
    
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.
Params:
initializer – the ConcurrentInitializer to be invoked
Type parameters:
<T> – the type of the object produced by the initializer
Throws:
ConcurrentException – if the ConcurrentInitializer throws an exception
Returns:
the object managed by the ConcurrentInitializer/**
     * Invokes the specified {@code ConcurrentInitializer} and returns the
     * object produced by the initializer. This method just invokes the {@code
     * get()} method of the given {@code ConcurrentInitializer}. It is
     * <b>null</b>-safe: if the argument is <b>null</b>, result is also
     * <b>null</b>.
     *
     * @param <T> the type of the object produced by the initializer
     * @param initializer the {@code ConcurrentInitializer} to be invoked
     * @return the object managed by the {@code ConcurrentInitializer}
     * @throws ConcurrentException if the {@code ConcurrentInitializer} throws
     * an exception
     */
    public static <T> T initialize(final ConcurrentInitializer<T> initializer)
            throws ConcurrentException {
        return initializer != null ? initializer.get() : null;
    }

    
Invokes the specified ConcurrentInitializer and transforms occurring exceptions to runtime exceptions. This method works like initialize(ConcurrentInitializer<Object>), 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. 
Params:
initializer – the ConcurrentInitializer to be invoked
Type parameters:
<T> – the type of the object produced by the initializer
Throws:
ConcurrentRuntimeException – if the initializer throws an exception
Returns:
the object managed by the ConcurrentInitializer/**
     * Invokes the specified {@code ConcurrentInitializer} and transforms
     * occurring exceptions to runtime exceptions. This method works like
     * {@link #initialize(ConcurrentInitializer)}, but if the {@code
     * ConcurrentInitializer} throws a {@link ConcurrentException}, it is
     * caught, and the cause is wrapped in a {@link ConcurrentRuntimeException}.
     * So client code does not have to deal with checked exceptions.
     *
     * @param <T> the type of the object produced by the initializer
     * @param initializer the {@code ConcurrentInitializer} to be invoked
     * @return the object managed by the {@code ConcurrentInitializer}
     * @throws ConcurrentRuntimeException if the initializer throws an exception
     */
    public static <T> T initializeUnchecked(final ConcurrentInitializer<T> initializer) {
        try {
            return initialize(initializer);
        } catch (final ConcurrentException cex) {
            throw new ConcurrentRuntimeException(cex.getCause());
        }
    }

    //-----------------------------------------------------------------------
    
 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.

Params:
map – the map to be modified
key – the key of the value to be added
value – the value to be added
Type parameters:
<K> – the type of the keys of the map
<V> – the type of the values of the map
Returns:
the value stored in the map after this operation/**
     * <p>
     * Puts a value in the specified {@code ConcurrentMap} if the key is not yet
     * present. This method works similar to the {@code putIfAbsent()} method of
     * the {@code ConcurrentMap} interface, but the value returned is different.
     * Basically, this method is equivalent to the following code fragment:
     * </p>
     *
     * <pre>
     * if (!map.containsKey(key)) {
     *     map.put(key, value);
     *     return value;
     * } else {
     *     return map.get(key);
     * }
     * </pre>
     *
     * <p>
     * except that the action is performed atomically. So this method always
     * returns the value which is stored in the map.
     * </p>
     * <p>
     * This method is <b>null</b>-safe: It accepts a <b>null</b> map as input
     * without throwing an exception. In this case the return value is
     * <b>null</b>, too.
     * </p>
     *
     * @param <K> the type of the keys of the map
     * @param <V> the type of the values of the map
     * @param map the map to be modified
     * @param key the key of the value to be added
     * @param value the value to be added
     * @return the value stored in the map after this operation
     */
    public static <K, V> V putIfAbsent(final ConcurrentMap<K, V> map, final K key, final V value) {
        if (map == null) {
            return null;
        }

        final V result = map.putIfAbsent(key, value);
        return result != null ? result : value;
    }

    
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>, 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.
Params:
map – the map to be modified
key – the key of the value to be added
init – the ConcurrentInitializer for creating the value
Type parameters:
<K> – the type of the keys of the map
<V> – the type of the values of the map
Throws:
ConcurrentException – if the initializer throws an exception
Returns:
the value stored in the map after this operation; this may or may not be the object created by the ConcurrentInitializer/**
     * 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 {@code get()} method of the passed in {@link ConcurrentInitializer}
     * is called. With the resulting object
     * {@link #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 <b>null</b>; in this
     * case this method simply returns <b>null</b>.
     *
     * @param <K> the type of the keys of the map
     * @param <V> the type of the values of the map
     * @param map the map to be modified
     * @param key the key of the value to be added
     * @param init the {@link ConcurrentInitializer} for creating the value
     * @return the value stored in the map after this operation; this may or may
     * not be the object created by the {@link ConcurrentInitializer}
     * @throws ConcurrentException if the initializer throws an exception
     */
    public static <K, V> V createIfAbsent(final ConcurrentMap<K, V> map, final K key,
            final ConcurrentInitializer<V> init) throws ConcurrentException {
        if (map == null || init == null) {
            return null;
        }

        final V value = map.get(key);
        if (value == null) {
            return putIfAbsent(map, key, init.get());
        }
        return value;
    }

    
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. 
Params:
map – the map to be modified
key – the key of the value to be added
init – the ConcurrentInitializer for creating the value
Type parameters:
<K> – the type of the keys of the map
<V> – the type of the values of the map
Throws:
ConcurrentRuntimeException – if the initializer throws an exception
Returns:
the value stored in the map after this operation; this may or may not be the object created by the ConcurrentInitializer/**
     * Checks if a concurrent map contains a key and creates a corresponding
     * value if not, suppressing checked exceptions. This method calls
     * {@code createIfAbsent()}. If a {@link ConcurrentException} is thrown, it
     * is caught and re-thrown as a {@link ConcurrentRuntimeException}.
     *
     * @param <K> the type of the keys of the map
     * @param <V> the type of the values of the map
     * @param map the map to be modified
     * @param key the key of the value to be added
     * @param init the {@link ConcurrentInitializer} for creating the value
     * @return the value stored in the map after this operation; this may or may
     * not be the object created by the {@link ConcurrentInitializer}
     * @throws ConcurrentRuntimeException if the initializer throws an exception
     */
    public static <K, V> V createIfAbsentUnchecked(final ConcurrentMap<K, V> map,
            final K key, final ConcurrentInitializer<V> init) {
        try {
            return createIfAbsent(map, key, init);
        } catch (final ConcurrentException cex) {
            throw new ConcurrentRuntimeException(cex.getCause());
        }
    }

    //-----------------------------------------------------------------------
    

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.

Params:
value –  the constant value to return, may be null
Type parameters:
<T> – the type of the value used by this Future object
Returns:
an instance of Future that will return the value, never null/**
     * <p>
     * Gets an implementation of <code>Future</code> that is immediately done
     * and returns the specified constant value.
     * </p>
     * <p>
     * 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.
     * </p>
     *
     * @param <T> the type of the value used by this {@code Future} object
     * @param value  the constant value to return, may be null
     * @return an instance of Future that will return the value, never null
     */
    public static <T> Future<T> constantFuture(final T value) {
        return new ConstantFuture<>(value);
    }

    
A specialized Future implementation which wraps a constant value. 
Type parameters:
<T> – the type of the value wrapped by this class/**
     * A specialized {@code Future} implementation which wraps a constant value.
     * @param <T> the type of the value wrapped by this class
     */
    static final class ConstantFuture<T> implements Future<T> {
        
The constant value. /** The constant value. */
        private final T value;

        
Creates a new instance of ConstantFuture and initializes it with the constant value. 
Params:
value – the value (may be null)/**
         * Creates a new instance of {@code ConstantFuture} and initializes it
         * with the constant value.
         *
         * @param value the value (may be <b>null</b>)
         */
        ConstantFuture(final T value) {
            this.value = value;
        }

        
{@inheritDoc} This implementation always returns true because the constant object managed by this Future implementation is always available. /**
         * {@inheritDoc} This implementation always returns <b>true</b> because
         * the constant object managed by this {@code Future} implementation is
         * always available.
         */
        @Override
        public boolean isDone() {
            return true;
        }

        
{@inheritDoc} This implementation just returns the constant value.
/**
         * {@inheritDoc} This implementation just returns the constant value.
         */
        @Override
        public T get() {
            return value;
        }

        
{@inheritDoc} This implementation just returns the constant value; it
does not block, therefore the timeout has no meaning.
/**
         * {@inheritDoc} This implementation just returns the constant value; it
         * does not block, therefore the timeout has no meaning.
         */
        @Override
        public T get(final long timeout, final TimeUnit unit) {
            return value;
        }

        
{@inheritDoc} This implementation always returns false; there
is no background process which could be cancelled.
/**
         * {@inheritDoc} This implementation always returns <b>false</b>; there
         * is no background process which could be cancelled.
         */
        @Override
        public boolean isCancelled() {
            return false;
        }

        
{@inheritDoc} The cancel operation is not supported. This
implementation always returns false.
/**
         * {@inheritDoc} The cancel operation is not supported. This
         * implementation always returns <b>false</b>.
         */
        @Override
        public boolean cancel(final boolean mayInterruptIfRunning) {
            return false;
        }
    }

}