Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.openide.util 6.8.22
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.openide.util
Class RequestProcessor

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

    public final class RequestProcessor

extends 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:

- Having something done asynchronously in some other thread, not insisting on any kind of serialization of the requests: Use `RequestProcessor.`getDefault()`.`post(runnable)`` for this purpose.
- Having something done later in some other thread: Use `RequestProcessor.`getDefault()`.`post(runnable, delay)``
- Having something done periodically in any thread: Use the `RequestProcessor.Task`'s ability to `schedule()`, like

            static RequestProcessor.Task CLEANER = RequestProcessor.getDefault().post(runnable,DELAY);
            public void run() {
                doTheWork();
                CLEANER.schedule(DELAY);
            }

  Note: Please think twice before implementing some periodic background activity. It is generally considered evil if it will run regardless of user actions and the IDE state, even while the application is minimized / not currently used.
- Having something done in some other thread but properly ordered: Create a private instance of the `RequestProcessor(name)` and use it from all places you'd like to have serialized. It works like a simple Mutex.
- Having some entity that will do processing in a limited number of threads paralelly: Create a private instance of the `RequestProcessor(name,throughput)` set proper throughput and use it to schedule the work. It works like a queue of requests passing through a semafore with predefined number of `DOWN()`s.

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), the IDE 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;
         }
     }

Nested Class Summary
`class` | `RequestProcessor.Task` The task describing the request sent to the processor.

Constructor Summary
`RequestProcessor()` Creates new RequestProcessor with automatically assigned unique name.
`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.

Method Summary
`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.
`static RequestProcessor` | `getDefault()` The getter for the shared instance of the `RequestProcessor`.
`boolean` | `isRequestProcessorThread()` Tests if the current thread is request processor thread.
`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.
`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`

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(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

Method Detail

### getDefault

    public static RequestProcessor getDefault()

  The getter for the shared instance of the `RequestProcessor`.

  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. This instance is shared by anybody who needs a way of performing sporadic or repeated asynchronous work.
  Since:
    OpenAPI version 2.12

### 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 `waitFinished` on the task will succeeded immediatelly even the task has not yet been `Task.schedule`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

    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

    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

    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

    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 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.openide.util 6.8.22
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Built on December 7 2006. | Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.