org.glassfish.jersey.spi

## Class AbstractThreadPoolProvider<E extends ThreadPoolExecutor>

- java.lang.Object
- - org.glassfish.jersey.spi.AbstractThreadPoolProvider<E>

All Implemented Interfaces:
  AutoCloseable

Direct Known Subclasses:
  ScheduledThreadPoolExecutorProvider, ThreadPoolExecutorProvider

    public abstract class AbstractThreadPoolProvider<E extends ThreadPoolExecutor>
    extends Object
    implements AutoCloseable

Abstract thread pool executor provider.

This class provides a skeleton implementation for provisioning and basic lifecycle management of thread pool executors. Every instance of the concrete implementation of this provider class creates at most one shared and lazily initialized thread pool executor instance, which can be retrieved by invoking the `getExecutor()` method. This provider also makes sure that the provisioned thread pool executor instance is properly shut down when the managing provider instance is `closed` (in case it has not been already shut down).

At minimum, concrete subclasses of this provider are expected to implement the `createExecutor(int, java.util.concurrent.ThreadFactory, java.util.concurrent.RejectedExecutionHandler)` method that is used as a thread pool instance factory. The method is invoked lazily, with the first call to the `getExecutor()` method. The result returned from the `createExecutor()` method is cached internally and is used as a return value for subsequent calls to the `getExecutor()` method. This means, that `createExecutor()` method is guaranteed to be invoked at most once during the lifetime of any particular provider instance.

Since:
  2.18
Author:
  Marek Potociar

### Field Summary

Fields
`static int` `DEFAULT_TERMINATION_TIMEOUT` Default thread pool executor termination timeout in milliseconds.

### Constructor Summary

Constructors
`protected` `AbstractThreadPoolProvider(String name)` Inheritance constructor.

### Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
`void` `close()` Close this thread pool executor provider.
`protected abstract E` `createExecutor(int corePoolSize, ThreadFactory threadFactory, RejectedExecutionHandler handler)` Create a new instance of the thread pool executor that should be provided by the `getExecutor()` method.
`protected ThreadFactory` `getBackingThreadFactory()` Get a backing thread factory that should be used as a delegate for creating the new threads for the provisioned executor service.
`protected int` `getCorePoolSize()` Get the number of the core threads of the the provisioned thread pool executor.
`protected E` `getExecutor()` Get the thread pool executor.
`protected RejectedExecutionHandler` `getRejectedExecutionHandler()` Get the handler for tasks that could not be executed by the provisioned thread pool executor.
`protected int` `getTerminationTimeout()` Get the provisioned thread pool executor termination time out (in milliseconds).
`boolean` `isClosed()` Check if this thread pool executor provider has been `closed`.
`protected void` `onClose()` Close event handler, that invoked during the `close()` operation.

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

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

### Field Detail

#### DEFAULT_TERMINATION_TIMEOUT

    public static final int DEFAULT_TERMINATION_TIMEOUT

Default thread pool executor termination timeout in milliseconds.

See Also:
  Constant Field Values

### Constructor Detail

#### AbstractThreadPoolProvider

    protected AbstractThreadPoolProvider(String name)

Inheritance constructor.

Parameters:
  `name` - name of the provided thread pool executor. Will be used in the names of threads created & used by the provided thread pool executor.

### Method Detail

#### getExecutor

    protected final E getExecutor()

Get the thread pool executor.

The first invocation of this method will invoke the overridden `createExecutor(int, java.util.concurrent.ThreadFactory, java.util.concurrent.RejectedExecutionHandler)` method to retrieve the provided thread pool executor instance. The created thread pool executor instance is then cached and will be returned upon subsequent calls to this method.

Returns:
  provided thread pool executor.
Throws:
  `IllegalStateException` - in case the provider has been `closed` already.
See Also:
  `createExecutor(int, java.util.concurrent.ThreadFactory, java.util.concurrent.RejectedExecutionHandler)`, `close()`, `isClosed()`

#### createExecutor

    protected abstract E createExecutor(int corePoolSize,
                                        ThreadFactory threadFactory,
                                        RejectedExecutionHandler handler)

Create a new instance of the thread pool executor that should be provided by the `getExecutor()` method.

Concrete implementations of this class must override this method and implement the logic that creates the executor service to be provided. The returned thread pool executor will be shut down when this provider instance is `closed`.

This method is invoked at most once, during the first call to the `getExecutor()` method.

Parameters:
  `corePoolSize` - number of core threads the provisioned thread pool executor should provide.
  `threadFactory` - thread factory to be used by the provisioned thread pool executor when creating new threads.
  `handler` - handler for tasks that cannot be executed by the provisioned thread pool executor (e.g. due to a shutdown).
Returns:
  new instance of the provided thread pool executor.
See Also:
  `getExecutor()`, `close()`, `getCorePoolSize()`, `getBackingThreadFactory()`, `getRejectedExecutionHandler()`

#### getTerminationTimeout

    protected int getTerminationTimeout()

Get the provisioned thread pool executor termination time out (in milliseconds).

The method is used during the thread pool executor shutdown sequence to determine the shutdown timeout, when this provider instance is `closed`. In case the thread pool executor shutdown is interrupted or the timeout expires, the provisioned thread pool executor is `shutdown forcefully`.

The method can be overridden to customize the thread pool executor termination time out. If not customized, the method defaults to 5000 ms.

Returns:
  provisioned thread pool executor termination time out (in milliseconds).
See Also:
  `close()`, `ExecutorService.awaitTermination(long, java.util.concurrent.TimeUnit)`

#### getCorePoolSize

    protected int getCorePoolSize()

Get the number of the core threads of the the provisioned thread pool executor.

The value from this method is passed as one of the input parameters in a call to the `createExecutor(int, java.util.concurrent.ThreadFactory, java.util.concurrent.RejectedExecutionHandler)` method.

The method can be overridden to customize the number of core threads of the provisioned thread pool executor. If not customized, the method defaults to the number of `available processors` in the system.

Returns:
  number of core threads in the provisioned thread pool executor.
See Also:
  `createExecutor(int, java.util.concurrent.ThreadFactory, java.util.concurrent.RejectedExecutionHandler)`

#### getRejectedExecutionHandler

    protected RejectedExecutionHandler getRejectedExecutionHandler()

Get the handler for tasks that could not be executed by the provisioned thread pool executor.

The value from this method is passed as one of the input parameters in a call to the `createExecutor(int, java.util.concurrent.ThreadFactory, java.util.concurrent.RejectedExecutionHandler)` method.

The method can be overridden to customize the rejected task handler used by the provisioned thread pool executor. If not customized, the method provides a basic default NO-OP implementation.

Returns:
  handler for tasks that could not be executed by the provisioned thread pool executor.
See Also:
  `createExecutor(int, java.util.concurrent.ThreadFactory, java.util.concurrent.RejectedExecutionHandler)`

#### getBackingThreadFactory

    protected ThreadFactory getBackingThreadFactory()

Get a backing thread factory that should be used as a delegate for creating the new threads for the provisioned executor service.

The value from this method is used as a backing `ThreadFactory` for an internally constructed thread factory instance that is passed as one of the input parameters in a call to the `createExecutor(int, java.util.concurrent.ThreadFactory, java.util.concurrent.RejectedExecutionHandler)` method. When not `null`, the new threads will be created by invoking the `ThreadFactory.newThread(Runnable)` on this backing `ThreadFactory`.

The method can be overridden to customize the backing thread factory for the provisioned thread pool executor. If not customized, the method returns `null` by default.

Returns:
  backing thread factory for the provisioned thread pool executor. May return `null`, in which case no backing thread factory will be used.
See Also:
  `createExecutor(int, java.util.concurrent.ThreadFactory, java.util.concurrent.RejectedExecutionHandler)`

#### isClosed

    public final boolean isClosed()

Check if this thread pool executor provider has been `closed`.

Returns:
  `true` if this provider has been closed, `false` otherwise.
See Also:
  `close()`

#### onClose

    protected void onClose()

Close event handler, that invoked during the `close()` operation.

Concrete implementations of this provider class may override this method to perform any additional resource clean-up. Default implementation is a NO-OP.

See Also:
  `close()`

#### close

    public final void close()

Close this thread pool executor provider.

Once the provider is closed, it will stop providing the thread pool executor and subsequent invocations to `getExecutor()` method will result in an `IllegalStateException` being thrown. The current status of the provider can be checked via `isClosed()` method.

Upon invocation, the following tasks are performed:

- The thread pool executor instance provisioning via `getExecutor()` method is stopped.
- The `onClose()` event handler is invoked.
- The thread pool executor, if previously `created` and `provisioned`, is shut down.

The actual thread pool executor shutdown is performed as follows:

First, a `graceful shutdown` is attempted. The value returned from a call to `getTerminationTimeout()` method is used to determine the graceful shutdown timeout period.

In case the thread pool executor graceful shutdown is interrupted or the timeout expires, the provisioned thread pool executor is `shutdown forcefully`. All tasks that have never commenced execution are then `cancelled interruptingly`, if possible.

Specified by:
  `close` in interface `AutoCloseable`
See Also:
  `isClosed()`, `onClose()`, `getExecutor()`, `getTerminationTimeout()`