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