/*

  * 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;

 /**

  * <p>

  * An utility class providing functionality related to the {@code

  * java.util.concurrent} package.

  * </p>

  *

  * @since 3.0

  * @version $Id: ConcurrentUtils.java 1436770 2013-01-22 07:09:45Z ggregory $

  */

 public class ConcurrentUtils {

     /**

      * Private constructor so that no instances can be created. This class

      * contains only static utility methods.

      */

     private ConcurrentUtils() {

     }

     /**

      * 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 {@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 {@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 {@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 {@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) {

         if (ex != null && !(ex instanceof RuntimeException)

                 && !(ex instanceof Error)) {

             return ex;

         } else {

             throw new IllegalArgumentException("Not a checked exception: " + ex);

         }

     }

     /**

      * 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 {@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 {@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());

         }

     }

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

     /**

      * <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:

      *

      * <pre>

      * if (!map.containsKey(key)) {

      *     map.put(key, value);

      *     return value;

      * } else {

      *     return map.get(key);

      * }

      * </pre>

      *

      * 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 {@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

      * {@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());

         }

     }

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

     /**

      * <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<T>(value);

     }

     /**

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

         private final T value;

         /**

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

          */

         @Override

         public T get() {

             return value;

         }

         /**

          * {@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 <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 <b>false</b>.

          */

         @Override

         public boolean cancel(final boolean mayInterruptIfRunning) {

             return false;

         }

     }

 }