org.openide.util
Class RequestProcessor

java.lang.Object
  extended by org.openide.util.RequestProcessor

public final class RequestProcessor
extends java.lang.Object

Request processor that is capable to execute requests in dedicated threads. You can create your own instance or use the shared one.

There are several use cases for RequestProcessor:

Note: If you don't need to serialize your requests but you're generating them in bursts, you should use your private RequestProcessor instance with limited throughput (probably set to 1), NetBeans would try to run all your requests in parallel otherwise.

Since version 6.3 there is a conditional support for interruption of long running tasks. 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. 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 immediatelly as in this example:

 public void run () {
     while (veryLongTimeLook) {
       doAPieceOfIt ();

       if (Thread.interrupted ()) return;
     }
 }
 

Author:
Petr Nejedly, Jaroslav Tulach

Nested Class Summary
 class RequestProcessor.Task
          The task describing the request sent to the processor.
 
Field Summary
(package private)  java.lang.String name
          The name of the RequestProcessor instance
(package private) static boolean SLOW
           
(package private)  boolean stopped
          If the RP was stopped, this variable will be set, every new post() will throw an exception and no task will be processed any further
 
Constructor Summary
RequestProcessor()
          Creates new RequestProcessor with automatically assigned unique name.
RequestProcessor(java.lang.String name)
          Creates a new named RequestProcessor with throughput 1.
RequestProcessor(java.lang.String name, int throughput)
          Creates a new named RequestProcessor with defined throughput.
RequestProcessor(java.lang.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.
 
Method Summary
(package private)  RequestProcessor.Task askForWork(org.openide.util.RequestProcessor.Processor worker, java.lang.String debug)
           
 RequestProcessor.Task create(java.lang.Runnable run)
          Creates request that can be later started by setting its delay.
 RequestProcessor.Task create(java.lang.Runnable run, boolean initiallyFinished)
          Creates request that can be later started by setting its delay.
static RequestProcessor.Task createRequest(java.lang.Runnable run)
          Deprecated. Sharing of one singlethreaded RequestProcessor among different users and posting even blocking requests is inherently deadlock-prone. See use cases.
(package private)  void enqueue(org.openide.util.RequestProcessor.Item item)
          Place the Task to the queue of pending tasks for immediate processing.
static RequestProcessor getDefault()
          The getter for the shared instance of the RequestProcessor.
 boolean isRequestProcessorThread()
          Tests if the current thread is request processor thread.
(package private) static java.util.logging.Logger logger()
          Logger for the error manager.
 RequestProcessor.Task post(java.lang.Runnable run)
          This methods asks the request processor to start given runnable immediately.
 RequestProcessor.Task post(java.lang.Runnable run, int timeToWait)
          This methods asks the request processor to start given runnable after timeToWait milliseconds.
 RequestProcessor.Task post(java.lang.Runnable run, int timeToWait, int priority)
          This methods asks the request processor to start given runnable after timeToWait milliseconds.
static RequestProcessor.Task postRequest(java.lang.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(java.lang.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(java.lang.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.
 void stop()
          Stops processing of runnables processor.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SLOW

static final boolean SLOW

name

java.lang.String name
The name of the RequestProcessor instance


stopped

boolean stopped
If the RP was stopped, this variable will be set, every new post() will throw an exception and no task will be processed any further

Constructor Detail

RequestProcessor

public RequestProcessor()
Creates new RequestProcessor with automatically assigned unique name.


RequestProcessor

public RequestProcessor(java.lang.String name)
Creates a new named RequestProcessor with throughput 1.

Parameters:
name - the name to use for the request processor thread

RequestProcessor

public RequestProcessor(java.lang.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(java.lang.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
Method Detail

getDefault

public static RequestProcessor getDefault()
The getter for the shared instance of the RequestProcessor. This instance is shared by anybody who needs a way of performing sporadic or repeated asynchronous work. 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(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(String, int, boolean), RequestProcessor.Task.cancel()

post

public RequestProcessor.Task post(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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 immediatelly 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

logger

static java.util.logging.Logger logger()
Logger for the error manager.


enqueue

void enqueue(org.openide.util.RequestProcessor.Item item)
Place the Task to the queue of pending tasks for immediate processing. If there is no other Task planned, this task is immediatelly processed in the Processor.


askForWork

RequestProcessor.Task askForWork(org.openide.util.RequestProcessor.Processor worker,
                                 java.lang.String debug)