1 /* 2 * Copyright 2014 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 /** 20 * Receives notifications from an observable stream of messages. 21 * 22 * <p>It is used by both the client stubs and service implementations for sending or receiving 23 * stream messages. It is used for all {@link io.grpc.MethodDescriptor.MethodType}, including 24 * {@code UNARY} calls. For outgoing messages, a {@code StreamObserver} is provided by the GRPC 25 * library to the application. For incoming messages, the application implements the 26 * {@code StreamObserver} and passes it to the GRPC library for receiving. 27 * 28 * <p>Implementations are not required to be thread-safe (but should be 29 * <a href="https://web.archive.org/web/20210125044505/https://www.ibm.com/developerworks/java/library/j-jtp09263/index.html"> 30 * thread-compatible</a>). Separate {@code StreamObserver}s do 31 * not need to be synchronized together; incoming and outgoing directions are independent. 32 * Since individual {@code StreamObserver}s are not thread-safe, if multiple threads will be 33 * writing to a {@code StreamObserver} concurrently, the application must synchronize calls. 34 * 35 * <p>This API is asynchronous, so methods may return before the operation completes. The API 36 * provides no guarantees for how quickly an operation will complete, so utilizing flow control via 37 * {@link ClientCallStreamObserver} and {@link ServerCallStreamObserver} to avoid excessive 38 * buffering is recommended for streaming RPCs. gRPC's implementation of {@code onError()} on 39 * client-side causes the RPC to be cancelled and discards all messages, so completes quickly. 40 * 41 * <p>gRPC guarantees it does not block on I/O in its implementation, but applications are allowed 42 * to perform blocking operations in their implementations. However, doing so will delay other 43 * callbacks because the methods cannot be called concurrently. 44 */ 45 public interface StreamObserver<V> { 46 /** 47 * Receives a value from the stream. 48 * 49 * <p>Can be called many times but is never called after {@link #onError(Throwable)} or {@link 50 * #onCompleted()} are called. 51 * 52 * <p>Unary calls must invoke onNext at most once. Clients may invoke onNext at most once for 53 * server streaming calls, but may receive many onNext callbacks. Servers may invoke onNext at 54 * most once for client streaming calls, but may receive many onNext callbacks. 55 * 56 * <p>If an exception is thrown by an implementation the caller is expected to terminate the 57 * stream by calling {@link #onError(Throwable)} with the caught exception prior to 58 * propagating it. 59 * 60 * @param value the value passed to the stream 61 */ onNext(V value)62 void onNext(V value); 63 64 /** 65 * Receives a terminating error from the stream. 66 * 67 * <p>May only be called once and if called it must be the last method called. In particular if an 68 * exception is thrown by an implementation of {@code onError} no further calls to any method are 69 * allowed. 70 * 71 * <p>{@code t} should be a {@link io.grpc.StatusException} or {@link 72 * io.grpc.StatusRuntimeException}, but other {@code Throwable} types are possible. Callers should 73 * generally convert from a {@link io.grpc.Status} via {@link io.grpc.Status#asException()} or 74 * {@link io.grpc.Status#asRuntimeException()}. Implementations should generally convert to a 75 * {@code Status} via {@link io.grpc.Status#fromThrowable(Throwable)}. 76 * 77 * @param t the error occurred on the stream 78 */ onError(Throwable t)79 void onError(Throwable t); 80 81 /** 82 * Receives a notification of successful stream completion. 83 * 84 * <p>May only be called once and if called it must be the last method called. In particular if an 85 * exception is thrown by an implementation of {@code onCompleted} no further calls to any method 86 * are allowed. 87 */ onCompleted()88 void onCompleted(); 89 } 90