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="http://www.ibm.com/developerworks/library/j-jtp09263/">thread-compatible</a>). 30 * 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 public interface StreamObserver<V> { 36 /** 37 * Receives a value from the stream. 38 * 39 * <p>Can be called many times but is never called after {@link #onError(Throwable)} or {@link 40 * #onCompleted()} are called. 41 * 42 * <p>Unary calls must invoke onNext at most once. Clients may invoke onNext at most once for 43 * server streaming calls, but may receive many onNext callbacks. Servers may invoke onNext at 44 * most once for client streaming calls, but may receive many onNext callbacks. 45 * 46 * <p>If an exception is thrown by an implementation the caller is expected to terminate the 47 * stream by calling {@link #onError(Throwable)} with the caught exception prior to 48 * propagating it. 49 * 50 * @param value the value passed to the stream 51 */ onNext(V value)52 void onNext(V value); 53 54 /** 55 * Receives a terminating error from the stream. 56 * 57 * <p>May only be called once and if called it must be the last method called. In particular if an 58 * exception is thrown by an implementation of {@code onError} no further calls to any method are 59 * allowed. 60 * 61 * <p>{@code t} should be a {@link io.grpc.StatusException} or {@link 62 * io.grpc.StatusRuntimeException}, but other {@code Throwable} types are possible. Callers should 63 * generally convert from a {@link io.grpc.Status} via {@link io.grpc.Status#asException()} or 64 * {@link io.grpc.Status#asRuntimeException()}. Implementations should generally convert to a 65 * {@code Status} via {@link io.grpc.Status#fromThrowable(Throwable)}. 66 * 67 * @param t the error occurred on the stream 68 */ onError(Throwable t)69 void onError(Throwable t); 70 71 /** 72 * Receives a notification of successful stream completion. 73 * 74 * <p>May only be called once and if called it must be the last method called. In particular if an 75 * exception is thrown by an implementation of {@code onCompleted} no further calls to any method 76 * are allowed. 77 */ onCompleted()78 void onCompleted(); 79 } 80