grpc / grpc-java / #18725

/*

 * Copyright 2014 The gRPC Authors

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *     http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

package io.grpc;

import javax.annotation.Nullable;

/**

 * An instance of a call to a remote method. A call will send zero or more

 * request messages to the server and receive zero or more response messages back.

 *

 * <p>Instances are created

 * by a {@link Channel} and used by stubs to invoke their remote behavior.

 *

 * <p>More advanced usages may consume this interface directly as opposed to using a stub. Common

 * reasons for doing so would be the need to interact with flow-control or when acting as a generic

 * proxy for arbitrary operations.

 *

 * <p>{@link #start} must be called prior to calling any other methods, with the exception of

 * {@link #cancel}. Whereas {@link #cancel} must not be followed by any other methods,

 * but can be called more than once, while only the first one has effect.

 *

 * <p>No generic method for determining message receipt or providing acknowledgement is provided.

 * Applications are expected to utilize normal payload messages for such signals, as a response

 * naturally acknowledges its request.

 *

 * <p>Methods are guaranteed to be non-blocking. Not thread-safe except for {@link #request}, which

 * may be called from any thread.

 *

 * <p>There is no interaction between the states on the {@link Listener Listener} and {@link

 * ClientCall}, i.e., if {@link Listener#onClose Listener.onClose()} is called, it has no bearing on

 * the permitted operations on {@code ClientCall} (but it may impact whether they do anything).

 *

 * <p>There is a race between {@link #cancel} and the completion/failure of the RPC in other ways.

 * If {@link #cancel} won the race, {@link Listener#onClose Listener.onClose()} is called with

 * {@link Status#CANCELLED CANCELLED}. Otherwise, {@link Listener#onClose Listener.onClose()} is

 * called with whatever status the RPC was finished. We ensure that at most one is called.

 *

 * <h3>Usage examples</h3>

 * <h4>Simple Unary (1 request, 1 response) RPC</h4>

 * <pre>

 *   call = channel.newCall(unaryMethod, callOptions);

 *   call.start(listener, headers);

 *   call.sendMessage(message);

 *   call.halfClose();

 *   call.request(1);

 *   // wait for listener.onMessage()

 * </pre>

 *

 * <h4>Flow-control in Streaming RPC</h4>

 *

 * <p>The following snippet demonstrates a bi-directional streaming case, where the client sends

 * requests produced by a fictional <code>makeNextRequest()</code> in a flow-control-compliant

 * manner, and notifies gRPC library to receive additional response after one is consumed by

 * a fictional <code>processResponse()</code>.

 *

 * <p><pre>

 *   call = channel.newCall(bidiStreamingMethod, callOptions);

 *   listener = new ClientCall.Listener<FooResponse>() {

 *     @Override

 *     public void onMessage(FooResponse response) {

 *       processResponse(response);

 *       // Notify gRPC to receive one additional response.

 *       call.request(1);

 *     }

 *

 *     @Override

 *     public void onReady() {

 *       while (call.isReady()) {

 *         FooRequest nextRequest = makeNextRequest();

 *         if (nextRequest == null) {  // No more requests to send

 *           call.halfClose();

 *           return;

 *         }

 *         call.sendMessage(nextRequest);

 *       }

 *     }

 *   }

 *   call.start(listener, headers);

 *   // Notify gRPC to receive one response. Without this line, onMessage() would never be called.

 *   call.request(1);

 * </pre>

 *

 * <p>DO NOT MOCK: Use InProcessServerBuilder and make a test server instead.

 *

 * @param <ReqT> type of message sent one or more times to the server.

 * @param <RespT> type of message received one or more times from the server.

 */

  /**

   * Callbacks for receiving metadata, response messages and completion status from the server.

   *

   * <p>Implementations are free to block for extended periods of time. Implementations are not

   * required to be thread-safe, but they must not be thread-hostile. The caller is free to call

   * an instance from multiple threads, but only one call simultaneously. A single thread may

   * interleave calls to multiple instances, so implementations using ThreadLocals must be careful

   * to avoid leaking inappropriate state (e.g., clearing the ThreadLocal before returning).

   *

   * @param <T> type of message received.

   */

    /**

     * The response headers have been received. Headers always precede messages.

     *

     * <p>Since {@link Metadata} is not thread-safe, the caller must not access (read or write)

     * {@code headers} after this point.

     *

     * @param headers containing metadata sent by the server at the start of the response.

     */

    /**

     * A response message has been received. May be called zero or more times depending on whether

     * the call response is empty, a single message or a stream of messages.

     *

     * @param message returned by the server

     */

    /**

     * The ClientCall has been closed. Any additional calls to the {@code ClientCall} will not be

     * processed by the server. No further receiving will occur and no further notifications will be

     * made.

     *

     * <p>Since {@link Metadata} is not thread-safe, the caller must not access (read or write)

     * {@code trailers} after this point.

     *

     * <p>If {@code status} returns false for {@link Status#isOk()}, then the call failed.

     * An additional block of trailer metadata may be received at the end of the call from the

     * server. An empty {@link Metadata} object is passed if no trailers are received.

     *

     * <p>This method should not throw. If this method throws, there is no way to be notified of the

     * exception. Implementations should therefore be careful of exceptions which can accidentally 

     * leak resources.

     *

     * @param status the result of the remote call.

     * @param trailers metadata provided at call completion.

     */

    /**

     * This indicates that the ClientCall may now be capable of sending additional messages (via

     * {@link #sendMessage}) without requiring excessive buffering internally. This event is

     * just a suggestion and the application is free to ignore it, however doing so may

     * result in excessive buffering within the ClientCall.

     *

     * <p>Because there is a processing delay to deliver this notification, it is possible for

     * concurrent writes to cause {@code isReady() == false} within this callback. Handle "spurious"

     * notifications by checking {@code isReady()}'s current value instead of assuming it is now

     * {@code true}. If {@code isReady() == false} the normal expectations apply, so there would be

     * <em>another</em> {@code onReady()} callback.

     *

     * <p>If the type of a call is either {@link MethodDescriptor.MethodType#UNARY} or

     * {@link MethodDescriptor.MethodType#SERVER_STREAMING}, this callback may not be fired. Calls

     * that send exactly one message should not await this callback.

     */

  }

  /**

   * Start a call, using {@code responseListener} for processing response messages.

   *

   * <p>It must be called prior to any other method on this class, except for {@link #cancel} which

   * may be called at any time.

   *

   * <p>Since {@link Metadata} is not thread-safe, the caller must not access (read or write) {@code

   * headers} after this point.

   *

   * @param responseListener receives response messages

   * @param headers which can contain extra call metadata, e.g. authentication credentials.

   * @throws IllegalStateException if a method (including {@code start()}) on this class has been

   *                               called.

   */

  public abstract void start(Listener<RespT> responseListener, Metadata headers);

  /**

   * Requests up to the given number of messages from the call to be delivered to

   * {@link Listener#onMessage(Object)}. No additional messages will be delivered.

   *

   * <p>Message delivery is guaranteed to be sequential in the order received. In addition, the

   * listener methods will not be accessed concurrently. While it is not guaranteed that the same

   * thread will always be used, it is guaranteed that only a single thread will access the listener

   * at a time.

   *

   * <p>If it is desired to bypass inbound flow control, a very large number of messages can be

   * specified (e.g. {@link Integer#MAX_VALUE}).

   *

   * <p>If called multiple times, the number of messages able to delivered will be the sum of the

   * calls.

   *

   * <p>This method is safe to call from multiple threads without external synchronization.

   *

   * @param numMessages the requested number of messages to be delivered to the listener. Must be

   *                    non-negative.

   * @throws IllegalStateException if call is not {@code start()}ed

   * @throws IllegalArgumentException if numMessages is negative

   */

  public abstract void request(int numMessages);

  /**

   * Prevent any further processing for this {@code ClientCall}. No further messages may be sent or

   * will be received. The server is informed of cancellations, but may not stop processing the

   * call. Cancellation is permitted even if previously {@link #halfClose}d. Cancelling an already

   * {@code cancel()}ed {@code ClientCall} has no effect.

   *

   * <p>No other methods on this class can be called after this method has been called.

   *

   * <p>It is recommended that at least one of the arguments to be non-{@code null}, to provide

   * useful debug information. Both argument being null may log warnings and result in suboptimal

   * performance. Also note that the provided information will not be sent to the server.

   *

   * @param message if not {@code null}, will appear as the description of the CANCELLED status

   * @param cause if not {@code null}, will appear as the cause of the CANCELLED status

   */

  public abstract void cancel(@Nullable String message, @Nullable Throwable cause);

  /**

   * Close the call for request message sending. Incoming response messages are unaffected.  This

   * should be called when no more messages will be sent from the client.

   *

   * @throws IllegalStateException if call is already {@code halfClose()}d or {@link #cancel}ed

   */

  public abstract void halfClose();

  /**

   * Send a request message to the server. May be called zero or more times depending on how many

   * messages the server is willing to accept for the operation.

   *

   * @param message message to be sent to the server.

   * @throws IllegalStateException if call is {@link #halfClose}d or explicitly {@link #cancel}ed

   */

  public abstract void sendMessage(ReqT message);

  /**

   * If {@code true}, indicates that the call is capable of sending additional messages

   * without requiring excessive buffering internally. This event is

   * just a suggestion and the application is free to ignore it, however doing so may

   * result in excessive buffering within the call.

   *

   * <p>If {@code false}, {@link Listener#onReady()} will be called after {@code isReady()}

   * transitions to {@code true}.

   *

   * <p>If the type of the call is either {@link MethodDescriptor.MethodType#UNARY} or

   * {@link MethodDescriptor.MethodType#SERVER_STREAMING}, this method may persistently return

   * false. Calls that send exactly one message should not check this method.

   *

   * <p>This abstract class's implementation always returns {@code true}. Implementations generally

   * override the method.

   */

  public boolean isReady() {

  }

  /**

   * Enables per-message compression, if an encoding type has been negotiated.  If no message

   * encoding has been negotiated, this is a no-op. By default per-message compression is enabled,

   * but may not have any effect if compression is not enabled on the call.

   */

  public void setMessageCompression(boolean enabled) {

    // noop

  /**

   * Returns additional properties of the call. May only be called after {@link Listener#onHeaders}

   * or {@link Listener#onClose}. If called prematurely, the implementation may throw {@code

   * IllegalStateException} or return arbitrary {@code Attributes}.

   *

   * @return non-{@code null} attributes

   * @throws IllegalStateException (optional) if called before permitted

   */

  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2607")

  @Grpc.TransportAttr

  public Attributes getAttributes() {

  }

}