EventThread (eBus Utilities 5.3.1 API)

java.lang.Object
- java.lang.Thread
- - net.sf.eBus.util.EventThread

All Implemented Interfaces:

Runnable
```
public abstract class EventThread
extends Thread
```
A Java thread with a run() method that iterates over a Java BlockingQueue, processing each event in the same order as posted. The event thread has three general states:
1. Starting: The subclass' starting() method is called to perform the actual initialization. If this method returns true, the thread moves to the next state. If false is returned or this method throws an exception, the event thread stops running.
2. Running: The thread continues taking enqueued events and passing them to the the subclass' handleEvent(Object) method. This continues until the thread is halted. If haltNow(boolean) is called, all enqueued events are discarded and the event thread immediately goes to the next state. If halt(boolean) is called, a special halt event is enqueued. The event thread continues processing events until the halt event is reached. The event thread then goes to the next state. In either case, after the event thread is halted, no more events may be enqueued.
3. Stopping: The event thread concludes its run by calling the subclass' stopping() method. The subclass performs the necessary clean up before the event thread stops running.
This class is thread safe. There is no need to externally synchronize an event thread before calling any of its methods.
The event thread supports only a First In, First Out (FIFO) blocking queue with configurable capacity. There is no support for a priority blocking queue.
Author:

Charles Rapp

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`EventThread.RunState` An `EventThread` has seven distinct states: `NOT_STARTED`: The `EventThread` was instantiated but not yet started.

Nested classes/interfaces inherited from class java.lang.Thread
Thread.State, Thread.UncaughtExceptionHandler

Field Summary
- Fields inherited from class java.lang.Thread
  MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`EventThread()` Constructs an `EventThread` with a capacity of `Integer.MAX_VALUE`.
`protected`	`EventThread(int capacity)` Constructs a `EventThread` with a specified event queue capacity.
`protected`	`EventThread(String name)` Constructs an `EventThread` with a specified thread name and a default capacity of `Integer.MAX_VALUE`.
`protected`	`EventThread(String name, int capacity)` Constructs an `EventThread` with a specified name and queue capacity.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`add(Object event)` Appends an event to the queue.
`void`	`halt(boolean waitFlag)` Permanently stops this thread's execution after the event queue is empty.
`void`	`haltNow(boolean waitFlag)` Permanently stops this thread's execution now.
`abstract void`	`handleEvent(Object event)` Processes the next enqueued event.
`boolean`	`isHalted()` Returns `true` if this event thread has been halted and `false` otherwise.
`void`	`run()` The main `Thread` routine.
`EventThread.RunState`	`runstate()` Returns this event thread current `state`.
`void`	`start(boolean waitFlag)` Starts the thread execution.
`abstract boolean`	`starting()` Returns `true` if the `EventThread` subclass initializes successfully and `false` otherwise.
`abstract void`	`stopping()` Performs any necessary local clean up when the thread halts.

Methods inherited from class java.lang.Thread
activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - EventThread
```
protected EventThread()
```
    Constructs an EventThread with a capacity of Integer.MAX_VALUE. The thread name is set to "EventThread_n" where n is an arbitrary number.
  - EventThread
```
protected EventThread(String name)
```
    Constructs an EventThread with a specified thread name and a default capacity of Integer.MAX_VALUE.
    
    Parameters:
    
    name - Thread name.
  - EventThread
```
protected EventThread(int capacity)
```
    Constructs a EventThread with a specified event queue capacity. The thread name is set to "EventThread_n" where n is an arbitrary number.
    
    Parameters:
    
    capacity - Event queue capacity.
    
    Throws:
    
    IllegalArgumentException - if capacity is <= zero.
  - EventThread
```
protected EventThread(String name,
                      int capacity)
```
    Constructs an EventThread with a specified name and queue capacity.
    
    Parameters:
    
    name - Thread name.
    
    capacity - Event queue capacity.
    
    Throws:
    
    IllegalArgumentException - if capacity is <= zero.
- Method Detail
  - isHalted
```
public final boolean isHalted()
```
    Returns true if this event thread has been halted and false otherwise. It is possible for this method to return true yet still receive calls to handleEvent(Object). This will happen when halt(boolean) is called, the event queue is not empty and so the thread is still processing events.
    Use runstate() for finer-grained determination of the event thread's current state.
    Call haltNow(boolean) to stop the event thread immediately despite the presence of unprocessed events.
    
    Returns:
    
    true if this event thread has been halted and false otherwise.
    
    See Also:
    
    halt(boolean), haltNow(boolean), runstate()
  - runstate
```
public final EventThread.RunState runstate()
```
    Returns this event thread current state.
    
    Returns:
    
    this event thread current state.
    
    See Also:
    
    isHalted()
  - run
```
public final void run()
```
    The main Thread routine.
    Do not call this method directly. Instead, call the start method.
    
    Specified by:
    
    run in interface Runnable
    
    Overrides:
    
    run in class Thread
  - handleEvent
```
public abstract void handleEvent(Object event)
```
    Processes the next enqueued event.
    
    Parameters:
    
    event - the next event.
  - starting
```
public abstract boolean starting()
```
    Returns true if the EventThread subclass initializes successfully and false otherwise. If false is returned or throws an exception, then this event thread immediately halts.
    
    Returns:
    
    true if the EventThread subclass initializes successfully and false otherwise.
  - stopping
```
public abstract void stopping()
```
    Performs any necessary local clean up when the thread halts.
  - start
```
public final void start(boolean waitFlag)
                 throws IllegalStateException
```
    Starts the thread execution. If waitFlag is true, then waits for this thread to begin execution before return; otherwise returns immediately.
    Note: waiting for this event thread to start does not imply this thread is running, only that its starting() method has completed. If starting() returns false, then this thread will immediately terminate. Call runstate() to determine if this thread is running.
    
    Parameters:
    
    waitFlag - if true, then wait for the event thread to start before returning; otherwise return immediately.
    
    Throws:
    
    IllegalStateException - if this thread was previously started.
  - add
```
public final void add(Object event)
               throws IllegalArgumentException,
                      IllegalStateException
```
    Appends an event to the queue. If the queue's capacity is full, this method will wait until the event can be enqueued.
    
    Parameters:
    
    event - append this event to the queue.
    
    Throws:
    
    IllegalArgumentException - if event is null.
    
    IllegalStateException - if this event thread is halted.
  - halt
```
public final void halt(boolean waitFlag)
```
    Permanently stops this thread's execution after the event queue is empty. Subsequent calls to add(Object) and java.lang.IllegalStateException.
    If waitFlag is true, then this method blocks until this event thread has finished processing all extant events and is halted.
    Does nothing if this thread was previously halted and returns immediately.
    
    Parameters:
    
    waitFlag - if true, then wait for the event thread to halt before returning; otherwise return immediately.
  - haltNow
```
public final void haltNow(boolean waitFlag)
```
    Permanently stops this thread's execution now. All events currently equeued and not yet processed are cleared from the queue and will not be processed. Subsequent calls to add(Object) and java.lang.IllegalStateException.
    If waitFlag is true, then this method blocks until this event thread is halted.
    Does nothing if this thread was previously halted and returns immediately.
    
    Parameters:
    
    waitFlag - if true, then wait for the event thread to halt before returning; otherwise return immediately.

Class EventThread

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread

Field Summary

Fields inherited from class java.lang.Thread

Constructor Summary

Method Summary

Methods inherited from class java.lang.Thread

Methods inherited from class java.lang.Object

Constructor Detail

EventThread

EventThread

EventThread

EventThread

Method Detail

isHalted

runstate

run

handleEvent

starting

stopping

start

add

halt

haltNow