393 lines
15 KiB
Java
393 lines
15 KiB
Java
/*
|
|
* 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
|
|
*/
|
|
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} 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<>(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;
|
|
}
|
|
}
|
|
|
|
}
|