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.internal; 18 19 import java.io.InputStream; 20 import javax.annotation.Nullable; 21 22 /** 23 * An observer of {@link Stream} events. It is guaranteed to only have one concurrent callback at a 24 * time. 25 */ 26 public interface StreamListener { 27 /** 28 * Called upon receiving a message from the remote end-point. 29 * 30 * <p>Implementations must eventually drain the provided {@code producer} {@link MessageProducer} 31 * completely by invoking {@link MessageProducer#next()} to obtain deframed messages until the 32 * producer returns null. 33 * 34 * <p>This method should return quickly, as the same thread may be used to process other streams. 35 * 36 * @param producer supplier of deframed messages. 37 */ messagesAvailable(MessageProducer producer)38 void messagesAvailable(MessageProducer producer); 39 40 /** 41 * This indicates that the transport is now capable of sending additional messages 42 * without requiring excessive buffering internally. This event is 43 * just a suggestion and the application is free to ignore it, however doing so may 44 * result in excessive buffering within the transport. 45 */ onReady()46 void onReady(); 47 48 /** 49 * A producer for deframed gRPC messages. 50 */ 51 interface MessageProducer { 52 /** 53 * Returns the next gRPC message, if the data has been received by the deframer and the 54 * application has requested another message. 55 * 56 * <p>The provided {@code message} {@link InputStream} must be closed by the listener. 57 * 58 * <p>This is intended to be used similar to an iterator, invoking {@code next()} to obtain 59 * messages until the producer returns null, at which point the producer may be discarded. 60 */ 61 @Nullable next()62 public InputStream next(); 63 } 64 } 65