1 | // Protocol Buffers - Google's data interchange format |
---|
2 | // Copyright 2008 Google Inc. All rights reserved. |
---|
3 | // http://code.google.com/p/protobuf/ |
---|
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 | * <p>An {@code RpcController} mediates a single method call. The primary |
---|
35 | * purpose of the controller is to provide a way to manipulate settings |
---|
36 | * specific to the RPC implementation and to find out about RPC-level errors. |
---|
37 | * |
---|
38 | * <p>Starting with version 2.3.0, RPC implementations should not try to build |
---|
39 | * on this, but should instead provide code generator plugins which generate |
---|
40 | * code specific to the particular RPC implementation. This way the generated |
---|
41 | * code can be more appropriate for the implementation in use and can avoid |
---|
42 | * unnecessary layers of indirection. |
---|
43 | * |
---|
44 | * <p>The methods provided by the {@code RpcController} interface are intended |
---|
45 | * to be a "least common denominator" set of features which we expect all |
---|
46 | * implementations to support. Specific implementations may provide more |
---|
47 | * advanced features (e.g. deadline propagation). |
---|
48 | * |
---|
49 | * @author kenton@google.com Kenton Varda |
---|
50 | */ |
---|
51 | public interface RpcController { |
---|
52 | // ----------------------------------------------------------------- |
---|
53 | // These calls may be made from the client side only. Their results |
---|
54 | // are undefined on the server side (may throw RuntimeExceptions). |
---|
55 | |
---|
56 | /** |
---|
57 | * Resets the RpcController to its initial state so that it may be reused in |
---|
58 | * a new call. This can be called from the client side only. It must not |
---|
59 | * be called while an RPC is in progress. |
---|
60 | */ |
---|
61 | void reset(); |
---|
62 | |
---|
63 | /** |
---|
64 | * After a call has finished, returns true if the call failed. The possible |
---|
65 | * reasons for failure depend on the RPC implementation. {@code failed()} |
---|
66 | * most only be called on the client side, and must not be called before a |
---|
67 | * call has finished. |
---|
68 | */ |
---|
69 | boolean failed(); |
---|
70 | |
---|
71 | /** |
---|
72 | * If {@code failed()} is {@code true}, returns a human-readable description |
---|
73 | * of the error. |
---|
74 | */ |
---|
75 | String errorText(); |
---|
76 | |
---|
77 | /** |
---|
78 | * Advises the RPC system that the caller desires that the RPC call be |
---|
79 | * canceled. The RPC system may cancel it immediately, may wait awhile and |
---|
80 | * then cancel it, or may not even cancel the call at all. If the call is |
---|
81 | * canceled, the "done" callback will still be called and the RpcController |
---|
82 | * will indicate that the call failed at that time. |
---|
83 | */ |
---|
84 | void startCancel(); |
---|
85 | |
---|
86 | // ----------------------------------------------------------------- |
---|
87 | // These calls may be made from the server side only. Their results |
---|
88 | // are undefined on the client side (may throw RuntimeExceptions). |
---|
89 | |
---|
90 | /** |
---|
91 | * Causes {@code failed()} to return true on the client side. {@code reason} |
---|
92 | * will be incorporated into the message returned by {@code errorText()}. |
---|
93 | * If you find you need to return machine-readable information about |
---|
94 | * failures, you should incorporate it into your response protocol buffer |
---|
95 | * and should NOT call {@code setFailed()}. |
---|
96 | */ |
---|
97 | void setFailed(String reason); |
---|
98 | |
---|
99 | /** |
---|
100 | * If {@code true}, indicates that the client canceled the RPC, so the server |
---|
101 | * may as well give up on replying to it. This method must be called on the |
---|
102 | * server side only. The server should still call the final "done" callback. |
---|
103 | */ |
---|
104 | boolean isCanceled(); |
---|
105 | |
---|
106 | /** |
---|
107 | * Asks that the given callback be called when the RPC is canceled. The |
---|
108 | * parameter passed to the callback will always be {@code null}. The |
---|
109 | * callback will always be called exactly once. If the RPC completes without |
---|
110 | * being canceled, the callback will be called after completion. If the RPC |
---|
111 | * has already been canceled when NotifyOnCancel() is called, the callback |
---|
112 | * will be called immediately. |
---|
113 | * |
---|
114 | * <p>{@code notifyOnCancel()} must be called no more than once per request. |
---|
115 | * It must be called on the server side only. |
---|
116 | */ |
---|
117 | void notifyOnCancel(RpcCallback<Object> callback); |
---|
118 | } |
---|