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   */
34  public class ConcurrentUtils {
35  
36      /**
37       * Private constructor so that no instances can be created. This class
38       * contains only static utility methods.
39       */
40      private ConcurrentUtils() {
41      }
42  
43      /**
44       * Inspects the cause of the specified {@code ExecutionException} and
45       * creates a {@code ConcurrentException} with the checked cause if
46       * necessary. This method performs the following checks on the cause of the
47       * passed in exception:
48       * <ul>
49       * <li>If the passed in exception is <b>null</b> or the cause is
50       * <b>null</b>, this method returns <b>null</b>.</li>
51       * <li>If the cause is a runtime exception, it is directly thrown.</li>
52       * <li>If the cause is an error, it is directly thrown, too.</li>
53       * <li>In any other case the cause is a checked exception. The method then
54       * creates a {@link ConcurrentException}, initializes it with the cause, and
55       * returns it.</li>
56       * </ul>
57       *
58       * @param ex the exception to be processed
59       * @return a {@code ConcurrentException} with the checked cause
60       */
61      public static ConcurrentException extractCause(final ExecutionException ex) {
62          if (ex == null || ex.getCause() == null) {
63              return null;
64          }
65  
66          throwCause(ex);
67          return new ConcurrentException(ex.getMessage(), ex.getCause());
68      }
69  
70      /**
71       * Inspects the cause of the specified {@code ExecutionException} and
72       * creates a {@code ConcurrentRuntimeException} with the checked cause if
73       * necessary. This method works exactly like
74       * {@link #extractCause(ExecutionException)}. The only difference is that
75       * the cause of the specified {@code ExecutionException} is extracted as a
76       * runtime exception. This is an alternative for client code that does not
77       * want to deal with checked exceptions.
78       *
79       * @param ex the exception to be processed
80       * @return a {@code ConcurrentRuntimeException} with the checked cause
81       */
82      public static ConcurrentRuntimeException extractCauseUnchecked(
83              final ExecutionException ex) {
84          if (ex == null || ex.getCause() == null) {
85              return null;
86          }
87  
88          throwCause(ex);
89          return new ConcurrentRuntimeException(ex.getMessage(), ex.getCause());
90      }
91  
92      /**
93       * Handles the specified {@code ExecutionException}. This method calls
94       * {@link #extractCause(ExecutionException)} for obtaining the cause of the
95       * exception - which might already cause an unchecked exception or an error
96       * being thrown. If the cause is a checked exception however, it is wrapped
97       * in a {@code ConcurrentException}, which is thrown. If the passed in
98       * exception is <b>null</b> or has no cause, the method simply returns
99       * 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 }