Package com.github.ambry.rest

Interface RestResponseChannel

  • All Superinterfaces:
    AsyncWritableChannel, java.lang.AutoCloseable, java.nio.channels.Channel, java.io.Closeable
    public interface RestResponseChannel
extends AsyncWritableChannel
    The RestResponseChannel is meant to provide a NioServer implementation independent way to return responses to the client. It deals with data in terms of bytes only and is not concerned with different types of data that might need to be returned from the RestRequestService.

    This functionality is mostly required by implementations of RestRequestService since they are agnostic to both the REST protocol being used and the framework used for the implementation of NioServer.

    Typically, the RestResponseChannel wraps the underlying network channel and the APIs of the NIO framework to return responses to clients.

    Implementations are expected to be thread-safe but use with care across different threads since there are neither ordering guarantees nor operation success guarantees (e.g. if an external thread closes the channel while a write attempt is in progress) - especially with concurrent writes.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void close()
      Closes the underlying network channel immediately.
      java.lang.Object getHeader​(java.lang.String headerName)
      Gets the current value of the header with headerName.
      ResponseStatus getStatus()
      Gets the current ResponseStatus.
      void onResponseComplete​(java.lang.Exception exception)
      Notifies that response handling for the request is complete (whether the request succeeded or not) and tasks that need to be done after handling of a response is complete can proceed (e.g.
      void setHeader​(java.lang.String headerName, java.lang.Object headerValue)
      Sets header headerName to headerValue.
      void setStatus​(ResponseStatus status)
      Sets the response status.
      java.util.concurrent.Future<java.lang.Long> write​(java.nio.ByteBuffer src, Callback<java.lang.Long> callback)
      Adds a sequence of bytes to the body of the response.

      • Methods inherited from interface java.nio.channels.Channel

        isOpen

    • Method Detail

      • write

        java.util.concurrent.Future<java.lang.Long> write​(java.nio.ByteBuffer src,
                                                  Callback<java.lang.Long> callback)
        Adds a sequence of bytes to the body of the response.

        If any write fails, all subsequent writes will fail. The data in src will be eventually written to the channel and the callback will be invoked once the write succeeds/fails. The callback and the future returned will contain the bytes written (that should be equal to src.remaining() at the time of invocation if there were no exceptions) on success or failure. If the write failed, they will also contain the exception that caused the failure.

        Every single write is guaranteed to be acknowledged as either succeeded or failed even if the channel is closed. Further, writes will be acknowledged in the same order that they were received.

        src can be reused only after the callback is invoked (or after future.get() returns).

        Concurrent write calls may result in unexpected behavior.

        Specified by:
        write in interface AsyncWritableChannel
        Parameters:
        src - the data that needs to be written to the channel.
        callback - the Callback that will be invoked once the write succeeds/fails. This can be null.
        Returns:
        a Future that will eventually contain the result of the write operation.

      • close

        void close()
    throws java.io.IOException
        Closes the underlying network channel immediately. This should be used only if there is an error and the channel needs to be closed immediately.

        Typically onResponseComplete(Exception) will take care of closing the channel if required. It will handle keep-alive headers and close the channel gracefully as opposed to this function which will simply close the channel abruptly.

        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.nio.channels.Channel
        Specified by:
        close in interface java.io.Closeable
        Throws:
        java.io.IOException - if there was a problem closing the channel.

      • onResponseComplete

        void onResponseComplete​(java.lang.Exception exception)
        Notifies that response handling for the request is complete (whether the request succeeded or not) and tasks that need to be done after handling of a response is complete can proceed (e.g. cleanup code + closing of connection if not keepalive).

        If exception is not null, then it indicates that there was an error while handling the request and exception defines the error that occurred. The expectation is that an appropriate error response will be constructed, returned to the client if possible and the connection closed (if required).

        It is possible that the connection might be closed/severed before this is called. Therefore this function needs to always check if the channel of communication with the client is still open if it wants to send data.

        A response is considered to be complete either when a complete response has been sent to the client, an exception occurred while handling the request or if the client timed out (or there was any other client side error).

        A response of OK is returned if exception is null and no response body was constructed (i.e if there were no write(ByteBuffer, Callback) calls).

        This is (has to be) called regardless of the request being concluded successfully or unsuccessfully (e.g. connection interruption).

        This operation is idempotent.

        Parameters:
        exception - if an error occurred, the cause of the error. Otherwise null.

      • setHeader

        void setHeader​(java.lang.String headerName,
               java.lang.Object headerValue)
        Sets header headerName to headerValue.
        Parameters:
        headerName - the name of the header to set to headerValue.
        headerValue - the value of the header with name headerName.

      • getHeader

        java.lang.Object getHeader​(java.lang.String headerName)
        Gets the current value of the header with headerName.
        Parameters:
        headerName - the name of the header whose value is required.
        Returns:
        the value of the header with name headerName if it exists. null otherwise.