1 // Copyright 2021 The Pigweed Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not 4 // use this file except in compliance with the License. You may obtain a copy of 5 // the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12 // License for the specific language governing permissions and limitations under 13 // the License. 14 15 package dev.pigweed.pw_rpc; 16 17 import com.google.common.util.concurrent.ListenableFuture; 18 import com.google.protobuf.MessageLite; 19 import javax.annotation.Nullable; 20 21 /** 22 * Represents an ongoing RPC call. 23 * 24 * Methods that send packets may throw a ChannelOutputException if sending failed. 25 */ 26 public interface Call { 27 /** 28 * Cancels the RPC. 29 * 30 * Sends a cancellation packet to the server and sets error() to CANCELLED. Does nothing if the 31 * call is inactive. 32 * 33 * @return true if the call was active; false if the call was inactive so nothing was done 34 * @throws ChannelOutputException the Channel.Output was unable to send the cancellation packet 35 */ cancel()36 boolean cancel() throws ChannelOutputException; 37 38 /** 39 * Cancels the RPC as in cancel(), but does not send a cancellation packet to the server. 40 * 41 * @return true if the call was active; false if the call was inactive so nothing was done 42 */ abandon()43 boolean abandon(); 44 45 /** True if the RPC has not yet completed. */ active()46 default boolean active() { 47 return status() == null && error() == null; 48 } 49 50 /** The RPC status, if the RPC completed. */ status()51 @Nullable Status status(); 52 53 /** The error that terminated this RPC, if any. */ error()54 @Nullable Status error(); 55 56 /** Represents a call to a unary or client streaming RPC that uses a future. */ 57 @SuppressWarnings("ShouldNotSubclass") 58 interface UnaryFuture<ResponseT extends MessageLite> 59 extends Call, ListenableFuture<UnaryResult<ResponseT>> {} 60 61 /** Represents a call to a server or bidirectional streaming RPC that uses a future. */ 62 @SuppressWarnings("ShouldNotSubclass") 63 interface ServerStreamingFuture extends Call, ListenableFuture<Status> {} 64 65 /** Represents a call to a client or bidirectional streaming RPC. */ 66 interface ClientStreaming<RequestT extends MessageLite> extends Call { 67 /** 68 * Sends a request to a pending client or bidirectional streaming RPC. 69 * 70 * Sends a client stream packet to the server. Does nothing if the call is inactive. 71 * 72 * @return true if the packet was sent; false if the call was inactive so nothing was done 73 * @throws ChannelOutputException the Channel.Output was unable to send the request 74 */ write(RequestT request)75 boolean write(RequestT request) throws ChannelOutputException; 76 77 /** 78 * Signals to the server that the client stream has completed. 79 * 80 * Sends a client stream end packet to the server. Does nothing if the call is inactive. 81 * 82 * @return true if the packet was sent; false if the call was inactive so nothing was done 83 * @throws ChannelOutputException the Channel.Output was unable to send the request 84 */ finish()85 boolean finish() throws ChannelOutputException; 86 } 87 88 /** Represents a call to a client streaming RPC that uses a future. */ 89 interface ClientStreamingFuture<RequestT extends MessageLite, ResponseT extends MessageLite> 90 extends ClientStreaming<RequestT>, UnaryFuture<ResponseT> {} 91 92 /** Represents a call to a bidirectional streaming RPC that uses a future. */ 93 interface BidirectionalStreamingFuture<RequestT extends MessageLite> 94 extends ClientStreaming<RequestT>, ServerStreamingFuture {} 95 } 96