Java example source code file (ConcurrentUtils.java)

This example Java source code file (ConcurrentUtils.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

concurrentexception, concurrentinitializer, concurrentmap, concurrentutils, constantfuture, error, executionexception, override, runtimeexception, threading, threads

The ConcurrentUtils.java Java example source code

/*
 * 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 null or the cause is
     * <b>null, this method returns null.
     * <li>If the cause is a runtime exception, it is directly thrown.
     * <li>If the cause is an error, it is directly thrown, too.
     * <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 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-safe: if the argument is null, result is also
     * <b>null.
     *
     * @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 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 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-safe: It accepts a null map as input
     * without throwing an exception. In this case the return value is
     * <b>null, 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 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; in this
     * case this method simply returns <b>null.
     *
     * @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 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 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 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 {
        /** 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)
         */
        ConstantFuture(final T value) {
            this.value = value;
        }

        /**
         * {@inheritDoc} This implementation always returns <b>true 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; 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.
         */
        @Override
        public boolean cancel(final boolean mayInterruptIfRunning) {
            return false;
        }
    }

}