1 /* 2 * Copyright 2016 The gRPC Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package io.grpc.stub; 18 19 import io.grpc.ExperimentalApi; 20 21 /** 22 * A refinement of StreamObserver provided by the GRPC runtime to the application that allows for 23 * more complex interactions with call behavior. 24 * 25 * <p>In any call there are logically two {@link StreamObserver} implementations: 26 * <ul> 27 * <li>'inbound' - which the GRPC runtime calls when it receives messages from the 28 * remote peer. This is implemented by the application. 29 * </li> 30 * <li>'outbound' - which the GRPC runtime provides to the application which it uses to 31 * send messages to the remote peer. 32 * </li> 33 * </ul> 34 * 35 * <p>Implementations of this class represent the 'outbound' message stream. 36 * 37 * <p>Like {@code StreamObserver}, implementations are not required to be thread-safe; if multiple 38 * threads will be writing to an instance concurrently, the application must synchronize its calls. 39 * 40 * <p>DO NOT MOCK: The API is too complex to reliably mock. Use InProcessChannelBuilder to create 41 * "real" RPCs suitable for testing. 42 */ 43 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1788") 44 public abstract class CallStreamObserver<V> implements StreamObserver<V> { 45 46 /** 47 * If {@code true}, indicates that the observer is capable of sending additional messages 48 * without requiring excessive buffering internally. This value is just a suggestion and the 49 * application is free to ignore it, however doing so may result in excessive buffering within the 50 * observer. 51 */ isReady()52 public abstract boolean isReady(); 53 54 /** 55 * Set a {@link Runnable} that will be executed every time the stream {@link #isReady()} state 56 * changes from {@code false} to {@code true}. While it is not guaranteed that the same 57 * thread will always be used to execute the {@link Runnable}, it is guaranteed that executions 58 * are serialized with calls to the 'inbound' {@link StreamObserver}. 59 * 60 * <p>On client-side this method may only be called during {@link 61 * ClientResponseObserver#beforeStart}. On server-side it may only be called during the initial 62 * call to the application, before the service returns its {@code StreamObserver}. 63 * 64 * <p>Note that the handler may be called some time after {@link #isReady} has transitioned to 65 * true as other callbacks may still be executing in the 'inbound' observer. 66 * 67 * @param onReadyHandler to call when peer is ready to receive more messages. 68 */ setOnReadyHandler(Runnable onReadyHandler)69 public abstract void setOnReadyHandler(Runnable onReadyHandler); 70 71 /** 72 * Disables automatic flow control where a token is returned to the peer after a call 73 * to the 'inbound' {@link io.grpc.stub.StreamObserver#onNext(Object)} has completed. If disabled 74 * an application must make explicit calls to {@link #request} to receive messages. 75 * 76 * <p>On client-side this method may only be called during {@link 77 * ClientResponseObserver#beforeStart}. On server-side it may only be called during the initial 78 * call to the application, before the service returns its {@code StreamObserver}. 79 * 80 * <p>Note that for cases where the runtime knows that only one inbound message is allowed 81 * calling this method will have no effect and the runtime will always permit one and only 82 * one message. This is true for: 83 * <ul> 84 * <li>{@link io.grpc.MethodDescriptor.MethodType#UNARY} operations on both the 85 * client and server. 86 * </li> 87 * <li>{@link io.grpc.MethodDescriptor.MethodType#CLIENT_STREAMING} operations on the client. 88 * </li> 89 * <li>{@link io.grpc.MethodDescriptor.MethodType#SERVER_STREAMING} operations on the server. 90 * </li> 91 * </ul> 92 * </p> 93 */ disableAutoInboundFlowControl()94 public abstract void disableAutoInboundFlowControl(); 95 96 /** 97 * Requests the peer to produce {@code count} more messages to be delivered to the 'inbound' 98 * {@link StreamObserver}. 99 * 100 * <p>This method is safe to call from multiple threads without external synchronization. 101 * 102 * @param count more messages 103 */ request(int count)104 public abstract void request(int count); 105 106 /** 107 * Sets message compression for subsequent calls to {@link #onNext}. 108 * 109 * @param enable whether to enable compression. 110 */ setMessageCompression(boolean enable)111 public abstract void setMessageCompression(boolean enable); 112 } 113