Package rife.engine

Interface SiteResponseListener


public interface SiteResponseListener
Receives the response of a SiteRunner while it's being written.

committed(rife.engine.SiteResponse) is called once, when the status and the headers are final, before any content. The content then follows in calls to content(byte[], int, int). Like a servlet container, the site runner collects what the site writes until it flushes it or until there's 32 KB of it. The response is however committed as soon as content is written to its output stream, like with a container that has no buffer, so the status and the headers have to be set before that. The response ends with completed(), failed(java.lang.Throwable) or cancelled(). Exactly one of them is called, and no other call comes after it, so that's where you can let go of what you set up for the response. A failure can also come before the response was committed.

The response of a detached event stream ends when its connection is closed, which is after SiteRunner.handle(String, SiteRequest, SiteResponseListener) returned, and its calls come from the threads that send the events.

Once the request is cancelled, no new call will start. A call that was already under way on another thread still finishes, and cancelled() is called once it did, so if what you pass the content to doesn't accept calls after it was stopped, you have to guard against that yourself until then.

When committed(rife.engine.SiteResponse) or content(byte[], int, int) throws an exception, the response ends like it does when the request is cancelled.

Since:
1.11.0
See Also:
  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    Called when the response ended because its request was cancelled, once no other call of this listener is under way anymore.
    void
    Called when the response is committed, which means that its status and its headers are final.
    void
    Called when the response has ended normally.
    void
    content(byte[] bytes, int offset, int length)
    Called with a part of the content of the response.
    void
    failed(Throwable exception)
    Called when the response ended with a failure.
  • Method Details

    • committed

      void committed(SiteResponse response)
      Called when the response is committed, which means that its status and its headers are final.
      Parameters:
      response - the response, which provides its status through SiteResponse.getStatus(), its headers through SiteResponse.getHttpHeaders(), and whether it was handled through SiteResponse.isHandled()
      Since:
      1.11.0
    • content

      void content(byte[] bytes, int offset, int length)
      Called with a part of the content of the response. The bytes are only valid during the call, so you have to copy them if you need them afterwards.
      Parameters:
      bytes - the buffer with the content
      offset - where the content starts in the buffer
      length - how many bytes of content there are
      Since:
      1.11.0
    • completed

      void completed()
      Called when the response has ended normally.
      Since:
      1.11.0
    • failed

      void failed(Throwable exception)
      Called when the response ended with a failure.
      Parameters:
      exception - the cause of the failure
      Since:
      1.11.0
    • cancelled

      default void cancelled()
      Called when the response ended because its request was cancelled, once no other call of this listener is under way anymore. This can happen on the thread that cancelled the request, or on the one of the call that was still under way.

      This does nothing by default.

      Since:
      1.11.0