public class AsyncStateMachine<S>
extends Object

Manages the state transitions for async requests.

 The internal states that are used are:
 DISPATCHED       - Standard request. Not in Async mode.
 STARTING         - ServletRequest.startAsync() has been called from
                    Servlet.service() but service() has not exited.
 STARTED          - ServletRequest.startAsync() has been called from
                    Servlet.service() and service() has exited.
 MUST_COMPLETE    - ServletRequest.startAsync() followed by complete() have
                    been called during a single Servlet.service() method. The
                    complete() will be processed as soon as Servlet.service()
                    exits.
 COMPLETE_PENDING - ServletRequest.startAsync() has been called from
                    Servlet.service() but, before service() exited, complete()
                    was called from another thread. The complete() will
                    be processed as soon as Servlet.service() exits.
 COMPLETING       - The call to complete() was made once the request was in
                    the STARTED state.
 TIMING_OUT       - The async request has timed out and is waiting for a call
                    to complete() or dispatch(). If that isn't made, the error
                    state will be entered.
 MUST_DISPATCH    - ServletRequest.startAsync() followed by dispatch() have
                    been called during a single Servlet.service() method. The
                    dispatch() will be processed as soon as Servlet.service()
                    exits.
 DISPATCH_PENDING - ServletRequest.startAsync() has been called from
                    Servlet.service() but, before service() exited, dispatch()
                    was called from another thread. The dispatch() will
                    be processed as soon as Servlet.service() exits.
 DISPATCHING      - The dispatch is being processed.
 MUST_ERROR       - ServletRequest.startAsync() has been called from
                    Servlet.service() but, before service() exited, an I/O
                    error occurred on another thread. The container will
                    perform the necessary error handling when
                    Servlet.service() exits.
 ERROR            - Something went wrong.


 The valid state transitions are:

                  post()                                        dispatched()
    |-------»------------------»---------|    |-------«-----------------------«-----|
    |                                    |    |                                     |
    |                                    |    |        post()                       |
    |               post()              \|/  \|/       dispatched()                 |
    |           |-----»----------------»DISPATCHED«-------------«-------------|     |
    |           |                          | /|\ |                            |     |
    |           |              startAsync()|  |--|timeout()                   |     |
    ^           |                          |                                  |     |
    |           |        complete()        |                  dispatch()      ^     |
    |           |   |--«---------------«-- | ---«--MUST_ERROR--»-----|        |     |
    |           |   |                      |         /|\             |        |     |
    |           ^   |                      |          |              |        |     |
    |           |   |                      |    /-----|error()       |        |     |
    |           |   |                      |   /                     |        ^     |
    |           |  \|/  ST-complete()     \|/ /   ST-dispatch()     \|/       |     |
    |    MUST_COMPLETE«--------«--------STARTING--------»---------»MUST_DISPATCH    |
    |                                    / | \                                      |
    |                                   /  |  \                                     |
    |                    OT-complete() /   |   \    OT-dispatch()                   |
    |   COMPLETE_PENDING«------«------/    |    \-------»---------»DISPATCH_PENDING |
    |          |                           |                           |            |
    |    post()|   timeout()         post()|   post()            post()|  timeout() |
    |          |   |--|                    |  |--|                     |    |--|    |
    |         \|/ \|/ |   complete()      \|/\|/ |   dispatch()       \|/  \|/ |    |
    |--«-----COMPLETING«--------«----------STARTED--------»---------»DISPATCHING----|
            /|\  /|\                       |                             /|\ /|\
             |    |                        |                              |   |
             |    |               timeout()|                              |   |
             |    |                        |                              |   |
             |    |                        |                              |   |
             |    |                        |                              |   |
             |    |                        |                              |   |
             |    |                        |                              |   |
             |    |                        |                              |   |
             |    |                        |                              |   |
             |    |                        |                              |   |
             |    |       complete()      \|/         dispatch()          |   |
             |    |------------«-------TIMING_OUT--------»----------------|   |
             |                                                                |
             |            complete()                     dispatch()           |
             |---------------«-----------ERROR--------------»-----------------|


 Notes: * For clarity, the transitions to ERROR which are valid from every state apart from
          STARTING are not shown.
        * All transitions may happen on either the Servlet.service() thread (ST) or on any
          other thread (OT) unless explicitly marked.