ABLE 2.0.0 07/02/2003 10:25:01

com.ibm.able
Class AbleEventQueue

java.lang.Object
  |
  +--com.ibm.able.AbleEventQueue
All Implemented Interfaces:
java.lang.Runnable, java.io.Serializable

public class AbleEventQueue
extends java.lang.Object
implements java.lang.Runnable, java.io.Serializable

The AbleEventQueue allows events added to this queue to be processed on the caller's thread, or on a separate thread controlled by the event queue itself. The queue can also be used for timed event processing. The asynchronous thread of control allows containing AbleEventListener objects to:

  1. Receive and process asynchronous ABLE events while doing other work. Sequencing of events is enforced.
  2. Perform asynchronous special processing at regular, timed intervals.
  3. Do any combination of the above.
This class in intended to be used by all AbleEventListeners to support the handleAbleEvent() method.

See Also:
Serialized Form

Constructor Summary
AbleEventQueue(AbleEventQueueProcessor theContainingEventProcessor)
          Create a new AbleEventQueue.
 
Method Summary
 void flushEvents()
          Removes all events from the event queue.
 int getAbleEventProcessingEnabled()
          Returns whether asynchronous ABLE event processing is enabled or disabled.
 AbleEvent getEvent()
          Remove and return the very next event waiting on the queue.
 long getSleepTime()
          Returns the current sleep time setting.
 boolean isAbleEventPostingEnabled()
          Indicates whether asynchronous ABLE event posting is enabled or disabled.
 boolean isAbleEventProcessingEnabled()
          Indicates whether asynchronous ABLE event processing is enabled or disabled.
 boolean isTimerEventProcessingEnabled()
          Indicates whether automatic periodic processing is enabled or disabled.
 AbleEvent peekEvent()
          Return the very next event waiting on the queue, but leave that event on the queue for further processing.
 void postEvent(AbleEvent theEvent)
          Place an event on the queue for future processing, but only if event posting is enabled.
 void resumeProcessingEvents()
          Resume the "suspended" asynchronous thread of control.
 void run()
          Called indirectly by startProcessingEvents() when myEventHandlerThread.start() is invoked within that method.
 void setAbleEventProcessingEnabled(int theEnabledFlag)
          Specify whether asynchronous ABLE event processing is enabled or disabled.
 void setSleepTime(long theSleepTime)
          Set the sleep time for the thread's processing loop.
 void setTimerEventProcessingEnabled(boolean theEnabledFlag)
          Specify whether automatic periodic processing is enabled or disabled.
 int size()
          Returns the number of events on the event queue.
 void startProcessingEvents()
          Starts the asynchronous thread of control.
 void stopProcessingEvents()
          Stops the asynchronous thread of control.
 void suspendProcessingEvents()
          Temporarily suspend the asynchronous thread of control.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AbleEventQueue

public AbleEventQueue(AbleEventQueueProcessor theContainingEventProcessor)
Create a new AbleEventQueue.

A reference to the enclosing container is saved so that we can call back to it when new events arrive or the timer expires.

Users must call startProcessingEvents() to create a separate thread which continuously listens for new events to arrive on the queue and/or processes timer expirations. Processing can be suspended and resumed by using suspendProcessingEvents() and resumeProcessingEvents() respectively. The thread can be gracefully killed by calling stopProcessingEvents().

Parameters:
theContainingEventProcessor - An AbleEventQueueProcessor object that will process timer and asynchronous Able events. This parameter must never be null.

Method Detail

run

public void run()
Called indirectly by startProcessingEvents() when myEventHandlerThread.start() is invoked within that method.
Specified by:
run in interface java.lang.Runnable

setSleepTime

public void setSleepTime(long theSleepTime)
Set the sleep time for the thread's processing loop.

If the thread is sleeping when this method is called, the changed sleep time value will not take effect until the timer expires and the thread goes back to sleep.

Parameters:
theSleepTime - The number of milliseconds for which the thread is to sleep before it awakes and calls the containing event listener's processTimerEvent() method.

getSleepTime

public long getSleepTime()
Returns the current sleep time setting.
Returns:
The current sleep time, in milliseconds.

setTimerEventProcessingEnabled

public void setTimerEventProcessingEnabled(boolean theEnabledFlag)
Specify whether automatic periodic processing is enabled or disabled. When enabled and the thread is started, the thread will awaken at periodic intervals as specified in the "sleep time" variable, and call the containing event listener's processTimerEvent() method.

This method can be used before the asynchronous thread of control is started in order to set the thread loop's initial behavior; the method can also be used while the thread is running to start and stop the behavior.

Parameters:
theEnabledFlag - Specify true if the thread is to awaken every N milliseconds and call the containing event listener's processTimerEvent() method; specify false if no automatic periodic processing is to take place while the thread is running.

See Also:
setSleepTime(long), startProcessingEvents()

isTimerEventProcessingEnabled

public boolean isTimerEventProcessingEnabled()
Indicates whether automatic periodic processing is enabled or disabled.
Returns:
true if the thread will awaken every N milliseconds and call the containing event listener's processTimerEvent() method; false otherwise.

setAbleEventProcessingEnabled

public void setAbleEventProcessingEnabled(int theEnabledFlag)
                                   throws java.lang.IllegalArgumentException
Specify whether asynchronous ABLE event processing is enabled or disabled. When enabled and the asynchronous thread of control is started, the thread will awaken whenever an asynchronous event is placed on our internal event queue and call the containing event listener's processAbleEvent() method.

This method can be used before the asynchronous thread of control is started in order to set the thread's initial behavior; the method can also be used while the thread is running to start and stop the behavior.

Parameters:
theEnabledFlag - Specify one of the following values:
Able.ProcessingEnabled_PostingEnabled
Able events are taken from the event queue in FIFO order and processed; other objects may add additional events to the event queue. The queue grows and shrinks as events come in and are processed.
Able.ProcessingEnabled_PostingDisabled
Able events are taken from the event queue in FIFO order and processed; other objects may not add new events to the event queue. The queue shrinks until it is empty.
Able.ProcessingDisabled_PostingEnabled
Able events on the event queue remain there, unprocessed; other objects may add additional events to the event queue; the queue grows.
Able.ProcessingDisabled_PostingDisabled
Able events on the event queue remain there, unprocessed; other objects may not add new events to the event queue. The queue neither shrinks nor grows.
Throws:
java.lang.IllegalArgumentException - If the parameter is not a valid value.
See Also:
startProcessingEvents()

getAbleEventProcessingEnabled

public int getAbleEventProcessingEnabled()
Returns whether asynchronous ABLE event processing is enabled or disabled.
Returns:
One of the following values:
Able.ProcessingEnabled_PostingEnabled
Able events are taken from the event queue in FIFO order and processed; other objects may add additional events to the event queue. The queue grows and shrinks as events come in and are processed.
Able.ProcessingEnabled_PostingDisabled
Able events are taken from the event queue in FIFO order and processed; other objects may not add new events to the event queue. The queue shrinks until it is empty.
Able.ProcessingDisabled_PostingEnabled
Able events on the event queue remain there, unprocessed; other objects may add additional events to the event queue; the queue grows.
Able.ProcessingDisabled_PostingDisabled
Able events on the event queue remain there, unprocessed; other objects may not add new events to the event queue. The queue neither shrinks nor grows.

isAbleEventPostingEnabled

public boolean isAbleEventPostingEnabled()
Indicates whether asynchronous ABLE event posting is enabled or disabled.
Returns:
true if Able events are permitted to be placed on the event queue; false otherwise.

isAbleEventProcessingEnabled

public boolean isAbleEventProcessingEnabled()
Indicates whether asynchronous ABLE event processing is enabled or disabled.
Returns:
true if Able events are permitted to be taken off of the event queue and processed; false otherwise.

flushEvents

public void flushEvents()
Removes all events from the event queue.

Note that unless event Posting is disabled before clearing the event queue, new events may arrive on the queue as soon as it has been cleared!


size

public int size()
Returns the number of events on the event queue.

Note that unless both event Posting and event Processing are disabled, the number may be invalid as soon as it is returned.

Returns:
The number of events on the queue.

startProcessingEvents

public void startProcessingEvents()
Starts the asynchronous thread of control.

In this thread, one, two, or no actions can occur, depending on what is enabled (see the related method links):

If the thread is already running, this method is a no-op.

See Also:
setTimerEventProcessingEnabled(boolean), setAbleEventProcessingEnabled(int), stopProcessingEvents(), run()

stopProcessingEvents

public void stopProcessingEvents()
Stops the asynchronous thread of control. Note that this means that the thread's run() method will exit gracefully. This method must be called synchronously; it cannot be called from the asynchronous thread itself.

Timer event processing and ABLE event processing cease, but if event posting is still enabled, events may still be placed on the internal event queue by other processes. However, events currently on the queue at the time the thread is stopped are flushed! Events placed on the queue after the thread is stopped and the queue is flushed will not be processed until a new thread is started.

If no thread is running, this method is a no-op.

See Also:
startProcessingEvents()

suspendProcessingEvents

public void suspendProcessingEvents()
Temporarily suspend the asynchronous thread of control. Note that what this really means is that the thread goes into a long wait state that can only be interrupted by some external thread calling resumeProcessingEvents().

Timer event processing and ABLE event processing cease, but if event Posting is still enabled, events may still be placed on the internal event queue by other processes.

Because the thread may be doing some work at the time this method is called, it may take some time before the thread actually achieves a suspended state. This method will not return until AbleState.Suspended is achieved.

This method must be called synchronously; it cannot be called from the asynchronous thread itself.

If no thread is running, this method is a no-op.

If the thread is already suspended, this method is a no-op.

See Also:
resumeProcessingEvents(), run()

resumeProcessingEvents

public void resumeProcessingEvents()
Resume the "suspended" asynchronous thread of control.

Timer event processing and ABLE event processing resume if these actions are enabled.

If no thread is running, this method is a no-op.

If the thread is not suspended, this method is a no-op.

See Also:
suspendProcessingEvents(), run()

postEvent

public void postEvent(AbleEvent theEvent)
Place an event on the queue for future processing, but only if event posting is enabled. Any thread that is in a wait state waiting for ABLE events to arrive is awakened, but only if event processing is enabled. If event posting is not enabled, the event is completely ignored.

Note that the caller must have the monitor before calling this method; for example, synchronized (eventQueue) {eventQueue.postEvent(someAbleEvent);}

Parameters:
theEvent - The event to be processed at some future time.

Throws:
MonitorStateException - if the caller does not have the monitor for this event queue as explained above.
See Also:
getEvent(), peekEvent()

getEvent

public AbleEvent getEvent()
Remove and return the very next event waiting on the queue.
Returns:
The next event waiting on the queue, or null if no event is waiting on the queue.
See Also:
postEvent(AbleEvent), peekEvent()

peekEvent

public AbleEvent peekEvent()
Return the very next event waiting on the queue, but leave that event on the queue for further processing.
Returns:
The next event waiting on the queue, or null if no event is waiting on the queue.
See Also:
getEvent()

ABLE 2.0.0 07/02/2003 10:25:01

(C) Copyright IBM Corporation 1999, 2003