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 import java.util.concurrent.CancellationException; 33 34 /** 35 * Allows the implementer of {@link ResponseObserver} to control the flow of responses. 36 * 37 * <p>An instance of this class will be passed to {@link 38 * ResponseObserver#onStart(StreamController)}, at which point the receiver can disable automatic 39 * flow control. The receiver can also save a reference to the instance and terminate the stream 40 * early using {@code cancel()}. 41 */ 42 public interface StreamController { 43 /** 44 * Cancel the stream early. 45 * 46 * <p>This will manifest as an onError on the {@link ResponseObserver} with the cause being a 47 * {@link CancellationException}. 48 */ cancel()49 void cancel(); 50 51 /** 52 * Disables automatic flow control. 53 * 54 * <p>The next response is requested immediately after the current response is processed by {@link 55 * ResponseObserver#onResponse(Object)}. If disabled, an application must make explicit calls to 56 * {@link #request} to receive messages. 57 */ disableAutoInboundFlowControl()58 void disableAutoInboundFlowControl(); 59 60 /** 61 * Requests up to the given number of responses from the call to be delivered to {@link 62 * ResponseObserver#onResponse(Object)}. No additional messages will be delivered. 63 * 64 * <p>This method can only be called after disabling automatic flow control. 65 * 66 * <p>Message delivery is guaranteed to be sequential in the order received. In addition, the 67 * listener methods will not be accessed concurrently. While it is not guaranteed that the same 68 * thread will always be used, it is guaranteed that only a single thread will access the listener 69 * at a time. 70 * 71 * <p>If called multiple times, the number of messages able to delivered will be the sum of the 72 * calls. 73 * 74 * <p>This method is safe to call from multiple threads without external synchronizaton. 75 * 76 * @param count the requested number of messages to be delivered to the listener. Must be 77 * non-negative. 78 */ request(int count)79 void request(int count); 80 } 81