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.Callable;
020import java.util.concurrent.ExecutorService;
021
022import org.apache.commons.lang3.Validate;
023
024/**
025 * <p>
026 * A specialized {@link BackgroundInitializer} implementation that wraps a
027 * {@code Callable} object.
028 * </p>
029 * <p>
030 * An instance of this class is initialized with a {@code Callable} object when
031 * it is constructed. The implementation of the {@link #initialize()} method
032 * defined in the super class delegates to this {@code Callable} so that the
033 * {@code Callable} is executed in the background thread.
034 * </p>
035 * <p>
036 * The {@code java.util.concurrent.Callable} interface is a standard mechanism
037 * of the JDK to define tasks to be executed by another thread. The {@code
038 * CallableBackgroundInitializer} class allows combining this standard interface
039 * with the background initializer API.
040 * </p>
041 * <p>
042 * Usage of this class is very similar to the default usage pattern of the
043 * {@link BackgroundInitializer} class: Just create an instance and provide the
044 * {@code Callable} object to be executed, then call the initializer's
045 * {@link #start()} method. This causes the {@code Callable} to be executed in
046 * another thread. When the results of the {@code Callable} are needed the
047 * initializer's {@link #get()} method can be called (which may block until
048 * background execution is complete). The following code fragment shows a
049 * typical usage example:
050 * </p>
051 *
052 * <pre>
053 * // a Callable that performs a complex computation
054 * Callable&lt;Integer&gt; computationCallable = new MyComputationCallable();
055 * // setup the background initializer
056 * CallableBackgroundInitializer&lt;Integer&gt; initializer =
057 *     new CallableBackgroundInitializer(computationCallable);
058 * initializer.start();
059 * // Now do some other things. Initialization runs in a parallel thread
060 * ...
061 * // Wait for the end of initialization and access the result
062 * Integer result = initializer.get();
063 * </pre>
064 *
065 *
066 * @since 3.0
067 * @param <T> the type of the object managed by this initializer class
068 */
069public class CallableBackgroundInitializer<T> extends BackgroundInitializer<T> {
070    /** The Callable to be executed. */
071    private final Callable<T> callable;
072
073    /**
074     * Creates a new instance of {@code CallableBackgroundInitializer} and sets
075     * the {@code Callable} to be executed in a background thread.
076     *
077     * @param call the {@code Callable} (must not be <b>null</b>)
078     * @throws IllegalArgumentException if the {@code Callable} is <b>null</b>
079     */
080    public CallableBackgroundInitializer(final Callable<T> call) {
081        checkCallable(call);
082        callable = call;
083    }
084
085    /**
086     * Creates a new instance of {@code CallableBackgroundInitializer} and
087     * initializes it with the {@code Callable} to be executed in a background
088     * thread and the {@code ExecutorService} for managing the background
089     * execution.
090     *
091     * @param call the {@code Callable} (must not be <b>null</b>)
092     * @param exec an external {@code ExecutorService} to be used for task
093     * execution
094     * @throws IllegalArgumentException if the {@code Callable} is <b>null</b>
095     */
096    public CallableBackgroundInitializer(final Callable<T> call, final ExecutorService exec) {
097        super(exec);
098        checkCallable(call);
099        callable = call;
100    }
101
102    /**
103     * Performs initialization in a background thread. This implementation
104     * delegates to the {@code Callable} passed at construction time of this
105     * object.
106     *
107     * @return the result of the initialization
108     * @throws Exception if an error occurs
109     */
110    @Override
111    protected T initialize() throws Exception {
112        return callable.call();
113    }
114
115    /**
116     * Tests the passed in {@code Callable} and throws an exception if it is
117     * undefined.
118     *
119     * @param call the object to check
120     * @throws IllegalArgumentException if the {@code Callable} is <b>null</b>
121     */
122    private void checkCallable(final Callable<T> call) {
123        Validate.isTrue(call != null, "Callable must not be null!");
124    }
125}