core/src/main/java/com/google/net/stubby/ServerCall.java

package com.google.net.stubby;

import com.google.common.util.concurrent.ListenableFuture;

import java.io.InputStream;
import javax.annotation.Nullable;

/**
 * Low-level method for communicating with a remote client during a single RPC. Unlike normal RPCs,
 * calls may stream any number of requests and responses, although a single request and single
 * response is most common. This API is generally intended for use generated handlers, but advanced
 * applications may have need for it.
 *
 * <p>Any contexts must be sent before any payloads, which must be sent before closing.
 *
 * <p>No generic method for determining message receipt or providing acknowlegement is provided.
 * Applications are expected to utilize normal payload messages for such signals, as a response
 * natually acknowledges its request.
 *
 * <p>Methods are guaranteed to be non-blocking. Implementations are not required to be thread-safe.
 */
public abstract class ServerCall<ResponseT> {
  /**
   * Callbacks for consuming incoming RPC messages.
   *
   * <p>Any contexts are guaranteed to arrive before any payloads, which are guaranteed before half
   * close, which is guaranteed before completion.
   *
   * <p>Implementations are free to block for extended periods of time. Implementations are not
   * required to be thread-safe.
   */
  // TODO(user): We need to decide what to do in the case of server closing with non-cancellation
  // before client half closes. It may be that we treat such a case as an error. If we permit such
  // a case then we either get to generate a half close or purposefully omit it.
  public abstract static class Listener<RequestT> {
    /**
     * A request context has been received. Any context messages will precede payload messages.
     *
     * <p>The {@code value} {@link InputStream} will be closed when the returned future completes.
     * If no future is returned, the value will be closed immediately after returning from this
     * method.
     */
    @Nullable
    public abstract ListenableFuture<Void> onContext(String name, InputStream value);

    /**
     * A request payload has been receiveed. For streaming calls, there may be zero payload
     * messages.
     */
    @Nullable
    public abstract ListenableFuture<Void> onPayload(RequestT payload);

    /**
     * The client completed all message sending. However, the call may still be cancelled.
     */
    public abstract void onHalfClose();

    /**
     * The call was cancelled and the server is encouraged to abort processing to save resources,
     * since the client will not process any further messages. Cancellations can be caused by
     * timeouts, explicit cancel by client, network errors, and similar.
     *
     * <p>There will be no further callbacks for the call.
     */
    public abstract void onCancel();

    /**
     * The call is considered complete and {@link #onCancel} is guaranteed not to be called.
     * However, the client is not guaranteed to have received all messages.
     *
     * <p>There will be no further callbacks for the call.
     */
    public abstract void onCompleted();
  }

  /**
   * Close the call with the provided status. No further sending or receiving will occur. If {@code
   * status} is not equal to {@link Status#OK}, then the call is said to have failed.
   *
   * <p>If {@code status} is not {@link Status#CANCELLED} and no errors or cancellations are known
   * to have occured, then a {@link Listener#onCompleted} notification should be expected.
   * Otherwise {@link Listener#onCancel} has been or will be called.
   *
   * @throws IllegalStateException if call is already {@code close}d
   */
  public abstract void close(Status status);

  /**
   * Send a context message. Context messages are intended for side-channel information like
   * statistics and authentication.
   *
   * @param name key identifier of context
   * @param value context value bytes
   * @throws IllegalStateException if call is {@link #close}d, or after {@link #sendPayload}
   */
  public abstract void sendContext(String name, InputStream value);

  /**
   * Send a payload message. Payload messages are the primary form of communication associated with
   * RPCs. Multiple payload messages may exist for streaming calls.
   *
   * @param payload message
   * @throws IllegalStateException if call is {@link #close}d
   */
  public abstract void sendPayload(ResponseT payload);

  /**
   * Returns {@code true} when the call is cancelled and the server is encouraged to abort
   * processing to save resources, since the client will not be processing any further methods.
   * Cancellations can be caused by timeouts, explicit cancel by client, network errors, and
   * similar.
   *
   * <p>This method may safely be called concurrently from multiple threads.
   */
  public abstract boolean isCancelled();
}