View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.lang3.concurrent;
18  
19  import java.util.concurrent.ConcurrentMap;
20  import java.util.concurrent.ExecutionException;
21  import java.util.concurrent.Future;
22  import java.util.concurrent.TimeUnit;
23  
24  import org.apache.commons.lang3.Validate;
25  
26  /**
27   * <p>
28   * An utility class providing functionality related to the {@code
29   * java.util.concurrent} package.
30   * </p>
31   *
32   * @since 3.0
33   * @version $Id: ConcurrentUtils.java 1593668 2014-05-10 05:58:17Z djones $
34   */
35  public class ConcurrentUtils {
36  
37      /**
38       * Private constructor so that no instances can be created. This class
39       * contains only static utility methods.
40       */
41      private ConcurrentUtils() {
42      }
43  
44      /**
45       * Inspects the cause of the specified {@code ExecutionException} and
46       * creates a {@code ConcurrentException} with the checked cause if
47       * necessary. This method performs the following checks on the cause of the
48       * passed in exception:
49       * <ul>
50       * <li>If the passed in exception is <b>null</b> or the cause is
51       * <b>null</b>, this method returns <b>null</b>.</li>
52       * <li>If the cause is a runtime exception, it is directly thrown.</li>
53       * <li>If the cause is an error, it is directly thrown, too.</li>
54       * <li>In any other case the cause is a checked exception. The method then
55       * creates a {@link ConcurrentException}, initializes it with the cause, and
56       * returns it.</li>
57       * </ul>
58       *
59       * @param ex the exception to be processed
60       * @return a {@code ConcurrentException} with the checked cause
61       */
62      public static ConcurrentException extractCause(final ExecutionException ex) {
63          if (ex == null || ex.getCause() == null) {
64              return null;
65          }
66  
67          throwCause(ex);
68          return new ConcurrentException(ex.getMessage(), ex.getCause());
69      }
70  
71      /**
72       * Inspects the cause of the specified {@code ExecutionException} and
73       * creates a {@code ConcurrentRuntimeException} with the checked cause if
74       * necessary. This method works exactly like
75       * {@link #extractCause(ExecutionException)}. The only difference is that
76       * the cause of the specified {@code ExecutionException} is extracted as a
77       * runtime exception. This is an alternative for client code that does not
78       * want to deal with checked exceptions.
79       *
80       * @param ex the exception to be processed
81       * @return a {@code ConcurrentRuntimeException} with the checked cause
82       */
83      public static ConcurrentRuntimeException extractCauseUnchecked(
84              final ExecutionException ex) {
85          if (ex == null || ex.getCause() == null) {
86              return null;
87          }
88  
89          throwCause(ex);
90          return new ConcurrentRuntimeException(ex.getMessage(), ex.getCause());
91      }
92  
93      /**
94       * Handles the specified {@code ExecutionException}. This method calls
95       * {@link #extractCause(ExecutionException)} for obtaining the cause of the
96       * exception - which might already cause an unchecked exception or an error
97       * being thrown. If the cause is a checked exception however, it is wrapped
98       * in a {@code ConcurrentException}, which is thrown. If the passed in
99       * exception is <b>null</b> or has no cause, the method simply returns
100      * without throwing an exception.
101      *
102      * @param ex the exception to be handled
103      * @throws ConcurrentException if the cause of the {@code
104      * ExecutionException} is a checked exception
105      */
106     public static void handleCause(final ExecutionException ex)
107             throws ConcurrentException {
108         final ConcurrentException cex = extractCause(ex);
109 
110         if (cex != null) {
111             throw cex;
112         }
113     }
114 
115     /**
116      * Handles the specified {@code ExecutionException} and transforms it into a
117      * runtime exception. This method works exactly like
118      * {@link #handleCause(ExecutionException)}, but instead of a
119      * {@link ConcurrentException} it throws a
120      * {@link ConcurrentRuntimeException}. This is an alternative for client
121      * code that does not want to deal with checked exceptions.
122      *
123      * @param ex the exception to be handled
124      * @throws ConcurrentRuntimeException if the cause of the {@code
125      * ExecutionException} is a checked exception; this exception is then
126      * wrapped in the thrown runtime exception
127      */
128     public static void handleCauseUnchecked(final ExecutionException ex) {
129         final ConcurrentRuntimeException crex = extractCauseUnchecked(ex);
130 
131         if (crex != null) {
132             throw crex;
133         }
134     }
135 
136     /**
137      * Tests whether the specified {@code Throwable} is a checked exception. If
138      * not, an exception is thrown.
139      *
140      * @param ex the {@code Throwable} to check
141      * @return a flag whether the passed in exception is a checked exception
142      * @throws IllegalArgumentException if the {@code Throwable} is not a
143      * checked exception
144      */
145     static Throwable checkedException(final Throwable ex) {
146         Validate.isTrue(ex != null && !(ex instanceof RuntimeException)
147                 && !(ex instanceof Error), "Not a checked exception: " + ex);
148         
149         return ex;
150     }
151 
152     /**
153      * Tests whether the cause of the specified {@code ExecutionException}
154      * should be thrown and does it if necessary.
155      *
156      * @param ex the exception in question
157      */
158     private static void throwCause(final ExecutionException ex) {
159         if (ex.getCause() instanceof RuntimeException) {
160             throw (RuntimeException) ex.getCause();
161         }
162 
163         if (ex.getCause() instanceof Error) {
164             throw (Error) ex.getCause();
165         }
166     }
167 
168     //-----------------------------------------------------------------------
169     /**
170      * Invokes the specified {@code ConcurrentInitializer} and returns the
171      * object produced by the initializer. This method just invokes the {@code
172      * get()} method of the given {@code ConcurrentInitializer}. It is
173      * <b>null</b>-safe: if the argument is <b>null</b>, result is also
174      * <b>null</b>.
175      *
176      * @param <T> the type of the object produced by the initializer
177      * @param initializer the {@code ConcurrentInitializer} to be invoked
178      * @return the object managed by the {@code ConcurrentInitializer}
179      * @throws ConcurrentException if the {@code ConcurrentInitializer} throws
180      * an exception
181      */
182     public static <T> T initialize(final ConcurrentInitializer<T> initializer)
183             throws ConcurrentException {
184         return initializer != null ? initializer.get() : null;
185     }
186 
187     /**
188      * Invokes the specified {@code ConcurrentInitializer} and transforms
189      * occurring exceptions to runtime exceptions. This method works like
190      * {@link #initialize(ConcurrentInitializer)}, but if the {@code
191      * ConcurrentInitializer} throws a {@link ConcurrentException}, it is
192      * caught, and the cause is wrapped in a {@link ConcurrentRuntimeException}.
193      * So client code does not have to deal with checked exceptions.
194      *
195      * @param <T> the type of the object produced by the initializer
196      * @param initializer the {@code ConcurrentInitializer} to be invoked
197      * @return the object managed by the {@code ConcurrentInitializer}
198      * @throws ConcurrentRuntimeException if the initializer throws an exception
199      */
200     public static <T> T initializeUnchecked(final ConcurrentInitializer<T> initializer) {
201         try {
202             return initialize(initializer);
203         } catch (final ConcurrentException cex) {
204             throw new ConcurrentRuntimeException(cex.getCause());
205         }
206     }
207 
208     //-----------------------------------------------------------------------
209     /**
210      * <p>
211      * Puts a value in the specified {@code ConcurrentMap} if the key is not yet
212      * present. This method works similar to the {@code putIfAbsent()} method of
213      * the {@code ConcurrentMap} interface, but the value returned is different.
214      * Basically, this method is equivalent to the following code fragment:
215      * </p>
216      *
217      * <pre>
218      * if (!map.containsKey(key)) {
219      *     map.put(key, value);
220      *     return value;
221      * } else {
222      *     return map.get(key);
223      * }
224      * </pre>
225      *
226      * <p>
227      * except that the action is performed atomically. So this method always
228      * returns the value which is stored in the map.
229      * </p>
230      * <p>
231      * This method is <b>null</b>-safe: It accepts a <b>null</b> map as input
232      * without throwing an exception. In this case the return value is
233      * <b>null</b>, too.
234      * </p>
235      *
236      * @param <K> the type of the keys of the map
237      * @param <V> the type of the values of the map
238      * @param map the map to be modified
239      * @param key the key of the value to be added
240      * @param value the value to be added
241      * @return the value stored in the map after this operation
242      */
243     public static <K, V> V putIfAbsent(final ConcurrentMap<K, V> map, final K key, final V value) {
244         if (map == null) {
245             return null;
246         }
247 
248         final V result = map.putIfAbsent(key, value);
249         return result != null ? result : value;
250     }
251 
252     /**
253      * Checks if a concurrent map contains a key and creates a corresponding
254      * value if not. This method first checks the presence of the key in the
255      * given map. If it is already contained, its value is returned. Otherwise
256      * the {@code get()} method of the passed in {@link ConcurrentInitializer}
257      * is called. With the resulting object
258      * {@link #putIfAbsent(ConcurrentMap, Object, Object)} is called. This
259      * handles the case that in the meantime another thread has added the key to
260      * the map. Both the map and the initializer can be <b>null</b>; in this
261      * case this method simply returns <b>null</b>.
262      *
263      * @param <K> the type of the keys of the map
264      * @param <V> the type of the values of the map
265      * @param map the map to be modified
266      * @param key the key of the value to be added
267      * @param init the {@link ConcurrentInitializer} for creating the value
268      * @return the value stored in the map after this operation; this may or may
269      * not be the object created by the {@link ConcurrentInitializer}
270      * @throws ConcurrentException if the initializer throws an exception
271      */
272     public static <K, V> V createIfAbsent(final ConcurrentMap<K, V> map, final K key,
273             final ConcurrentInitializer<V> init) throws ConcurrentException {
274         if (map == null || init == null) {
275             return null;
276         }
277 
278         final V value = map.get(key);
279         if (value == null) {
280             return putIfAbsent(map, key, init.get());
281         }
282         return value;
283     }
284 
285     /**
286      * Checks if a concurrent map contains a key and creates a corresponding
287      * value if not, suppressing checked exceptions. This method calls
288      * {@code createIfAbsent()}. If a {@link ConcurrentException} is thrown, it
289      * is caught and re-thrown as a {@link ConcurrentRuntimeException}.
290      *
291      * @param <K> the type of the keys of the map
292      * @param <V> the type of the values of the map
293      * @param map the map to be modified
294      * @param key the key of the value to be added
295      * @param init the {@link ConcurrentInitializer} for creating the value
296      * @return the value stored in the map after this operation; this may or may
297      * not be the object created by the {@link ConcurrentInitializer}
298      * @throws ConcurrentRuntimeException if the initializer throws an exception
299      */
300     public static <K, V> V createIfAbsentUnchecked(final ConcurrentMap<K, V> map,
301             final K key, final ConcurrentInitializer<V> init) {
302         try {
303             return createIfAbsent(map, key, init);
304         } catch (final ConcurrentException cex) {
305             throw new ConcurrentRuntimeException(cex.getCause());
306         }
307     }
308 
309     //-----------------------------------------------------------------------
310     /**
311      * <p>
312      * Gets an implementation of <code>Future</code> that is immediately done
313      * and returns the specified constant value.
314      * </p>
315      * <p>
316      * This can be useful to return a simple constant immediately from the
317      * concurrent processing, perhaps as part of avoiding nulls.
318      * A constant future can also be useful in testing.
319      * </p>
320      *
321      * @param <T> the type of the value used by this {@code Future} object
322      * @param value  the constant value to return, may be null
323      * @return an instance of Future that will return the value, never null
324      */
325     public static <T> Future<T> constantFuture(final T value) {
326         return new ConstantFuture<T>(value);
327     }
328 
329     /**
330      * A specialized {@code Future} implementation which wraps a constant value.
331      * @param <T> the type of the value wrapped by this class
332      */
333     static final class ConstantFuture<T> implements Future<T> {
334         /** The constant value. */
335         private final T value;
336 
337         /**
338          * Creates a new instance of {@code ConstantFuture} and initializes it
339          * with the constant value.
340          *
341          * @param value the value (may be <b>null</b>)
342          */
343         ConstantFuture(final T value) {
344             this.value = value;
345         }
346 
347         /**
348          * {@inheritDoc} This implementation always returns <b>true</b> because
349          * the constant object managed by this {@code Future} implementation is
350          * always available.
351          */
352         @Override
353         public boolean isDone() {
354             return true;
355         }
356 
357         /**
358          * {@inheritDoc} This implementation just returns the constant value.
359          */
360         @Override
361         public T get() {
362             return value;
363         }
364 
365         /**
366          * {@inheritDoc} This implementation just returns the constant value; it
367          * does not block, therefore the timeout has no meaning.
368          */
369         @Override
370         public T get(final long timeout, final TimeUnit unit) {
371             return value;
372         }
373 
374         /**
375          * {@inheritDoc} This implementation always returns <b>false</b>; there
376          * is no background process which could be cancelled.
377          */
378         @Override
379         public boolean isCancelled() {
380             return false;
381         }
382 
383         /**
384          * {@inheritDoc} The cancel operation is not supported. This
385          * implementation always returns <b>false</b>.
386          */
387         @Override
388         public boolean cancel(final boolean mayInterruptIfRunning) {
389             return false;
390         }
391     }
392 
393 }