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