/* * 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.Executors; import java.util.concurrent.ThreadFactory; import java.util.concurrent.atomic.AtomicLong; import org.apache.commons.lang3.Validate; /** *
* An implementation of the {@code ThreadFactory} interface that provides some * configuration options for the threads it creates. *
** A {@code ThreadFactory} is used for instance by an {@code ExecutorService} to * create the threads it uses for executing tasks. In many cases users do not * have to care about a {@code ThreadFactory} because the default one used by an * {@code ExecutorService} will do. However, if there are special requirements * for the threads, a custom {@code ThreadFactory} has to be created. *
** This class provides some frequently needed configuration options for the * threads it creates. These are the following: *
** {@code BasicThreadFactory} wraps another thread factory which actually * creates new threads. The configuration options are set on the threads created * by the wrapped thread factory. On construction time the factory to be wrapped * can be specified. If none is provided, a default {@code ThreadFactory} is * used. *
** Instances of {@code BasicThreadFactory} are not created directly, but the * nested {@code Builder} class is used for this purpose. Using the builder only * the configuration options an application is interested in need to be set. The * following example shows how a {@code BasicThreadFactory} is created and * installed in an {@code ExecutorService}: *
* ** // Create a factory that produces daemon threads with a naming pattern and * // a priority * BasicThreadFactory factory = new BasicThreadFactory.Builder() * .namingPattern("workerthread-%d") * .daemon(true) * .priority(Thread.MAX_PRIORITY) * .build(); * // Create an executor service for single-threaded execution * ExecutorService exec = Executors.newSingleThreadExecutor(factory); ** * @since 3.0 */ public class BasicThreadFactory implements ThreadFactory { /** A counter for the threads created by this factory. */ private final AtomicLong threadCounter; /** Stores the wrapped factory. */ private final ThreadFactory wrappedFactory; /** Stores the uncaught exception handler. */ private final Thread.UncaughtExceptionHandler uncaughtExceptionHandler; /** Stores the naming pattern for newly created threads. */ private final String namingPattern; /** Stores the priority. */ private final Integer priority; /** Stores the daemon status flag. */ private final Boolean daemon; /** * Creates a new instance of {@code ThreadFactoryImpl} and configures it * from the specified {@code Builder} object. * * @param builder the {@code Builder} object */ private BasicThreadFactory(final Builder builder) { if (builder.wrappedFactory == null) { wrappedFactory = Executors.defaultThreadFactory(); } else { wrappedFactory = builder.wrappedFactory; } namingPattern = builder.namingPattern; priority = builder.priority; daemon = builder.daemon; uncaughtExceptionHandler = builder.exceptionHandler; threadCounter = new AtomicLong(); } /** * Returns the wrapped {@code ThreadFactory}. This factory is used for * actually creating threads. This method never returns null. If no * {@code ThreadFactory} was passed when this object was created, a default * thread factory is returned. * * @return the wrapped {@code ThreadFactory} */ public final ThreadFactory getWrappedFactory() { return wrappedFactory; } /** * Returns the naming pattern for naming newly created threads. Result can * be null if no naming pattern was provided. * * @return the naming pattern */ public final String getNamingPattern() { return namingPattern; } /** * Returns the daemon flag. This flag determines whether newly created * threads should be daemon threads. If true, this factory object * calls {@code setDaemon(true)} on the newly created threads. Result can be * null if no daemon flag was provided at creation time. * * @return the daemon flag */ public final Boolean getDaemonFlag() { return daemon; } /** * Returns the priority of the threads created by this factory. Result can * be null if no priority was specified. * * @return the priority for newly created threads */ public final Integer getPriority() { return priority; } /** * Returns the {@code UncaughtExceptionHandler} for the threads created by * this factory. Result can be null if no handler was provided. * * @return the {@code UncaughtExceptionHandler} */ public final Thread.UncaughtExceptionHandler getUncaughtExceptionHandler() { return uncaughtExceptionHandler; } /** * Returns the number of threads this factory has already created. This * class maintains an internal counter that is incremented each time the * {@link #newThread(Runnable)} method is invoked. * * @return the number of threads created by this factory */ public long getThreadCount() { return threadCounter.get(); } /** * Creates a new thread. This implementation delegates to the wrapped * factory for creating the thread. Then, on the newly created thread the * corresponding configuration options are set. * * @param runnable the {@code Runnable} to be executed by the new thread * @return the newly created thread */ @Override public Thread newThread(final Runnable runnable) { final Thread thread = getWrappedFactory().newThread(runnable); initializeThread(thread); return thread; } /** * Initializes the specified thread. This method is called by * {@link #newThread(Runnable)} after a new thread has been obtained from * the wrapped thread factory. It initializes the thread according to the * options set for this factory. * * @param thread the thread to be initialized */ private void initializeThread(final Thread thread) { if (getNamingPattern() != null) { final Long count = Long.valueOf(threadCounter.incrementAndGet()); thread.setName(String.format(getNamingPattern(), count)); } if (getUncaughtExceptionHandler() != null) { thread.setUncaughtExceptionHandler(getUncaughtExceptionHandler()); } if (getPriority() != null) { thread.setPriority(getPriority().intValue()); } if (getDaemonFlag() != null) { thread.setDaemon(getDaemonFlag().booleanValue()); } } /** *
* A builder class for creating instances of {@code * BasicThreadFactory}. *
** Using this builder class instances of {@code BasicThreadFactory} can be * created and initialized. The class provides methods that correspond to * the configuration options supported by {@code BasicThreadFactory}. Method * chaining is supported. Refer to the documentation of {@code * BasicThreadFactory} for a usage example. *
* */ public static class Builder implements org.apache.commons.lang3.builder.Builder