1 /* 2 * Copyright 2017 Google LLC 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions are 6 * met: 7 * 8 * * Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * * Redistributions in binary form must reproduce the above 11 * copyright notice, this list of conditions and the following disclaimer 12 * in the documentation and/or other materials provided with the 13 * distribution. 14 * * Neither the name of Google LLC nor the names of its 15 * contributors may be used to endorse or promote products derived from 16 * this software without specific prior written permission. 17 * 18 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 21 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 22 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 23 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 24 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 */ 30 package com.google.api.gax.rpc; 31 32 /** 33 * Receives notifications from an observable stream of messages. 34 * 35 * <p>It is used for sending messages in bidi (bidirectional) or client-streaming calls, or for 36 * receiving messages in bidi or server-streaming calls. 37 * 38 * <p>For outgoing messages, an {@code ApiStreamObserver} is provided by GAX to the application, and 39 * the application then provides the messages to send. For incoming messages, the application 40 * implements the {@code ApiStreamObserver} and passes it to GAX, which then calls the observer with 41 * the messages for the application to receive them. 42 * 43 * <p>Implementations are expected to be <a 44 * href="http://www.ibm.com/developerworks/library/j-jtp09263/">thread-compatible</a>. Separate 45 * {@code ApiStreamObserver}s do not need to be synchronized together; incoming and outgoing 46 * directions are independent. Since individual {@code ApiStreamObserver}s are not thread-safe, if 47 * multiple threads will be writing to a {@code ApiStreamObserver} concurrently, the application 48 * must synchronize calls. 49 * 50 * <p>This interface is a fork of io.grpc.stub.StreamObserver to enable shadowing of Guava, and also 51 * to allow for a transport-agnostic interface that doesn't depend on gRPC. 52 */ 53 public interface ApiStreamObserver<V> { 54 /** 55 * Receives a value from the stream. 56 * 57 * <p>Can be called many times but is never called after {@link #onError(Throwable)} or {@link 58 * #onCompleted()} are called. 59 * 60 * <p>Clients may invoke onNext at most once for server streaming calls, but may receive many 61 * onNext callbacks. Servers may invoke onNext at most once for client streaming calls, but may 62 * receive many onNext callbacks. 63 * 64 * <p>If an exception is thrown by an implementation the caller is expected to terminate the 65 * stream by calling {@link #onError(Throwable)} with the caught exception prior to propagating 66 * it. 67 * 68 * @param value the value passed to the stream 69 */ onNext(V value)70 void onNext(V value); 71 72 /** 73 * Receives a terminating error from the stream. 74 * 75 * <p>May only be called once and if called, it must be the last method called. In particular if 76 * an exception is thrown by an implementation of {@code onError}, no further calls to any method 77 * are allowed. 78 * 79 * @param t the error occurred on the stream 80 */ onError(Throwable t)81 void onError(Throwable t); 82 83 /** 84 * Receives a notification of successful stream completion. 85 * 86 * <p>May only be called once, and if called it must be the last method called. In particular if 87 * an exception is thrown by an implementation of {@code onCompleted}, no further calls to any 88 * method are allowed. 89 */ onCompleted()90 void onCompleted(); 91 } 92