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 javax.annotation.Nullable; 20 21 /** 22 * A refinement of {@link CallStreamObserver} that allows for lower-level interaction with 23 * client calls. An instance of this class is obtained via {@link ClientResponseObserver}, or by 24 * manually casting the {@code StreamObserver} returned by a stub. 25 * 26 * <p>Like {@code StreamObserver}, implementations are not required to be thread-safe; if multiple 27 * threads will be writing to an instance concurrently, the application must synchronize its calls. 28 * 29 * <p>DO NOT MOCK: The API is too complex to reliably mock. Use InProcessChannelBuilder to create 30 * "real" RPCs suitable for testing and make a fake for the server-side. 31 */ 32 public abstract class ClientCallStreamObserver<ReqT> extends CallStreamObserver<ReqT> { 33 /** 34 * Prevent any further processing for this {@code ClientCallStreamObserver}. No further messages 35 * will be received. The server is informed of cancellations, but may not stop processing the 36 * call. Cancelling an already 37 * {@code cancel()}ed {@code ClientCallStreamObserver} has no effect. 38 * 39 * <p>No other methods on this class can be called after this method has been called. 40 * 41 * <p>It is recommended that at least one of the arguments to be non-{@code null}, to provide 42 * useful debug information. Both argument being null may log warnings and result in suboptimal 43 * performance. Also note that the provided information will not be sent to the server. 44 * 45 * @param message if not {@code null}, will appear as the description of the CANCELLED status 46 * @param cause if not {@code null}, will appear as the cause of the CANCELLED status 47 */ cancel(@ullable String message, @Nullable Throwable cause)48 public abstract void cancel(@Nullable String message, @Nullable Throwable cause); 49 50 /** 51 * Swaps to manual flow control where no message will be delivered to {@link 52 * StreamObserver#onNext(Object)} unless it is {@link #request request()}ed. Since {@code 53 * request()} may not be called before the call is started, a number of initial requests may be 54 * specified. 55 * 56 * <p>This method may only be called during {@link ClientResponseObserver#beforeStart 57 * ClientResponseObserver.beforeStart()}. 58 */ disableAutoRequestWithInitial(int request)59 public void disableAutoRequestWithInitial(int request) { 60 throw new UnsupportedOperationException(); 61 } 62 63 /** 64 * If {@code true}, indicates that the observer is capable of sending additional messages 65 * without requiring excessive buffering internally. This value is just a suggestion and the 66 * application is free to ignore it, however doing so may result in excessive buffering within the 67 * observer. 68 * 69 * <p>If {@code false}, the runnable passed to {@link #setOnReadyHandler} will be called after 70 * {@code isReady()} transitions to {@code true}. 71 */ 72 @Override isReady()73 public abstract boolean isReady(); 74 75 /** 76 * Set a {@link Runnable} that will be executed every time the stream {@link #isReady()} state 77 * changes from {@code false} to {@code true}. While it is not guaranteed that the same 78 * thread will always be used to execute the {@link Runnable}, it is guaranteed that executions 79 * are serialized with calls to the 'inbound' {@link StreamObserver}. 80 * 81 * <p>May only be called during {@link ClientResponseObserver#beforeStart}. 82 * 83 * <p>Because there is a processing delay to deliver this notification, it is possible for 84 * concurrent writes to cause {@code isReady() == false} within this callback. Handle "spurious" 85 * notifications by checking {@code isReady()}'s current value instead of assuming it is now 86 * {@code true}. If {@code isReady() == false} the normal expectations apply, so there would be 87 * <em>another</em> {@code onReadyHandler} callback. 88 * 89 * @param onReadyHandler to call when peer is ready to receive more messages. 90 */ 91 @Override setOnReadyHandler(Runnable onReadyHandler)92 public abstract void setOnReadyHandler(Runnable onReadyHandler); 93 94 /** 95 * Requests the peer to produce {@code count} more messages to be delivered to the 'inbound' 96 * {@link StreamObserver}. 97 * 98 * <p>This method is safe to call from multiple threads without external synchronization. 99 * 100 * @param count more messages 101 */ 102 @Override request(int count)103 public abstract void request(int count); 104 105 /** 106 * Sets message compression for subsequent calls to {@link #onNext}. 107 * 108 * @param enable whether to enable compression. 109 */ 110 @Override setMessageCompression(boolean enable)111 public abstract void setMessageCompression(boolean enable); 112 } 113