RequestProcessor (Base Utilities API)

java.lang.Object
- org.openide.util.RequestProcessor

All Implemented Interfaces:

Executor, ExecutorService, ScheduledExecutorService
```
public final class RequestProcessor
extends Object
implements ScheduledExecutorService
```
Request processor is Executor (since version 7.16) capable to perform asynchronous requests in a dedicated thread pool. There are several use cases for RequestProcessor, most of them start with creating own RequestProcessor instance (which by itself is quite lightweight).
Do something later
In case you want something to be done later in some background thread, create an instance of RequestProcessor and post tasks to it.
```
 private static final RequestProcessor RP = new RequestProcessor(MyClass.class);
 // later
 RP.post(runnable, delay)
 
```
The above example guarantees that there is at most one runnable being processed in parallel. All your requests are serialized and processed one by one. RP works here like a simple mutex.
In case you want more tasks to run in parallel (not very often use case) you can specify higher throughput via RequestProcessor.RequestProcessor(java.lang.String, int). Then the RP works like a queue of requests passing through a semaphore with predefined number of DOWN()s.
You can wait for your tasks to be processed by keeping a reference to the last one and using waitFinished():
```
 private static final RequestProcessor RP = new RequestProcessor("My tasks");
 private volatile RequestProcessor.Task last;

 // when posting update the task
 last = RP.post(runnable, delay)

 // later wait
 last.waitFinished()
 
```
Periodic task
It is also possible to do something periodically. Use the schedule method:
```
 class Periodic implements Runnable {
   private static final RequestProcessor RP = new RequestProcessor(Periodic.class);
   private final RequestProcessor.Task CLEANER = RP.create(this);
   public void run() {
     doTheWork();
     CLEANER.schedule(DELAY);
   }
 }
 
```
Please think twice before using such periodic background activity. It is generally considered evil if some code runs without any user action. Your code shall respect the application's state, and for example when the application is minimized, do nothing.
Sliding task
Often you want to perform an update of your object internals based on changes in some model. However your update may be costly and you want to do it just once, regardless of how many changes are reported by the model. This can be achieved with a sliding task:
```
 class Updater implements PropertyChangeListener, Runnable {
   private static final RequestProcessor RP = new RequestProcessor(Updater.class);
   private final RequestProcessor.Task UPDATE = RP.create(this);

   public void propertyChange(PropertyChangeEvent ev) {
     UPDATE.schedule(1000);
   }

   public void run() {
     doTheWork();
   }
 }
 
```
The above code coalesces all events that arrive in 1s and for all of them does doTheWork just once.
Interruption of tasks
Since version 6.3 there is a conditional support for interruption of long running tasks. There always was a way to cancel not yet running task using RequestProcessor.Task.cancel() but if the task's run() method was already running, one was out of luck. Since version 6.3 the thread running the task is interrupted and the Runnable can check for that and terminate its execution sooner. In the runnable one shall check for thread interruption (done from RequestProcessor.Task.cancel()) and if true, return immediately as in this example:
```
 private static final RequestProcessor RP = new RequestProcessor("Interruptible", 1, true);
 public void run () {
     while (veryLongTimeLoop) {
       doAPieceOfIt ();

       if (Thread.interrupted ()) return;
     }
 }
 
```
Since org.openide.util, implements ScheduledExecutorService

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

class RequestProcessor.Task
The task describing the request sent to the processor.

Nested Classes
Modifier and Type	Class and Description
`class`	`RequestProcessor.Task` The task describing the request sent to the processor.

Constructor Summary

Constructors
Constructor and Description
`RequestProcessor()` Creates new RequestProcessor with automatically assigned unique name.
`RequestProcessor(Class<?> forClass)` Convenience constructor for a new RequestProcessor with throughput 1.
`RequestProcessor(String name)` Creates a new named RequestProcessor with throughput 1.
`RequestProcessor(String name, int throughput)` Creates a new named RequestProcessor with defined throughput.
`RequestProcessor(String name, int throughput, boolean interruptThread)` Creates a new named RequestProcessor with defined throughput which can support interruption of the thread the processor runs in.
`RequestProcessor(String name, int throughput, boolean interruptThread, boolean enableStackTraces)` Creates a new named `RequestProcessor` that allows to disable stack trace filling.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`boolean`	`awaitTermination(long timeout, TimeUnit unit)`
`RequestProcessor.Task`	`create(Runnable run)` Creates request that can be later started by setting its delay.
`RequestProcessor.Task`	`create(Runnable run, boolean initiallyFinished)` Creates request that can be later started by setting its delay.
`static RequestProcessor.Task`	`createRequest(Runnable run)` Deprecated. Sharing of one singlethreaded `RequestProcessor` among different users and posting even blocking requests is inherently deadlock-prone. See use cases.
`void`	`execute(Runnable command)` Implements contract of `Executor`.
`static RequestProcessor`	`getDefault()` Warning: The instance of `RequestProcessor` returned by this method has very bad performance side effects, don't use unless you understand all implications!
`<T> List<Future<T>>`	`invokeAll(Collection<? extends Callable<T>> tasks)`
`<T> List<Future<T>>`	`invokeAll(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)` Executes the given tasks, returning a list of Futures holding their status and results when all complete or the timeout expires, whichever happens first.
`<T> T`	`invokeAny(Collection<? extends Callable<T>> tasks)` Executes the given tasks, returning the result of one which has completed and cancelling any incomplete tasks.
`<T> T`	`invokeAny(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)` Executes the given tasks, returning a list of Futures holding their status and results when all complete or the timeout expires, whichever happens first.
`boolean`	`isRequestProcessorThread()` Tests if the current thread is request processor thread.
`boolean`	`isShutdown()`
`boolean`	`isTerminated()`
`RequestProcessor.Task`	`post(Runnable run)` This methods asks the request processor to start given runnable immediately.
`RequestProcessor.Task`	`post(Runnable run, int timeToWait)` This methods asks the request processor to start given runnable after `timeToWait` milliseconds.
`RequestProcessor.Task`	`post(Runnable run, int timeToWait, int priority)` This methods asks the request processor to start given runnable after `timeToWait` milliseconds.
`static RequestProcessor.Task`	`postRequest(Runnable run)` Deprecated. Sharing of one singlethreaded `RequestProcessor` among different users and posting even blocking requests is inherently deadlock-prone. See use cases.
`static RequestProcessor.Task`	`postRequest(Runnable run, int timeToWait)` Deprecated. Sharing of one singlethreaded `RequestProcessor` among different users and posting even blocking requests is inherently deadlock-prone. See use cases.
`static RequestProcessor.Task`	`postRequest(Runnable run, int timeToWait, int priority)` Deprecated. Sharing of one singlethreaded `RequestProcessor` among different users and posting even blocking requests is inherently deadlock-prone. See use cases.
`<T> ScheduledFuture<T>`	`schedule(Callable<T> callable, long delay, TimeUnit unit)`
`ScheduledFuture<?>`	`schedule(Runnable command, long delay, TimeUnit unit)`
`ScheduledFuture<?>`	`scheduleAtFixedRate(Runnable command, long initialDelay, long period, TimeUnit unit)` Schedules a runnable which will run with a given frequency, regardless of how long execution takes, with the exception that if execution takes longer than the specified delay, execution will be delayed but will never be run on two threads concurrently.
`ScheduledFuture<?>`	`scheduleWithFixedDelay(Runnable command, long initialDelay, long delay, TimeUnit unit)` Schedules a runnable which will run repeatedly after the specified initial delay, with the specified delay between the completion of one run and the start of the next.
`void`	`shutdown()`
`List<Runnable>`	`shutdownNow()`
`void`	`stop()` Stops processing of runnables processor.
`<T> Future<T>`	`submit(Callable<T> task)` Note: If the passed `Callable` implements `Cancellable`, then that object's `Cancellable.cancel()` method will be called if `Future.cancel(boolean)` is invoked.
`Future<?>`	`submit(Runnable task)` Note: If the passed `Runnable` implements `Cancellable`, then that object's `Cancellable.cancel()` method will be called if `Future.cancel(boolean)` is invoked.
`<T> Future<T>`	`submit(Runnable task, T predefinedResult)` Note: If the passed `Runnable` implements `Cancellable`, then that object's `Cancellable.cancel()` method will be called if `Future.cancel(boolean)` is invoked.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - RequestProcessor
```
public RequestProcessor()
```
    Creates new RequestProcessor with automatically assigned unique name.
  - RequestProcessor
```
public RequestProcessor(String name)
```
    Creates a new named RequestProcessor with throughput 1.
    
    Parameters:
    
    name - the name to use for the request processor thread
  - RequestProcessor
```
public RequestProcessor(Class<?> forClass)
```
    Convenience constructor for a new RequestProcessor with throughput 1. Typical usage is:
```
 class MyClass {
   private static final RequestProcessor RP = new RequestProcessor(MyClass.class);
 
 }
 
```
    Behaves as new RequestProcessor(MyClass.class.getName()).
    Parameters:
    
    forClass - name of this class gives name for the processor threads
    
    Since:
    
    8.6
  - RequestProcessor
```
public RequestProcessor(String name,
                        int throughput)
```
    Creates a new named RequestProcessor with defined throughput.
    
    Parameters:
    
    name - the name to use for the request processor thread
    
    throughput - the maximal count of requests allowed to run in parallel
    
    Since:
    
    OpenAPI version 2.12
  - RequestProcessor
```
public RequestProcessor(String name,
                        int throughput,
                        boolean interruptThread)
```
    Creates a new named RequestProcessor with defined throughput which can support interruption of the thread the processor runs in. There always was a way how to cancel not yet running task using RequestProcessor.Task.cancel() but if the task was already running, one was out of luck. With this constructor one can create a RequestProcessor which threads thread running tasks are interrupted and the Runnable can check for that and terminate its execution sooner. In the runnable one shall check for thread interruption (done from RequestProcessor.Task.cancel()) and if true, return immediatelly as in this example:
```
 public void run () {
     while (veryLongTimeLook) {
       doAPieceOfIt ();

       if (Thread.interrupted ()) return;
     }
 }
 
```
    Parameters:
    
    name - the name to use for the request processor thread
    
    throughput - the maximal count of requests allowed to run in parallel
    
    interruptThread - true if RequestProcessor.Task.cancel() shall interrupt the thread
    
    Since:
    
    6.3
  - RequestProcessor
```
public RequestProcessor(String name,
                        int throughput,
                        boolean interruptThread,
                        boolean enableStackTraces)
```
    Creates a new named RequestProcessor that allows to disable stack trace filling. By default, when assertions are on, each task posted on RequestProcessor stores the stack trace at the time of posting. When an exception is later thrown from the task, it allows to print not only stack trace of the task but also stack trace of the code that posted it. However this may be a performance bottleneck in cases when hundreds of short task are scheduled. This constructor then allows to create RequestProcessor which never stores stack traces at the time of posting.
    See constructor RequestProcessor.RequestProcessor(String, int, boolean) for details of interruptThread parameter.
    
    Parameters:
    
    name - the name to use for the request processor thread
    
    throughput - the maximal count of requests allowed to run in parallel
    
    interruptThread - true if RequestProcessor.Task.cancel() shall interrupt the thread
    
    enableStackTraces - false when request processor should not fill stack traces when task is posted. Default is true when assertions are enabled, false otherwise.
    
    Since:
    
    7.24
- Method Detail
  - getDefault
```
public static RequestProcessor getDefault()
```
    Warning: The instance of RequestProcessor returned by this method has very bad performance side effects, don't use unless you understand all implications!
    This is the getter for the shared instance of the RequestProcessor. This instance is shared by anybody who needs a way of performing sporadic asynchronous work.
    The problem of this method lays exactly in the definition of sporadic. Often one needs to process something at some sporadic moment, but, for example due to storm of events, one needs to execute more than one tasks at the same sporadic moment. In this situation using RequestProcessor.getDefault() is horribly inefficient. All such tasks would be processed in parallel, allocating their own execution threads (up to 50). As the price per one thread is estimated to 1MB on common systems, you shall think twice whether you want to increase the memory consumption of your application so much at these sporadic moments.
    There is a runtime detection of the parallel misuse of this method since version 8.3. It is activated only in development mode (when executed with assertions on) and prints warning into log whenever there are more than three same tasks running in parallel. In case you see such warning, or in case you are in doubts consider creation of your own, private, single throughput processor:
```
 class YourClass {
   private static final RequestProcessor RP = new RequestProcessor(YourClass.class);
 }
 
```
    Such private field is lightweight and guarantees that all your tasks will be processed sequentially, one by one. Just don't forget to make the field static!
    Tasks posted to this instance may be canceled until they start their execution. If a there is a need to cancel a task while it is running a seperate request processor needs to be created via RequestProcessor.RequestProcessor(String, int, boolean) constructor.
    Returns:
    
    an instance of RequestProcessor that is capable of performing "unlimited" (currently limited to 50, just for case of misuse) number of requests in parallel.
    
    Since:
    
    version 2.12
    
    See Also:
    
    RequestProcessor.RequestProcessor(String, int, boolean), RequestProcessor.Task.cancel()
  - execute
```
public void execute(Runnable command)
```
    Implements contract of Executor. Simply delegates to RequestProcessor.post(java.lang.Runnable).
    
    Specified by:
    
    execute in interface Executor
    
    Parameters:
    
    command - the runnable to execute
    
    Since:
    
    7.16
  - post
```
public RequestProcessor.Task post(Runnable run)
```
    This methods asks the request processor to start given runnable immediately. The default priority is Thread.MIN_PRIORITY.
    
    Parameters:
    
    run - class to run
    
    Returns:
    
    the task to control the request
  - post
```
public RequestProcessor.Task post(Runnable run,
                                  int timeToWait)
```
    This methods asks the request processor to start given runnable after timeToWait milliseconds. The default priority is Thread.MIN_PRIORITY.
    
    Parameters:
    
    run - class to run
    
    timeToWait - to wait before execution
    
    Returns:
    
    the task to control the request
  - post
```
public RequestProcessor.Task post(Runnable run,
                                  int timeToWait,
                                  int priority)
```
    This methods asks the request processor to start given runnable after timeToWait milliseconds. Given priority is assigned to the request.
    For request relaying please consider:
```
    post(run, timeToWait, Thread.currentThread().getPriority());
 
```
    Parameters:
    
    run - class to run
    
    timeToWait - to wait before execution
    
    priority - the priority from Thread.MIN_PRIORITY to Thread.MAX_PRIORITY
    
    Returns:
    
    the task to control the request
  - create
```
public RequestProcessor.Task create(Runnable run)
```
    Creates request that can be later started by setting its delay. The request is not immediatelly put into the queue. It is planned after setting its delay by schedule method. By default the initial state of the task is !isFinished() so doing waitFinished() will block on and wait until the task is scheduled.
    
    Parameters:
    
    run - action to run in the process
    
    Returns:
    
    the task to control execution of given action
  - create
```
public RequestProcessor.Task create(Runnable run,
                                    boolean initiallyFinished)
```
    Creates request that can be later started by setting its delay. The request is not immediatelly put into the queue. It is planned after setting its delay by schedule method.
    
    Parameters:
    
    run - action to run in the process
    
    initiallyFinished - should the task be marked initially finished? If so the RequestProcessor.Task.waitFinished() on the task will succeeded immediatelly even the task has not yet been RequestProcessor.Task.schedule(int)d.
    
    Returns:
    
    the task to control execution of given action
    
    Since:
    
    6.8
  - isRequestProcessorThread
```
public boolean isRequestProcessorThread()
```
    Tests if the current thread is request processor thread. This method could be used to prevent the deadlocks using waitFinished method. Any two tasks created by request processor must not wait for themself.
    
    Returns:
    
    true if the current thread is request processor thread, otherwise false
  - stop
```
public void stop()
```
    Stops processing of runnables processor. The currently running runnable is finished and no new is started.
  - postRequest
```
@Deprecated
public static RequestProcessor.Task postRequest(Runnable run)
```
    Deprecated. Sharing of one singlethreaded RequestProcessor among different users and posting even blocking requests is inherently deadlock-prone. See use cases.
    
    This methods asks the request processor to start given runnable after timeToWait milliseconds. The default priority is Thread.MIN_PRIORITY.
    
    Parameters:
    
    run - class to run
    
    Returns:
    
    the task to control the request
  - postRequest
```
@Deprecated
public static RequestProcessor.Task postRequest(Runnable run,
                                                            int timeToWait)
```
    Deprecated. Sharing of one singlethreaded RequestProcessor among different users and posting even blocking requests is inherently deadlock-prone. See use cases.
    
    This methods asks the request processor to start given runnable after timeToWait milliseconds. The default priority is Thread.MIN_PRIORITY.
    
    Parameters:
    
    run - class to run
    
    timeToWait - to wait before execution
    
    Returns:
    
    the task to control the request
  - postRequest
```
@Deprecated
public static RequestProcessor.Task postRequest(Runnable run,
                                                            int timeToWait,
                                                            int priority)
```
    Deprecated. Sharing of one singlethreaded RequestProcessor among different users and posting even blocking requests is inherently deadlock-prone. See use cases.
    
    This methods asks the request processor to start given runnable after timeToWait milliseconds. Given priority is assigned to the request.
    
    Parameters:
    
    run - class to run
    
    timeToWait - to wait before execution
    
    priority - the priority from Thread.MIN_PRIORITY to Thread.MAX_PRIORITY
    
    Returns:
    
    the task to control the request
  - createRequest
```
@Deprecated
public static RequestProcessor.Task createRequest(Runnable run)
```
    Deprecated. Sharing of one singlethreaded RequestProcessor among different users and posting even blocking requests is inherently deadlock-prone. See use cases.
    
    Creates request that can be later started by setting its delay. The request is not immediately put into the queue. It is planned after setting its delay by setDelay method.
    
    Parameters:
    
    run - action to run in the process
    
    Returns:
    
    the task to control execution of given action
  - shutdown
```
public void shutdown()
```
    Specified by:
    
    shutdown in interface ExecutorService
    
    Throws:
    
    an - IllegalStateException if called on the default request processor
    
    Since:
    
    org.openide.util 8.2
  - shutdownNow
```
public List<Runnable> shutdownNow()
```
    Specified by:
    
    shutdownNow in interface ExecutorService
    
    Throws:
    
    an - IllegalStateException if called on the default request processor
    
    Since:
    
    org.openide.util 8.2
  - isShutdown
```
public boolean isShutdown()
```
    Specified by:
    
    isShutdown in interface ExecutorService
    
    Since:
    
    org.openide.util 8.2
  - isTerminated
```
public boolean isTerminated()
```
    Specified by:
    
    isTerminated in interface ExecutorService
    
    Since:
    
    org.openide.util 8.2
  - awaitTermination
```
public boolean awaitTermination(long timeout,
                                TimeUnit unit)
                         throws InterruptedException
```
    Specified by:
    
    awaitTermination in interface ExecutorService
    
    Throws:
    
    InterruptedException
    
    Since:
    
    org.openide.util 8.2
  - submit
```
public <T> Future<T> submit(Callable<T> task)
```
    Note: If the passed Callable implements Cancellable, then that object's Cancellable.cancel() method will be called if Future.cancel(boolean) is invoked. If Cancellable.cancel() returns false, then the job will not be cancelled.
    
    Specified by:
    
    submit in interface ExecutorService
    
    Since:
    
    org.openide.util 8.2
  - submit
```
public <T> Future<T> submit(Runnable task,
                            T predefinedResult)
```
    Note: If the passed Runnable implements Cancellable, then that object's Cancellable.cancel() method will be called if Future.cancel(boolean) is invoked. If Cancellable.cancel() returns false, then the job will not be cancelled.
    
    Specified by:
    
    submit in interface ExecutorService
    
    Since:
    
    org.openide.util 8.2
  - submit
```
public Future<?> submit(Runnable task)
```
    Note: If the passed Runnable implements Cancellable, then that object's Cancellable.cancel() method will be called if Future.cancel(boolean) is invoked. If Cancellable.cancel() returns false, then the job will not be cancelled.
    
    Specified by:
    
    submit in interface ExecutorService
    
    Since:
    
    org.openide.util 8.2
  - invokeAll
```
public <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks)
                              throws InterruptedException
```
    Specified by:
    
    invokeAll in interface ExecutorService
    
    Throws:
    
    InterruptedException
    
    Since:
    
    org.openide.util 8.2
  - invokeAll
```
public <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks,
                                     long timeout,
                                     TimeUnit unit)
                              throws InterruptedException
```
    Executes the given tasks, returning a list of Futures holding their status and results when all complete or the timeout expires, whichever happens first.
    
    Specified by:
    
    invokeAll in interface ExecutorService
    
    Throws:
    
    InterruptedException
    
    Since:
    
    org.openide.util 8.2
  - invokeAny
```
public <T> T invokeAny(Collection<? extends Callable<T>> tasks)
                throws InterruptedException,
                       ExecutionException
```
    Executes the given tasks, returning the result of one which has completed and cancelling any incomplete tasks.
    
    Specified by:
    
    invokeAny in interface ExecutorService
    
    Throws:
    
    InterruptedException
    
    ExecutionException
    
    Since:
    
    org.openide.util 8.2
  - invokeAny
```
public <T> T invokeAny(Collection<? extends Callable<T>> tasks,
                       long timeout,
                       TimeUnit unit)
                throws InterruptedException,
                       ExecutionException,
                       TimeoutException
```
    Executes the given tasks, returning a list of Futures holding their status and results when all complete or the timeout expires, whichever happens first.
    
    Specified by:
    
    invokeAny in interface ExecutorService
    
    Type Parameters:
    
    T - The result type
    
    Parameters:
    
    tasks - A collection of callables
    
    timeout - The maximum time to wait for completion, in the specified time units
    
    unit - The time unit
    
    Returns:
    
    A list of futures
    
    Throws:
    
    InterruptedException - if the timeout expires or execution is interrupted
    
    ExecutionException
    
    TimeoutException
    
    Since:
    
    org.openide.util 8.2
  - schedule
```
public ScheduledFuture<?> schedule(Runnable command,
                                   long delay,
                                   TimeUnit unit)
```
    Specified by:
    
    schedule in interface ScheduledExecutorService
    
    Since:
    
    org.openide.util 8.2
  - schedule
```
public <T> ScheduledFuture<T> schedule(Callable<T> callable,
                                       long delay,
                                       TimeUnit unit)
```
    Specified by:
    
    schedule in interface ScheduledExecutorService
    
    Since:
    
    org.openide.util 8.2
  - scheduleAtFixedRate
```
public ScheduledFuture<?> scheduleAtFixedRate(Runnable command,
                                              long initialDelay,
                                              long period,
                                              TimeUnit unit)
```
    Schedules a runnable which will run with a given frequency, regardless of how long execution takes, with the exception that if execution takes longer than the specified delay, execution will be delayed but will never be run on two threads concurrently.
    
    Specified by:
    
    scheduleAtFixedRate in interface ScheduledExecutorService
    
    Since:
    
    org.openide.util 8.2
  - scheduleWithFixedDelay
```
public ScheduledFuture<?> scheduleWithFixedDelay(Runnable command,
                                                 long initialDelay,
                                                 long delay,
                                                 TimeUnit unit)
```
    Schedules a runnable which will run repeatedly after the specified initial delay, with the specified delay between the completion of one run and the start of the next.
    
    Specified by:
    
    scheduleWithFixedDelay in interface ScheduledExecutorService
    
    Since:
    
    org.openide.util 8.2

Class RequestProcessor

Do something later

Periodic task

Sliding task

Interruption of tasks

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

RequestProcessor

RequestProcessor

RequestProcessor

RequestProcessor

RequestProcessor

RequestProcessor

Method Detail

getDefault

execute

post

post

post

create

create

isRequestProcessorThread

stop

postRequest

postRequest

postRequest

createRequest

shutdown

shutdownNow

isShutdown

isTerminated

awaitTermination

submit

submit

submit

invokeAll

invokeAll

invokeAny

invokeAny

schedule

schedule

scheduleAtFixedRate

scheduleWithFixedDelay