126 lines
4.8 KiB
Java
126 lines
4.8 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.Callable;
|
|
import java.util.concurrent.ExecutorService;
|
|
|
|
import org.apache.commons.lang3.Validate;
|
|
|
|
/**
|
|
* <p>
|
|
* A specialized {@link BackgroundInitializer} implementation that wraps a
|
|
* {@code Callable} object.
|
|
* </p>
|
|
* <p>
|
|
* An instance of this class is initialized with a {@code Callable} object when
|
|
* it is constructed. The implementation of the {@link #initialize()} method
|
|
* defined in the super class delegates to this {@code Callable} so that the
|
|
* {@code Callable} is executed in the background thread.
|
|
* </p>
|
|
* <p>
|
|
* The {@code java.util.concurrent.Callable} interface is a standard mechanism
|
|
* of the JDK to define tasks to be executed by another thread. The {@code
|
|
* CallableBackgroundInitializer} class allows combining this standard interface
|
|
* with the background initializer API.
|
|
* </p>
|
|
* <p>
|
|
* Usage of this class is very similar to the default usage pattern of the
|
|
* {@link BackgroundInitializer} class: Just create an instance and provide the
|
|
* {@code Callable} object to be executed, then call the initializer's
|
|
* {@link #start()} method. This causes the {@code Callable} to be executed in
|
|
* another thread. When the results of the {@code Callable} are needed the
|
|
* initializer's {@link #get()} method can be called (which may block until
|
|
* background execution is complete). The following code fragment shows a
|
|
* typical usage example:
|
|
* </p>
|
|
*
|
|
* <pre>
|
|
* // a Callable that performs a complex computation
|
|
* Callable<Integer> computationCallable = new MyComputationCallable();
|
|
* // setup the background initializer
|
|
* CallableBackgroundInitializer<Integer> initializer =
|
|
* new CallableBackgroundInitializer(computationCallable);
|
|
* initializer.start();
|
|
* // Now do some other things. Initialization runs in a parallel thread
|
|
* ...
|
|
* // Wait for the end of initialization and access the result
|
|
* Integer result = initializer.get();
|
|
* </pre>
|
|
*
|
|
*
|
|
* @since 3.0
|
|
* @param <T> the type of the object managed by this initializer class
|
|
*/
|
|
public class CallableBackgroundInitializer<T> extends BackgroundInitializer<T> {
|
|
/** The Callable to be executed. */
|
|
private final Callable<T> callable;
|
|
|
|
/**
|
|
* Creates a new instance of {@code CallableBackgroundInitializer} and sets
|
|
* the {@code Callable} to be executed in a background thread.
|
|
*
|
|
* @param call the {@code Callable} (must not be <b>null</b>)
|
|
* @throws IllegalArgumentException if the {@code Callable} is <b>null</b>
|
|
*/
|
|
public CallableBackgroundInitializer(final Callable<T> call) {
|
|
checkCallable(call);
|
|
callable = call;
|
|
}
|
|
|
|
/**
|
|
* Creates a new instance of {@code CallableBackgroundInitializer} and
|
|
* initializes it with the {@code Callable} to be executed in a background
|
|
* thread and the {@code ExecutorService} for managing the background
|
|
* execution.
|
|
*
|
|
* @param call the {@code Callable} (must not be <b>null</b>)
|
|
* @param exec an external {@code ExecutorService} to be used for task
|
|
* execution
|
|
* @throws IllegalArgumentException if the {@code Callable} is <b>null</b>
|
|
*/
|
|
public CallableBackgroundInitializer(final Callable<T> call, final ExecutorService exec) {
|
|
super(exec);
|
|
checkCallable(call);
|
|
callable = call;
|
|
}
|
|
|
|
/**
|
|
* Performs initialization in a background thread. This implementation
|
|
* delegates to the {@code Callable} passed at construction time of this
|
|
* object.
|
|
*
|
|
* @return the result of the initialization
|
|
* @throws Exception if an error occurs
|
|
*/
|
|
@Override
|
|
protected T initialize() throws Exception {
|
|
return callable.call();
|
|
}
|
|
|
|
/**
|
|
* Tests the passed in {@code Callable} and throws an exception if it is
|
|
* undefined.
|
|
*
|
|
* @param callable the object to check
|
|
* @throws IllegalArgumentException if the {@code Callable} is <b>null</b>
|
|
*/
|
|
private void checkCallable(final Callable<T> callable) {
|
|
Validate.notNull(callable, "callable");
|
|
}
|
|
}
|