BasicThreadFactory (Apache Commons Lang 3.17.0 API)
Description: declaration: package: org.apache.commons.lang3.concurrent, class: BasicThreadFactory

Package org.apache.commons.lang3.concurrent

# Class BasicThreadFactory

java.lang.Object
org.apache.commons.lang3.concurrent.BasicThreadFactory

All Implemented Interfaces:
  `ThreadFactory`

public class BasicThreadFactory extends Object implements ThreadFactory
An implementation of the `ThreadFactory` interface that provides some configuration options for the threads it creates.

A `ThreadFactory` is used for instance by an `ExecutorService` to create the threads it uses for executing tasks. In many cases users do not have to care about a `ThreadFactory` because the default one used by an `ExecutorService` will do. However, if there are special requirements for the threads, a custom `ThreadFactory` has to be created.

This class provides some frequently needed configuration options for the threads it creates. These are the following:

- A name pattern for the threads created by this factory can be specified. This is often useful if an application uses multiple executor services for different purposes. If the names of the threads used by these services have meaningful names, log output or exception traces can be much easier to read. Naming patterns are format strings as used by the `String.format()` method. The string can contain the place holder `%d` which will be replaced by the number of the current thread (`ThreadFactoryImpl` keeps a counter of the threads it has already created). For instance, the naming pattern `"My %d. worker thread"` will result in thread names like `"My 1. worker thread"`, `"My 2. worker thread"` and so on.
- A flag whether the threads created by this factory should be daemon threads. This can impact the exit behavior of the current Java application because the JVM shuts down if there are only daemon threads running.
- The priority of the thread. Here an integer value can be provided. The `Thread` class defines constants for valid ranges of priority values.
- The `Thread.UncaughtExceptionHandler` for the thread. This handler is called if an uncaught exception occurs within the thread.

`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 `ThreadFactory` is used.

Instances of `BasicThreadFactory` are not created directly, but the nested `BasicThreadFactory.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 `BasicThreadFactory` is created and installed in an `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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `BasicThreadFactory.Builder`
  A builder class for creating instances of `BasicThreadFactory`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final Boolean`
  `getDaemonFlag()`
  Gets the daemon flag.
  `final String`
  `getNamingPattern()`
  Gets the naming pattern for naming newly created threads.
  `final Integer`
  `getPriority()`
  Gets the priority of the threads created by this factory.
  `long`
  `getThreadCount()`
  Gets the number of threads this factory has already created.
  `final Thread.UncaughtExceptionHandler`
  `getUncaughtExceptionHandler()`
  Gets the `Thread.UncaughtExceptionHandler` for the threads created by this factory.
  `final ThreadFactory`
  `getWrappedFactory()`
  Gets the wrapped `ThreadFactory`.
  `Thread`
  `newThread(Runnable runnable)`
  Creates a new thread.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### getDaemonFlag

    public final Boolean getDaemonFlag()
    Gets the daemon flag. This flag determines whether newly created threads should be daemon threads. If true, this factory object calls `setDaemon(true)` on the newly created threads. Result can be null if no daemon flag was provided at creation time.
    Returns:
      the daemon flag

  - ### getNamingPattern

    public final String getNamingPattern()
    Gets the naming pattern for naming newly created threads. Result can be null if no naming pattern was provided.
    Returns:
      the naming pattern

  - ### getPriority

    public final Integer getPriority()
    Gets the priority of the threads created by this factory. Result can be null if no priority was specified.
    Returns:
      the priority for newly created threads

  - ### getThreadCount

    public long getThreadCount()
    Gets the number of threads this factory has already created. This class maintains an internal counter that is incremented each time the `newThread(Runnable)` method is invoked.
    Returns:
      the number of threads created by this factory

  - ### getUncaughtExceptionHandler

    public final Thread.UncaughtExceptionHandler getUncaughtExceptionHandler()
    Gets the `Thread.UncaughtExceptionHandler` for the threads created by this factory. Result can be null if no handler was provided.
    Returns:
      the `Thread.UncaughtExceptionHandler`

  - ### getWrappedFactory

    public final ThreadFactory getWrappedFactory()
    Gets the wrapped `ThreadFactory`. This factory is used for actually creating threads. This method never returns null. If no `ThreadFactory` was passed when this object was created, a default thread factory is returned.
    Returns:
      the wrapped `ThreadFactory`

  - ### newThread

    public Thread newThread(Runnable runnable)
    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.
    Specified by:
      `newThread` in interface `ThreadFactory`
    Parameters:
      `runnable` - the `Runnable` to be executed by the new thread
    Returns:
      the newly created thread