    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.lang3.concurrent;
    018
    019import java.util.concurrent.ConcurrentMap;
    020import java.util.concurrent.ExecutionException;
    021import java.util.concurrent.Future;
    022import java.util.concurrent.TimeUnit;
    023
    024import org.apache.commons.lang3.Validate;
    025import org.apache.commons.lang3.exception.ExceptionUtils;
    026
    027/**
    028 * An utility class providing functionality related to the {@code
    029 * java.util.concurrent} package.
    030 *
    031 * @since 3.0
    032 */
    033public class ConcurrentUtils {
    034
    035    /**
    036     * Private constructor so that no instances can be created. This class
    037     * contains only static utility methods.
    038     */
    039    private ConcurrentUtils() {
    040    }
    041
    042    /**
    043     * Inspects the cause of the specified {@link ExecutionException} and
    044     * creates a {@link ConcurrentException} with the checked cause if
    045     * necessary. This method performs the following checks on the cause of the
    046     * passed in exception:
    047     * <ul>
    048     * <li>If the passed in exception is <b>null</b> or the cause is
    049     * <b>null</b>, this method returns <b>null</b>.</li>
    050     * <li>If the cause is a runtime exception, it is directly thrown.</li>
    051     * <li>If the cause is an error, it is directly thrown, too.</li>
    052     * <li>In any other case the cause is a checked exception. The method then
    053     * creates a {@link ConcurrentException}, initializes it with the cause, and
    054     * returns it.</li>
    055     * </ul>
    056     *
    057     * @param ex the exception to be processed
    058     * @return a {@link ConcurrentException} with the checked cause
    059     */
    060    public static ConcurrentException extractCause(final ExecutionException ex) {
    061        if (ex == null || ex.getCause() == null) {
    062            return null;
    063        }
    064        ExceptionUtils.throwUnchecked(ex.getCause());
    065        return new ConcurrentException(ex.getMessage(), ex.getCause());
    066    }
    067
    068    /**
    069     * Inspects the cause of the specified {@link ExecutionException} and
    070     * creates a {@link ConcurrentRuntimeException} with the checked cause if
    071     * necessary. This method works exactly like
    072     * {@link #extractCause(ExecutionException)}. The only difference is that
    073     * the cause of the specified {@link ExecutionException} is extracted as a
    074     * runtime exception. This is an alternative for client code that does not
    075     * want to deal with checked exceptions.
    076     *
    077     * @param ex the exception to be processed
    078     * @return a {@link ConcurrentRuntimeException} with the checked cause
    079     */
    080    public static ConcurrentRuntimeException extractCauseUnchecked(
    081            final ExecutionException ex) {
    082        if (ex == null || ex.getCause() == null) {
    083            return null;
    084        }
    085
    086        ExceptionUtils.throwUnchecked(ex.getCause());
    087        return new ConcurrentRuntimeException(ex.getMessage(), ex.getCause());
    088    }
    089
    090    /**
    091     * Handles the specified {@link ExecutionException}. This method calls
    092     * {@link #extractCause(ExecutionException)} for obtaining the cause of the
    093     * exception - which might already cause an unchecked exception or an error
    094     * being thrown. If the cause is a checked exception however, it is wrapped
    095     * in a {@link ConcurrentException}, which is thrown. If the passed in
    096     * exception is <b>null</b> or has no cause, the method simply returns
    097     * without throwing an exception.
    098     *
    099     * @param ex the exception to be handled
    100     * @throws ConcurrentException if the cause of the {@code
    101     * ExecutionException} is a checked exception
    102     */
    103    public static void handleCause(final ExecutionException ex)
    104            throws ConcurrentException {
    105        final ConcurrentException cex = extractCause(ex);
    106
    107        if (cex != null) {
    108            throw cex;
    109        }
    110    }
    111
    112    /**
    113     * Handles the specified {@link ExecutionException} and transforms it into a
    114     * runtime exception. This method works exactly like
    115     * {@link #handleCause(ExecutionException)}, but instead of a
    116     * {@link ConcurrentException} it throws a
    117     * {@link ConcurrentRuntimeException}. This is an alternative for client
    118     * code that does not want to deal with checked exceptions.
    119     *
    120     * @param ex the exception to be handled
    121     * @throws ConcurrentRuntimeException if the cause of the {@code
    122     * ExecutionException} is a checked exception; this exception is then
    123     * wrapped in the thrown runtime exception
    124     */
    125    public static void handleCauseUnchecked(final ExecutionException ex) {
    126        final ConcurrentRuntimeException crex = extractCauseUnchecked(ex);
    127
    128        if (crex != null) {
    129            throw crex;
    130        }
    131    }
    132
    133    /**
    134     * Tests whether the specified {@link Throwable} is a checked exception. If
    135     * not, an exception is thrown.
    136     *
    137     * @param ex the {@link Throwable} to check
    138     * @return a flag whether the passed in exception is a checked exception
    139     * @throws IllegalArgumentException if the {@link Throwable} is not a
    140     * checked exception
    141     */
    142    static Throwable checkedException(final Throwable ex) {
    143        Validate.isTrue(ExceptionUtils.isChecked(ex), "Not a checked exception: " + ex);
    144        return ex;
    145    }
    146
    147    /**
    148     * Invokes the specified {@link ConcurrentInitializer} and returns the
    149     * object produced by the initializer. This method just invokes the {@code
    150     * get()} method of the given {@link ConcurrentInitializer}. It is
    151     * <b>null</b>-safe: if the argument is <b>null</b>, result is also
    152     * <b>null</b>.
    153     *
    154     * @param <T> the type of the object produced by the initializer
    155     * @param initializer the {@link ConcurrentInitializer} to be invoked
    156     * @return the object managed by the {@link ConcurrentInitializer}
    157     * @throws ConcurrentException if the {@link ConcurrentInitializer} throws
    158     * an exception
    159     */
    160    public static <T> T initialize(final ConcurrentInitializer<T> initializer)
    161            throws ConcurrentException {
    162        return initializer != null ? initializer.get() : null;
    163    }
    164
    165    /**
    166     * Invokes the specified {@link ConcurrentInitializer} and transforms
    167     * occurring exceptions to runtime exceptions. This method works like
    168     * {@link #initialize(ConcurrentInitializer)}, but if the {@code
    169     * ConcurrentInitializer} throws a {@link ConcurrentException}, it is
    170     * caught, and the cause is wrapped in a {@link ConcurrentRuntimeException}.
    171     * So client code does not have to deal with checked exceptions.
    172     *
    173     * @param <T> the type of the object produced by the initializer
    174     * @param initializer the {@link ConcurrentInitializer} to be invoked
    175     * @return the object managed by the {@link ConcurrentInitializer}
    176     * @throws ConcurrentRuntimeException if the initializer throws an exception
    177     */
    178    public static <T> T initializeUnchecked(final ConcurrentInitializer<T> initializer) {
    179        try {
    180            return initialize(initializer);
    181        } catch (final ConcurrentException cex) {
    182            throw new ConcurrentRuntimeException(cex.getCause());
    183        }
    184    }
    185
    186    /**
    187     * Puts a value in the specified {@link ConcurrentMap} if the key is not yet
    188     * present. This method works similar to the {@code putIfAbsent()} method of
    189     * the {@link ConcurrentMap} interface, but the value returned is different.
    190     * Basically, this method is equivalent to the following code fragment:
    191     *
    192     * <pre>
    193     * if (!map.containsKey(key)) {
    194     *     map.put(key, value);
    195     *     return value;
    196     * } else {
    197     *     return map.get(key);
    198     * }
    199     * </pre>
    200     *
    201     * <p>
    202     * except that the action is performed atomically. So this method always
    203     * returns the value which is stored in the map.
    204     * </p>
    205     * <p>
    206     * This method is <b>null</b>-safe: It accepts a <b>null</b> map as input
    207     * without throwing an exception. In this case the return value is
    208     * <b>null</b>, too.
    209     * </p>
    210     *
    211     * @param <K> the type of the keys of the map
    212     * @param <V> the type of the values of the map
    213     * @param map the map to be modified
    214     * @param key the key of the value to be added
    215     * @param value the value to be added
    216     * @return the value stored in the map after this operation
    217     */
    218    public static <K, V> V putIfAbsent(final ConcurrentMap<K, V> map, final K key, final V value) {
    219        if (map == null) {
    220            return null;
    221        }
    222
    223        final V result = map.putIfAbsent(key, value);
    224        return result != null ? result : value;
    225    }
    226
    227    /**
    228     * Checks if a concurrent map contains a key and creates a corresponding
    229     * value if not. This method first checks the presence of the key in the
    230     * given map. If it is already contained, its value is returned. Otherwise
    231     * the {@code get()} method of the passed in {@link ConcurrentInitializer}
    232     * is called. With the resulting object
    233     * {@link #putIfAbsent(ConcurrentMap, Object, Object)} is called. This
    234     * handles the case that in the meantime another thread has added the key to
    235     * the map. Both the map and the initializer can be <b>null</b>; in this
    236     * case this method simply returns <b>null</b>.
    237     *
    238     * @param <K> the type of the keys of the map
    239     * @param <V> the type of the values of the map
    240     * @param map the map to be modified
    241     * @param key the key of the value to be added
    242     * @param init the {@link ConcurrentInitializer} for creating the value
    243     * @return the value stored in the map after this operation; this may or may
    244     * not be the object created by the {@link ConcurrentInitializer}
    245     * @throws ConcurrentException if the initializer throws an exception
    246     */
    247    public static <K, V> V createIfAbsent(final ConcurrentMap<K, V> map, final K key,
    248            final ConcurrentInitializer<V> init) throws ConcurrentException {
    249        if (map == null || init == null) {
    250            return null;
    251        }
    252
    253        final V value = map.get(key);
    254        if (value == null) {
    255            return putIfAbsent(map, key, init.get());
    256        }
    257        return value;
    258    }
    259
    260    /**
    261     * Checks if a concurrent map contains a key and creates a corresponding
    262     * value if not, suppressing checked exceptions. This method calls
    263     * {@code createIfAbsent()}. If a {@link ConcurrentException} is thrown, it
    264     * is caught and re-thrown as a {@link ConcurrentRuntimeException}.
    265     *
    266     * @param <K> the type of the keys of the map
    267     * @param <V> the type of the values of the map
    268     * @param map the map to be modified
    269     * @param key the key of the value to be added
    270     * @param init the {@link ConcurrentInitializer} for creating the value
    271     * @return the value stored in the map after this operation; this may or may
    272     * not be the object created by the {@link ConcurrentInitializer}
    273     * @throws ConcurrentRuntimeException if the initializer throws an exception
    274     */
    275    public static <K, V> V createIfAbsentUnchecked(final ConcurrentMap<K, V> map,
    276            final K key, final ConcurrentInitializer<V> init) {
    277        try {
    278            return createIfAbsent(map, key, init);
    279        } catch (final ConcurrentException cex) {
    280            throw new ConcurrentRuntimeException(cex.getCause());
    281        }
    282    }
    283
    284    /**
    285     * Gets an implementation of {@link Future} that is immediately done
    286     * and returns the specified constant value.
    287     *
    288     * <p>
    289     * This can be useful to return a simple constant immediately from the
    290     * concurrent processing, perhaps as part of avoiding nulls.
    291     * A constant future can also be useful in testing.
    292     * </p>
    293     *
    294     * @param <T> the type of the value used by this {@link Future} object
    295     * @param value  the constant value to return, may be null
    296     * @return an instance of Future that will return the value, never null
    297     */
    298    public static <T> Future<T> constantFuture(final T value) {
    299        return new ConstantFuture<>(value);
    300    }
    301
    302    /**
    303     * A specialized {@link Future} implementation which wraps a constant value.
    304     * @param <T> the type of the value wrapped by this class
    305     */
    306    static final class ConstantFuture<T> implements Future<T> {
    307        /** The constant value. */
    308        private final T value;
    309
    310        /**
    311         * Creates a new instance of {@link ConstantFuture} and initializes it
    312         * with the constant value.
    313         *
    314         * @param value the value (may be <b>null</b>)
    315         */
    316        ConstantFuture(final T value) {
    317            this.value = value;
    318        }
    319
    320        /**
    321         * {@inheritDoc} This implementation always returns <b>true</b> because
    322         * the constant object managed by this {@link Future} implementation is
    323         * always available.
    324         */
    325        @Override
    326        public boolean isDone() {
    327            return true;
    328        }
    329
    330        /**
    331         * {@inheritDoc} This implementation just returns the constant value.
    332         */
    333        @Override
    334        public T get() {
    335            return value;
    336        }
    337
    338        /**
    339         * {@inheritDoc} This implementation just returns the constant value; it
    340         * does not block, therefore the timeout has no meaning.
    341         */
    342        @Override
    343        public T get(final long timeout, final TimeUnit unit) {
    344            return value;
    345        }
    346
    347        /**
    348         * {@inheritDoc} This implementation always returns <b>false</b>; there
    349         * is no background process which could be cancelled.
    350         */
    351        @Override
    352        public boolean isCancelled() {
    353            return false;
    354        }
    355
    356        /**
    357         * {@inheritDoc} The cancel operation is not supported. This
    358         * implementation always returns <b>false</b>.
    359         */
    360        @Override
    361        public boolean cancel(final boolean mayInterruptIfRunning) {
    362            return false;
    363        }
    364    }
    365
    366}