Overview | Package | Class | Use | Tree | Serialized | Deprecated | Index | Help
| ABLE 2.3.0 07/13/2005 14:21:00
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

When timer event processing is enabled and the timer pops, the timer pop is handled first, and then the asynchronous event queue is handled. All events that are on the queue are handled (including those that arrive while handling other events), with "pseudo" timer pops occurring as necessary. When resetting the timer, the amount of time it takes to handle both timer and asynchronous events are tracked so that the timer interval is kept as accurate as possible.

For example, if the timer pops when it is scheduled to pop every 1000 milliseconds, and it takes 200 milliseconds to handle the timer event (and there are no events waiting on the queue), the next timer event is scheduled in 800 milliseconds.

For another example, if the timer is scheduled to pop every 1000 milliseconds and an incoming asynchronous event arrives after the timer has been sleeping for only 300 milliseconds, and it takes 100 milliseconds to handle the incoming event, the next timer event is scheduled in 600 milliseconds.

Note that if handling a timer or an asynchronous event takes longer than the configured timer interval, timer events may be missed, but the timer will be scheduled for whatever remains of a full interval after processing an immediate "pseudo" timer event. For example, if the timer is scheduled to pop every 1000 milliseconds, but it takes 5700 milliseconds to handle an asynchronous event, some timer pops will have been missed, but one will occur immediately.

Note that it is possible to change the configured timer interval while handling a timer event. This will have the desired effect, and can be used to create "random" timer events. Note too, that the timer interval can be changed by other threads. This will not have any effect until the timer pops or an incoming event interrupts the sleep.

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)
                      throws java.lang.IllegalArgumentException

  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.

    A value of zero or less is not valid and causes an IllegalArgumentException.

  Throws:
    `java.lang.IllegalArgumentException` - When the specified sleep time is zero or less.

### 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):

  - The thread can sleep and wake up at specific intervals, calling the containing event listener's processTimerEvent() method each time the timer expires.
  - The thread can sleep and wake up any time an asynchronous event is placed on this object's internal event queue, calling the containing event listener's processAbleEvent() method.

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

Overview | Package | Class | Use | Tree | Serialized | Deprecated | Index | Help
| ABLE 2.3.0 07/13/2005 14:21:00
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

(C) Copyright IBM Corporation 1999, 2005