org.apache.river.thread.wakeup

Class WakeupManager

java.lang.Object

org.apache.river.thread.wakeup.WakeupManager

public class WakeupManager
extends Object

A Queue of timed tasks. Each task implements Runnable. Events can either be executed in the queue's thread or in their own thread.

A task is an object that implements Runnable. It is scheduled by invoking schedule with a time at which it should be run. When that time arrives (approximately) the task will be pulled off the queue and have its run method invoked.

A schedule request can specify a WakeupManager.ThreadDesc, which will define the parameters of a thread to be created to run the Runnable. You can specify the group, whether the thread is a daemon thread, and the priority. Additionally you can use a subclass of WakeupManager.ThreadDesc and override the thread method to further customize thread creation.

When a task is scheduled, a WakeupManager.Ticket is returned that can be used to cancel the event if desired.

The queue requires its own thread, whose parameters can be defined via a ThreadDesc if desired. The queue's thread will be started when the first task is scheduled. If the queue becomes empty the thread will be terminated after a configurable delay. The thread will be re-started if a new task is scheduled.

While it is theoretically possible to obtain the queue's thread and interrupt it, the results of doing so are undefined. If a client wishes to stop the queue's thread the client should either remove all the tasks or call stop(). Note, calling stop will cause future schedule calls to fail with an IllegalStateException.

WakeupManager supports the queueThreadTimeout configuration entry, with the component org.apache.river.thread.wakeup.WakeupManager.

•	queueThreadTimeout
	Type:	long
	Default:	30,000 milliseconds
	Description:	How long, in milliseconds, the queue's thread will be left running if there are no scheduled tasks. Must be a non-negative long value. This configuration entry is consulted when the WakeupManager is initially created.

This class uses the Logger named org.apache.river.thread.wakeup.WakeupManager to log information at the following logging levels:

Level	Description
SEVERE	exceptions thrown when we attempt to create the queue's thread
WARNING	exceptions thrown by the run methods of tasks, by the ThreadDesc's of tasks, or if the queue's thread is interrupted
FINEST	how many milliseconds until the next event and when the queue's thread is stopped or started

Author:

Sun Microsystems, Inc.

See Also:

Runnable

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	WakeupManager.ThreadDesc Description of a future thread.
static class	WakeupManager.Ticket A ticket that can be used for cancelling a future task.

Constructor Summary

Constructors

Constructor and Description
WakeupManager() Create a new WakeupManager.
WakeupManager(WakeupManager.ThreadDesc desc) Create a new WakeupManager.
WakeupManager(WakeupManager.ThreadDesc desc, Configuration config) Create a new WakeupManager.

Method Summary

Modifier and Type	Method and Description
void	cancel(WakeupManager.Ticket t) Cancel the given ticket.
void	cancelAll() Cancel all tickets.
boolean	isEmpty() Return whether the queue is currently empty.
protected WakeupManager.Ticket	newTicket(long when, Runnable task, WakeupManager.ThreadDesc threadDesc) Create a new ticket with the specified values for when the task should be run, what task should be run, and what sort of thread the task should be run in.
WakeupManager.Ticket	schedule(long when, Runnable task) Schedule the given task for the given time.
WakeupManager.Ticket	schedule(long when, Runnable task, WakeupManager.ThreadDesc threadDesc) Schedule the given task for the given time, to be run in a thread.
void	stop() Stop executing.

Methods inherited from class java.lang.Object

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

Constructor Detail

WakeupManager

public WakeupManager()

Create a new WakeupManager. Equivalent to.

     WakeupManager(new ThreadDesc())
 

See Also:

WakeupManager.ThreadDesc

WakeupManager

public WakeupManager(WakeupManager.ThreadDesc desc)

Create a new WakeupManager. The thread used for timing will be created according to the provided ThreadDesc.

Throws:

NullPointerException - if desc is null

WakeupManager

public WakeupManager(WakeupManager.ThreadDesc desc,
                     Configuration config)
              throws ConfigurationException

Create a new WakeupManager. The thread used for timing will be created according to the provided ThreadDesc. Optionally pass a configuration to control various implementation specific behaviors.

Throws:

ConfigurationException - if if an exception occurs while retrieving an item from the given Configuration object

NullPointerException - if either argument is null

Method Detail

newTicket

protected WakeupManager.Ticket newTicket(long when,
                                         Runnable task,
                                         WakeupManager.ThreadDesc threadDesc)

Create a new ticket with the specified values for when the task should be run, what task should be run, and what sort of thread the task should be run in.

Parameters:

when - when the task should run, an absolute time

task - what task should be run

threadDesc - if non-null the object to use to create the thread the task should be run in, if null the task should be run in the manager's thread.

Throws:

NullPointerException - if task is null

schedule

public WakeupManager.Ticket schedule(long when,
                                     Runnable task)

Schedule the given task for the given time. The task's run method will be executed synchronously in the queue's own thread, so it should be brief or it will affect whether future events will be executed at an appropriate time.

Throws:

NullPointerException - if task is null

IllegalStateException - if the manager has been stopped

schedule

public WakeupManager.Ticket schedule(long when,
                                     Runnable task,
                                     WakeupManager.ThreadDesc threadDesc)

Schedule the given task for the given time, to be run in a thread. When the time comes, a new thread will be created according to the ThreadDesc object provided. If threadDesc is null, this is equivalent to the other form of schedule.

Throws:

NullPointerException - if task is null

IllegalStateException - if the manager has been stopped

cancel

public void cancel(WakeupManager.Ticket t)

Cancel the given ticket.

cancelAll

public void cancelAll()

Cancel all tickets.

isEmpty

public boolean isEmpty()

Return whether the queue is currently empty.

stop

public void stop()

Stop executing.