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</code> 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<T>(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}