Package com.yahoo.jdisc.handler

Interface ContentChannel

All Known Implementing Classes:
BufferedContentChannel, NonWorkingContentChannel, NullContent, ReadableContentChannel
public interface ContentChannel
This interface defines a callback for asynchronously writing the content of a Request or a Response to a recipient. It is the returned both by RequestHandler.handleRequest(Request, ResponseHandler) and ResponseHandler.handleResponse(Response). Note that methods of this channel only schedule the appropriate action - if you need to act on the result you will need submit a CompletionHandler to the appropriate method.

Because a ContentChannel might have a different lifespan than the originating Request and Response objects, all instances of this interface are internally backed by a reference to the Container that was active when the initial Request was created. This ensures that the configured environment of the ContentChannel is stable throughout its lifetime. This also means that the close(CompletionHandler) method MUST be called in order to release that reference. Failure to do so will prevent the Container from ever shutting down. This requirement is regardless of any errors that may occur while calling any of its other methods or its derived CompletionHandlers.

Author:
Simon Thoresen Hult

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close(CompletionHandler handler)
    Closes this ContentChannel.
    default void
    onError(Throwable error)
    Invoked when an error occurs during processing of request content.
    void
    write(ByteBuffer buf, CompletionHandler handler)
    Schedules the given ByteBuffer to be written to the content corresponding to this ContentChannel.

  • Method Details

    • write

      void write(ByteBuffer buf, CompletionHandler handler)
      Schedules the given ByteBuffer to be written to the content corresponding to this ContentChannel. This call transfers ownership of the given ByteBuffer to this ContentChannel, i.e. no further calls can be made to the buffer. The execution of writes happen in the same order as this method was invoked.
      Parameters:
      buf - The ByteBuffer to schedule for write. No further calls can be made to this buffer.
      handler - The CompletionHandler to call after the write has been executed.

    • close

      void close(CompletionHandler handler)
      Closes this ContentChannel. After a channel is closed, any further attempt to invoke write(ByteBuffer, CompletionHandler) upon it will cause an IllegalStateException to be thrown. If this channel is already closed then invoking this method has no effect, but CompletionHandler.completed() will still be called. Notice that you MUST call this method, regardless of any exceptions that might have occurred while writing to this ContentChannel. Failure to do so will prevent the Container from ever shutting down.
      Parameters:
      handler - The CompletionHandler to call after the close has been executed.

    • onError

      default void onError(Throwable error)
      Invoked when an error occurs during processing of request content. Signals that the caller was unable to write all data to this ContentChannel. This method can be invoked at any time after the content channel is created, but it's never invoked after close(CompletionHandler). close(CompletionHandler) will be invoked immediately after this method returning (no intermediate calls to #write(ByteBuffer, CompletionHandler)).