1 // Protocol Buffers - Google's data interchange format 2 // Copyright 2008 Google Inc. All rights reserved. 3 // https://developers.google.com/protocol-buffers/ 4 // 5 // Redistribution and use in source and binary forms, with or without 6 // modification, are permitted provided that the following conditions are 7 // met: 8 // 9 // * Redistributions of source code must retain the above copyright 10 // notice, this list of conditions and the following disclaimer. 11 // * Redistributions in binary form must reproduce the above 12 // copyright notice, this list of conditions and the following disclaimer 13 // in the documentation and/or other materials provided with the 14 // distribution. 15 // * Neither the name of Google Inc. nor the names of its 16 // contributors may be used to endorse or promote products derived from 17 // this software without specific prior written permission. 18 // 19 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 24 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 25 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 31 package com.google.protobuf; 32 33 /** 34 * An {@code RpcController} mediates a single method call. The primary purpose of the controller is 35 * to provide a way to manipulate settings specific to the RPC implementation and to find out about 36 * RPC-level errors. 37 * 38 * <p>Starting with version 2.3.0, RPC implementations should not try to build on this, but should 39 * instead provide code generator plugins which generate code specific to the particular RPC 40 * implementation. This way the generated code can be more appropriate for the implementation in use 41 * and can avoid unnecessary layers of indirection. 42 * 43 * <p>The methods provided by the {@code RpcController} interface are intended to be a "least common 44 * denominator" set of features which we expect all implementations to support. Specific 45 * implementations may provide more advanced features (e.g. deadline propagation). 46 * 47 * @author kenton@google.com Kenton Varda 48 */ 49 public interface RpcController { 50 // ----------------------------------------------------------------- 51 // These calls may be made from the client side only. Their results 52 // are undefined on the server side (may throw RuntimeExceptions). 53 54 /** 55 * Resets the RpcController to its initial state so that it may be reused in a new call. This can 56 * be called from the client side only. It must not be called while an RPC is in progress. 57 */ reset()58 void reset(); 59 60 /** 61 * After a call has finished, returns true if the call failed. The possible reasons for failure 62 * depend on the RPC implementation. {@code failed()} most only be called on the client side, and 63 * must not be called before a call has finished. 64 */ failed()65 boolean failed(); 66 67 /** If {@code failed()} is {@code true}, returns a human-readable description of the error. */ errorText()68 String errorText(); 69 70 /** 71 * Advises the RPC system that the caller desires that the RPC call be canceled. The RPC system 72 * may cancel it immediately, may wait awhile and then cancel it, or may not even cancel the call 73 * at all. If the call is canceled, the "done" callback will still be called and the RpcController 74 * will indicate that the call failed at that time. 75 */ startCancel()76 void startCancel(); 77 78 // ----------------------------------------------------------------- 79 // These calls may be made from the server side only. Their results 80 // are undefined on the client side (may throw RuntimeExceptions). 81 82 /** 83 * Causes {@code failed()} to return true on the client side. {@code reason} will be incorporated 84 * into the message returned by {@code errorText()}. If you find you need to return 85 * machine-readable information about failures, you should incorporate it into your response 86 * protocol buffer and should NOT call {@code setFailed()}. 87 */ setFailed(String reason)88 void setFailed(String reason); 89 90 /** 91 * If {@code true}, indicates that the client canceled the RPC, so the server may as well give up 92 * on replying to it. This method must be called on the server side only. The server should still 93 * call the final "done" callback. 94 */ isCanceled()95 boolean isCanceled(); 96 97 /** 98 * Asks that the given callback be called when the RPC is canceled. The parameter passed to the 99 * callback will always be {@code null}. The callback will always be called exactly once. If the 100 * RPC completes without being canceled, the callback will be called after completion. If the RPC 101 * has already been canceled when NotifyOnCancel() is called, the callback will be called 102 * immediately. 103 * 104 * <p>{@code notifyOnCancel()} must be called no more than once per request. It must be called on 105 * the server side only. 106 */ notifyOnCancel(RpcCallback<Object> callback)107 void notifyOnCancel(RpcCallback<Object> callback); 108 } 109