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}