Java tutorial
/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.lang3.concurrent; import java.util.concurrent.ConcurrentMap; import java.util.concurrent.ExecutionException; import java.util.concurrent.Future; import java.util.concurrent.TimeUnit; import org.apache.commons.lang3.Validate; /** * <p> * An utility class providing functionality related to the {@code * java.util.concurrent} package. * </p> * * @since 3.0 * @version $Id$ */ public class ConcurrentUtils { /** * Private constructor so that no instances can be created. This class * contains only static utility methods. */ private ConcurrentUtils() { } /** * Inspects the cause of the specified {@code ExecutionException} and * creates a {@code ConcurrentException} with the checked cause if * necessary. This method performs the following checks on the cause of the * passed in exception: * <ul> * <li>If the passed in exception is <b>null</b> or the cause is * <b>null</b>, this method returns <b>null</b>.</li> * <li>If the cause is a runtime exception, it is directly thrown.</li> * <li>If the cause is an error, it is directly thrown, too.</li> * <li>In any other case the cause is a checked exception. The method then * creates a {@link ConcurrentException}, initializes it with the cause, and * returns it.</li> * </ul> * * @param ex the exception to be processed * @return a {@code ConcurrentException} with the checked cause */ public static ConcurrentException extractCause(final ExecutionException ex) { if (ex == null || ex.getCause() == null) { return null; } throwCause(ex); return new ConcurrentException(ex.getMessage(), ex.getCause()); } /** * Inspects the cause of the specified {@code ExecutionException} and * creates a {@code ConcurrentRuntimeException} with the checked cause if * necessary. This method works exactly like * {@link #extractCause(ExecutionException)}. The only difference is that * the cause of the specified {@code ExecutionException} is extracted as a * runtime exception. This is an alternative for client code that does not * want to deal with checked exceptions. * * @param ex the exception to be processed * @return a {@code ConcurrentRuntimeException} with the checked cause */ public static ConcurrentRuntimeException extractCauseUnchecked(final ExecutionException ex) { if (ex == null || ex.getCause() == null) { return null; } throwCause(ex); return new ConcurrentRuntimeException(ex.getMessage(), ex.getCause()); } /** * Handles the specified {@code ExecutionException}. This method calls * {@link #extractCause(ExecutionException)} for obtaining the cause of the * exception - which might already cause an unchecked exception or an error * being thrown. If the cause is a checked exception however, it is wrapped * in a {@code ConcurrentException}, which is thrown. If the passed in * exception is <b>null</b> or has no cause, the method simply returns * without throwing an exception. * * @param ex the exception to be handled * @throws ConcurrentException if the cause of the {@code * ExecutionException} is a checked exception */ public static void handleCause(final ExecutionException ex) throws ConcurrentException { final ConcurrentException cex = extractCause(ex); if (cex != null) { throw cex; } } /** * Handles the specified {@code ExecutionException} and transforms it into a * runtime exception. This method works exactly like * {@link #handleCause(ExecutionException)}, but instead of a * {@link ConcurrentException} it throws a * {@link ConcurrentRuntimeException}. This is an alternative for client * code that does not want to deal with checked exceptions. * * @param ex the exception to be handled * @throws ConcurrentRuntimeException if the cause of the {@code * ExecutionException} is a checked exception; this exception is then * wrapped in the thrown runtime exception */ public static void handleCauseUnchecked(final ExecutionException ex) { final ConcurrentRuntimeException crex = extractCauseUnchecked(ex); if (crex != null) { throw crex; } } /** * Tests whether the specified {@code Throwable} is a checked exception. If * not, an exception is thrown. * * @param ex the {@code Throwable} to check * @return a flag whether the passed in exception is a checked exception * @throws IllegalArgumentException if the {@code Throwable} is not a * checked exception */ static Throwable checkedException(final Throwable ex) { Validate.isTrue(ex != null && !(ex instanceof RuntimeException) && !(ex instanceof Error), "Not a checked exception: " + ex); return ex; } /** * Tests whether the cause of the specified {@code ExecutionException} * should be thrown and does it if necessary. * * @param ex the exception in question */ private static void throwCause(final ExecutionException ex) { if (ex.getCause() instanceof RuntimeException) { throw (RuntimeException) ex.getCause(); } if (ex.getCause() instanceof Error) { throw (Error) ex.getCause(); } } //----------------------------------------------------------------------- /** * Invokes the specified {@code ConcurrentInitializer} and returns the * object produced by the initializer. This method just invokes the {@code * get()} method of the given {@code ConcurrentInitializer}. It is * <b>null</b>-safe: if the argument is <b>null</b>, result is also * <b>null</b>. * * @param <T> the type of the object produced by the initializer * @param initializer the {@code ConcurrentInitializer} to be invoked * @return the object managed by the {@code ConcurrentInitializer} * @throws ConcurrentException if the {@code ConcurrentInitializer} throws * an exception */ public static <T> T initialize(final ConcurrentInitializer<T> initializer) throws ConcurrentException { return initializer != null ? initializer.get() : null; } /** * Invokes the specified {@code ConcurrentInitializer} and transforms * occurring exceptions to runtime exceptions. This method works like * {@link #initialize(ConcurrentInitializer)}, but if the {@code * ConcurrentInitializer} throws a {@link ConcurrentException}, it is * caught, and the cause is wrapped in a {@link ConcurrentRuntimeException}. * So client code does not have to deal with checked exceptions. * * @param <T> the type of the object produced by the initializer * @param initializer the {@code ConcurrentInitializer} to be invoked * @return the object managed by the {@code ConcurrentInitializer} * @throws ConcurrentRuntimeException if the initializer throws an exception */ public static <T> T initializeUnchecked(final ConcurrentInitializer<T> initializer) { try { return initialize(initializer); } catch (final ConcurrentException cex) { throw new ConcurrentRuntimeException(cex.getCause()); } } //----------------------------------------------------------------------- /** * <p> * Puts a value in the specified {@code ConcurrentMap} if the key is not yet * present. This method works similar to the {@code putIfAbsent()} method of * the {@code ConcurrentMap} interface, but the value returned is different. * Basically, this method is equivalent to the following code fragment: * </p> * * <pre> * if (!map.containsKey(key)) { * map.put(key, value); * return value; * } else { * return map.get(key); * } * </pre> * * <p> * except that the action is performed atomically. So this method always * returns the value which is stored in the map. * </p> * <p> * This method is <b>null</b>-safe: It accepts a <b>null</b> map as input * without throwing an exception. In this case the return value is * <b>null</b>, too. * </p> * * @param <K> the type of the keys of the map * @param <V> the type of the values of the map * @param map the map to be modified * @param key the key of the value to be added * @param value the value to be added * @return the value stored in the map after this operation */ public static <K, V> V putIfAbsent(final ConcurrentMap<K, V> map, final K key, final V value) { if (map == null) { return null; } final V result = map.putIfAbsent(key, value); return result != null ? result : value; } /** * Checks if a concurrent map contains a key and creates a corresponding * value if not. This method first checks the presence of the key in the * given map. If it is already contained, its value is returned. Otherwise * the {@code get()} method of the passed in {@link ConcurrentInitializer} * is called. With the resulting object * {@link #putIfAbsent(ConcurrentMap, Object, Object)} is called. This * handles the case that in the meantime another thread has added the key to * the map. Both the map and the initializer can be <b>null</b>; in this * case this method simply returns <b>null</b>. * * @param <K> the type of the keys of the map * @param <V> the type of the values of the map * @param map the map to be modified * @param key the key of the value to be added * @param init the {@link ConcurrentInitializer} for creating the value * @return the value stored in the map after this operation; this may or may * not be the object created by the {@link ConcurrentInitializer} * @throws ConcurrentException if the initializer throws an exception */ public static <K, V> V createIfAbsent(final ConcurrentMap<K, V> map, final K key, final ConcurrentInitializer<V> init) throws ConcurrentException { if (map == null || init == null) { return null; } final V value = map.get(key); if (value == null) { return putIfAbsent(map, key, init.get()); } return value; } /** * Checks if a concurrent map contains a key and creates a corresponding * value if not, suppressing checked exceptions. This method calls * {@code createIfAbsent()}. If a {@link ConcurrentException} is thrown, it * is caught and re-thrown as a {@link ConcurrentRuntimeException}. * * @param <K> the type of the keys of the map * @param <V> the type of the values of the map * @param map the map to be modified * @param key the key of the value to be added * @param init the {@link ConcurrentInitializer} for creating the value * @return the value stored in the map after this operation; this may or may * not be the object created by the {@link ConcurrentInitializer} * @throws ConcurrentRuntimeException if the initializer throws an exception */ public static <K, V> V createIfAbsentUnchecked(final ConcurrentMap<K, V> map, final K key, final ConcurrentInitializer<V> init) { try { return createIfAbsent(map, key, init); } catch (final ConcurrentException cex) { throw new ConcurrentRuntimeException(cex.getCause()); } } //----------------------------------------------------------------------- /** * <p> * Gets an implementation of <code>Future</code> that is immediately done * and returns the specified constant value. * </p> * <p> * This can be useful to return a simple constant immediately from the * concurrent processing, perhaps as part of avoiding nulls. * A constant future can also be useful in testing. * </p> * * @param <T> the type of the value used by this {@code Future} object * @param value the constant value to return, may be null * @return an instance of Future that will return the value, never null */ public static <T> Future<T> constantFuture(final T value) { return new ConstantFuture<T>(value); } /** * A specialized {@code Future} implementation which wraps a constant value. * @param <T> the type of the value wrapped by this class */ static final class ConstantFuture<T> implements Future<T> { /** The constant value. */ private final T value; /** * Creates a new instance of {@code ConstantFuture} and initializes it * with the constant value. * * @param value the value (may be <b>null</b>) */ ConstantFuture(final T value) { this.value = value; } /** * {@inheritDoc} This implementation always returns <b>true</b> because * the constant object managed by this {@code Future} implementation is * always available. */ @Override public boolean isDone() { return true; } /** * {@inheritDoc} This implementation just returns the constant value. */ @Override public T get() { return value; } /** * {@inheritDoc} This implementation just returns the constant value; it * does not block, therefore the timeout has no meaning. */ @Override public T get(final long timeout, final TimeUnit unit) { return value; } /** * {@inheritDoc} This implementation always returns <b>false</b>; there * is no background process which could be cancelled. */ @Override public boolean isCancelled() { return false; } /** * {@inheritDoc} The cancel operation is not supported. This * implementation always returns <b>false</b>. */ @Override public boolean cancel(final boolean mayInterruptIfRunning) { return false; } } }