    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 *      https://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.Callable;
    020import java.util.concurrent.CancellationException;
    021import java.util.concurrent.ExecutionException;
    022import java.util.concurrent.ExecutorService;
    023import java.util.concurrent.Executors;
    024import java.util.concurrent.Future;
    025
    026import org.apache.commons.lang3.function.FailableConsumer;
    027import org.apache.commons.lang3.function.FailableSupplier;
    028
    029/**
    030 * A class that allows complex initialization operations in a background task.
    031 *
    032 * <p>
    033 * Applications often have to do some expensive initialization steps when they
    034 * are started, e.g. constructing a connection to a database, reading a
    035 * configuration file, etc. Doing these things in parallel can enhance
    036 * performance as the CPU load can be improved. However, when access to the
    037 * resources initialized in a background thread is actually required,
    038 * synchronization has to be performed to ensure that their initialization is
    039 * complete.
    040 * </p>
    041 * <p>
    042 * This abstract base class provides support for this use case. A concrete
    043 * subclass must implement the {@link #initialize()} method. Here an arbitrary
    044 * initialization can be implemented, and a result object can be returned. With
    045 * this method in place the basic usage of this class is as follows (where
    046 * {@code MyBackgroundInitializer} is a concrete subclass):
    047 * </p>
    048 *
    049 * <pre>
    050 * MyBackgroundInitializer initializer = new MyBackgroundInitializer();
    051 * initializer.start();
    052 * // Now do some other things. Initialization runs in a parallel thread
    053 * ...
    054 * // Wait for the end of initialization and access the result object
    055 * Object result = initializer.get();
    056 * </pre>
    057 *
    058 * <p>
    059 * After the construction of a {@link BackgroundInitializer} object its
    060 * {@link #start()} method has to be called. This starts the background
    061 * processing. The application can now continue to do other things. When it
    062 * needs access to the object produced by the {@link BackgroundInitializer} it
    063 * calls its {@link #get()} method. If initialization is already complete,
    064 * {@link #get()} returns the result object immediately. Otherwise it blocks
    065 * until the result object is fully constructed.
    066 * </p>
    067 * <p>
    068 * {@link BackgroundInitializer} is a thin wrapper around a {@link Future}
    069 * object and uses an {@link ExecutorService} for running the background
    070 * initialization task. It is possible to pass in an {@link ExecutorService} at
    071 * construction time or set one using {@code setExternalExecutor()} before
    072 * {@code start()} was called. Then this object is used to spawn the background
    073 * task. If no {@link ExecutorService} has been provided, {@code
    074 * BackgroundInitializer} creates a temporary {@link ExecutorService} and
    075 * destroys it when initialization is complete.
    076 * </p>
    077 * <p>
    078 * The methods provided by {@link BackgroundInitializer} provide for minimal
    079 * interaction with the wrapped {@link Future} object. It is also possible to
    080 * obtain the {@link Future} object directly. Then the enhanced functionality
    081 * offered by {@link Future} can be used, e.g. to check whether the background
    082 * operation is complete or to cancel the operation.
    083 * </p>
    084 *
    085 * @param <T> the type of the object managed by this initializer class
    086 * @since 3.0
    087 */
    088public class BackgroundInitializer<T> extends AbstractConcurrentInitializer<T, Exception> {
    089
    090    /**
    091     * Builds a new instance.
    092     *
    093     * @param <T> The type of results supplied by this builder.
    094     * @param <I> The type of the initializer managed by this builder.
    095     * @since 3.14.0
    096     */
    097    public static class Builder<I extends BackgroundInitializer<T>, T> extends AbstractBuilder<I, T, Builder<I, T>, Exception> {
    098
    099        /**
    100         * The external executor service for executing tasks. null is a permitted value.
    101         */
    102        private ExecutorService externalExecutor;
    103
    104        /**
    105         * Constructs a new instance.
    106         */
    107        public Builder() {
    108            // empty
    109        }
    110
    111        @SuppressWarnings("unchecked")
    112        @Override
    113        public I get() {
    114            return (I) new BackgroundInitializer(getInitializer(), getCloser(), externalExecutor);
    115        }
    116
    117        /**
    118         * Sets the external executor service for executing tasks. null is a permitted value.
    119         *
    120         * @see org.apache.commons.lang3.concurrent.BackgroundInitializer#setExternalExecutor(ExecutorService)
    121         * @param externalExecutor the {@link ExecutorService} to be used.
    122         * @return {@code this} instance.
    123         */
    124        public Builder<I, T> setExternalExecutor(final ExecutorService externalExecutor) {
    125            this.externalExecutor = externalExecutor;
    126            return asThis();
    127        }
    128
    129    }
    130
    131    private final class InitializationTask implements Callable<T> {
    132        /** Stores the executor service to be destroyed at the end. */
    133        private final ExecutorService execFinally;
    134
    135        /**
    136         * Creates a new instance of {@link InitializationTask} and initializes
    137         * it with the {@link ExecutorService} to be destroyed at the end.
    138         *
    139         * @param exec the {@link ExecutorService}
    140         */
    141        InitializationTask(final ExecutorService exec) {
    142            execFinally = exec;
    143        }
    144
    145        /**
    146         * Initiates initialization and returns the result.
    147         *
    148         * @return the result object
    149         * @throws Exception if an error occurs
    150         */
    151        @Override
    152        public T call() throws Exception {
    153            try {
    154                return initialize();
    155            } finally {
    156                if (execFinally != null) {
    157                    execFinally.shutdown();
    158                }
    159            }
    160        }
    161    }
    162
    163    /**
    164     * Creates a new builder.
    165     *
    166     * @param <T> the type of object to build.
    167     * @return a new builder.
    168     * @since 3.14.0
    169     */
    170    public static <T> Builder<BackgroundInitializer<T>, T> builder() {
    171        return new Builder<>();
    172    }
    173
    174    /** The external executor service for executing tasks. */
    175    private ExecutorService externalExecutor; // @GuardedBy("this")
    176
    177    /** A reference to the executor service that is actually used. */
    178    private ExecutorService executor; // @GuardedBy("this")
    179
    180    /** Stores the handle to the background task. */
    181    private Future<T> future;  // @GuardedBy("this")
    182
    183    /**
    184     * Creates a new instance of {@link BackgroundInitializer}. No external
    185     * {@link ExecutorService} is used.
    186     */
    187    protected BackgroundInitializer() {
    188        this(null);
    189    }
    190
    191    /**
    192     * Creates a new instance of {@link BackgroundInitializer} and initializes
    193     * it with the given {@link ExecutorService}. If the {@link ExecutorService}
    194     * is not null, the background task for initializing this object will be
    195     * scheduled at this service. Otherwise a new temporary {@code
    196     * ExecutorService} is created.
    197     *
    198     * @param exec an external {@link ExecutorService} to be used for task.
    199     * execution
    200     */
    201    protected BackgroundInitializer(final ExecutorService exec) {
    202        setExternalExecutor(exec);
    203    }
    204
    205    /**
    206     * Constructs a new instance.
    207     *
    208     * @param initializer the initializer supplier called by {@link #initialize()}.
    209     * @param closer the closer consumer called by {@link #close()}.
    210     * @param exec the {@link ExecutorService} to be used @see #setExternalExecutor(ExecutorService)
    211     */
    212    private BackgroundInitializer(final FailableSupplier<T, ConcurrentException> initializer, final FailableConsumer<T, ConcurrentException> closer, final ExecutorService exec) {
    213        super(initializer, closer);
    214        setExternalExecutor(exec);
    215    }
    216
    217    /**
    218     * Creates the {@link ExecutorService} to be used. This method is called if
    219     * no {@link ExecutorService} was provided at construction time.
    220     *
    221     * @return the {@link ExecutorService} to be used.
    222     */
    223    private ExecutorService createExecutor() {
    224        return Executors.newFixedThreadPool(getTaskCount());
    225    }
    226
    227    /**
    228     * Creates a task for the background initialization. The {@link Callable}
    229     * object returned by this method is passed to the {@link ExecutorService}.
    230     * This implementation returns a task that invokes the {@link #initialize()}
    231     * method. If a temporary {@link ExecutorService} is used, it is destroyed
    232     * at the end of the task.
    233     *
    234     * @param execDestroy the {@link ExecutorService} to be destroyed by the
    235     * task.
    236     * @return a task for the background initialization.
    237     */
    238    private Callable<T> createTask(final ExecutorService execDestroy) {
    239        return new InitializationTask(execDestroy);
    240    }
    241
    242    /**
    243     * Gets the result of the background initialization. This method blocks
    244     * until initialization is complete. If the background processing caused a
    245     * runtime exception, it is directly thrown by this method. Checked
    246     * exceptions, including {@link InterruptedException} are wrapped in a
    247     * {@link ConcurrentException}. Calling this method before {@link #start()}
    248     * was called causes an {@link IllegalStateException} exception to be
    249     * thrown.
    250     *
    251     * @return the object produced by this initializer.
    252     * @throws ConcurrentException if a checked exception occurred during
    253     * background processing.
    254     * @throws IllegalStateException if {@link #start()} has not been called.
    255     */
    256    @Override
    257    public T get() throws ConcurrentException {
    258        try {
    259            return getFuture().get();
    260        } catch (final ExecutionException execex) {
    261            ConcurrentUtils.handleCause(execex);
    262            return null; // should not be reached
    263        } catch (final InterruptedException iex) {
    264            // reset interrupted state
    265            Thread.currentThread().interrupt();
    266            throw new ConcurrentException(iex);
    267        }
    268    }
    269
    270    /**
    271     * Gets the {@link ExecutorService} that is actually used for executing
    272     * the background task. This method can be called after {@link #start()}
    273     * (before {@code start()} it returns <strong>null</strong>). If an external executor
    274     * was set, this is also the active executor. Otherwise this method returns
    275     * the temporary executor that was created by this object.
    276     *
    277     * @return the {@link ExecutorService} for executing the background task.
    278     */
    279    protected final synchronized ExecutorService getActiveExecutor() {
    280        return executor;
    281    }
    282
    283    /**
    284     * Gets the external {@link ExecutorService} to be used by this class.
    285     *
    286     * @return the {@link ExecutorService}.
    287     */
    288    public final synchronized ExecutorService getExternalExecutor() {
    289        return externalExecutor;
    290    }
    291
    292    /**
    293     * Gets the {@link Future} object that was created when {@link #start()}
    294     * was called. Therefore this method can only be called after {@code
    295     * start()}.
    296     *
    297     * @return the {@link Future} object wrapped by this initializer.
    298     * @throws IllegalStateException if {@link #start()} has not been called.
    299     */
    300    public synchronized Future<T> getFuture() {
    301        if (future == null) {
    302            throw new IllegalStateException("start() must be called first!");
    303        }
    304        return future;
    305    }
    306
    307    /**
    308     * Gets the number of background tasks to be created for this
    309     * initializer. This information is evaluated when a temporary {@code
    310     * ExecutorService} is created. This base implementation returns 1. Derived
    311     * classes that do more complex background processing can override it. This
    312     * method is called from a synchronized block by the {@link #start()}
    313     * method. Therefore overriding methods should be careful with obtaining
    314     * other locks and return as fast as possible.
    315     *
    316     * @return the number of background tasks required by this initializer.
    317     */
    318    protected int getTaskCount() {
    319        return 1;
    320    }
    321
    322    /**
    323     * {@inheritDoc}
    324     */
    325    @Override
    326    protected Exception getTypedException(final Exception e) {
    327        //This Exception object will be used for type comparison in AbstractConcurrentInitializer.initialize but not thrown
    328        return new Exception(e);
    329    }
    330
    331    /**
    332     * Tests whether this instance is initialized. Once initialized, always returns true.
    333     * If initialization failed then the failure will be cached and this will never return
    334     * true.
    335     *
    336     * @return true if initialization completed successfully, otherwise false.
    337     * @since 3.14.0
    338     */
    339    @Override
    340    public synchronized boolean isInitialized() {
    341        if (future == null || !future.isDone()) {
    342            return false;
    343        }
    344        try {
    345            future.get();
    346            return true;
    347        } catch (CancellationException | ExecutionException | InterruptedException e) {
    348            return false;
    349        }
    350    }
    351
    352    /**
    353     * Tests whether this {@link BackgroundInitializer} has already
    354     * been started.
    355     *
    356     * @return a flag whether the {@link #start()} method has already been
    357     * called.
    358     */
    359    public synchronized boolean isStarted() {
    360        return future != null;
    361    }
    362
    363    /**
    364     * Sets an {@link ExecutorService} to be used by this class. The {@code
    365     * ExecutorService} passed to this method is used for executing the
    366     * background task. Thus it is possible to re-use an already existing
    367     * {@link ExecutorService} or to use a specially configured one. If no
    368     * {@link ExecutorService} is set, this instance creates a temporary one and
    369     * destroys it after background initialization is complete. Note that this
    370     * method must be called before {@link #start()}; otherwise an exception is
    371     * thrown.
    372     *
    373     * @param externalExecutor the {@link ExecutorService} to be used.
    374     * @throws IllegalStateException if this initializer has already been
    375     * started.
    376     */
    377    public final synchronized void setExternalExecutor(final ExecutorService externalExecutor) {
    378        if (isStarted()) {
    379            throw new IllegalStateException("Cannot set ExecutorService after start()!");
    380        }
    381        this.externalExecutor = externalExecutor;
    382    }
    383
    384    /**
    385     * Starts the background initialization. With this method the initializer
    386     * becomes active and invokes the {@link #initialize()} method in a
    387     * background task. A {@link BackgroundInitializer} can be started exactly
    388     * once. The return value of this method determines whether the start was
    389     * successful: only the first invocation of this method returns <strong>true</strong>,
    390     * following invocations will return <strong>false</strong>.
    391     *
    392     * @return a flag whether the initializer could be started successfully.
    393     */
    394    public synchronized boolean start() {
    395        // Not yet started?
    396        if (!isStarted()) {
    397            // Determine the executor to use and whether a temporary one has to be created.
    398            final ExecutorService tempExec;
    399            executor = getExternalExecutor();
    400            if (executor == null) {
    401                executor = tempExec = createExecutor();
    402            } else {
    403                tempExec = null;
    404            }
    405            future = executor.submit(createTask(tempExec));
    406            return true;
    407        }
    408        return false;
    409    }
    410}