OLD | NEW |
(Empty) | |
| 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 """DEPRECATED: Declares the RPC service interfaces. |
| 32 |
| 33 This module declares the abstract interfaces underlying proto2 RPC |
| 34 services. These are intended to be independent of any particular RPC |
| 35 implementation, so that proto2 services can be used on top of a variety |
| 36 of implementations. Starting with version 2.3.0, RPC implementations should |
| 37 not try to build on these, but should instead provide code generator plugins |
| 38 which generate code specific to the particular RPC implementation. This way |
| 39 the generated code can be more appropriate for the implementation in use |
| 40 and can avoid unnecessary layers of indirection. |
| 41 """ |
| 42 |
| 43 __author__ = 'petar@google.com (Petar Petrov)' |
| 44 |
| 45 |
| 46 class RpcException(Exception): |
| 47 """Exception raised on failed blocking RPC method call.""" |
| 48 pass |
| 49 |
| 50 |
| 51 class Service(object): |
| 52 |
| 53 """Abstract base interface for protocol-buffer-based RPC services. |
| 54 |
| 55 Services themselves are abstract classes (implemented either by servers or as |
| 56 stubs), but they subclass this base interface. The methods of this |
| 57 interface can be used to call the methods of the service without knowing |
| 58 its exact type at compile time (analogous to the Message interface). |
| 59 """ |
| 60 |
| 61 def GetDescriptor(): |
| 62 """Retrieves this service's descriptor.""" |
| 63 raise NotImplementedError |
| 64 |
| 65 def CallMethod(self, method_descriptor, rpc_controller, |
| 66 request, done): |
| 67 """Calls a method of the service specified by method_descriptor. |
| 68 |
| 69 If "done" is None then the call is blocking and the response |
| 70 message will be returned directly. Otherwise the call is asynchronous |
| 71 and "done" will later be called with the response value. |
| 72 |
| 73 In the blocking case, RpcException will be raised on error. |
| 74 |
| 75 Preconditions: |
| 76 * method_descriptor.service == GetDescriptor |
| 77 * request is of the exact same classes as returned by |
| 78 GetRequestClass(method). |
| 79 * After the call has started, the request must not be modified. |
| 80 * "rpc_controller" is of the correct type for the RPC implementation being |
| 81 used by this Service. For stubs, the "correct type" depends on the |
| 82 RpcChannel which the stub is using. |
| 83 |
| 84 Postconditions: |
| 85 * "done" will be called when the method is complete. This may be |
| 86 before CallMethod() returns or it may be at some point in the future. |
| 87 * If the RPC failed, the response value passed to "done" will be None. |
| 88 Further details about the failure can be found by querying the |
| 89 RpcController. |
| 90 """ |
| 91 raise NotImplementedError |
| 92 |
| 93 def GetRequestClass(self, method_descriptor): |
| 94 """Returns the class of the request message for the specified method. |
| 95 |
| 96 CallMethod() requires that the request is of a particular subclass of |
| 97 Message. GetRequestClass() gets the default instance of this required |
| 98 type. |
| 99 |
| 100 Example: |
| 101 method = service.GetDescriptor().FindMethodByName("Foo") |
| 102 request = stub.GetRequestClass(method)() |
| 103 request.ParseFromString(input) |
| 104 service.CallMethod(method, request, callback) |
| 105 """ |
| 106 raise NotImplementedError |
| 107 |
| 108 def GetResponseClass(self, method_descriptor): |
| 109 """Returns the class of the response message for the specified method. |
| 110 |
| 111 This method isn't really needed, as the RpcChannel's CallMethod constructs |
| 112 the response protocol message. It's provided anyway in case it is useful |
| 113 for the caller to know the response type in advance. |
| 114 """ |
| 115 raise NotImplementedError |
| 116 |
| 117 |
| 118 class RpcController(object): |
| 119 |
| 120 """An RpcController mediates a single method call. |
| 121 |
| 122 The primary purpose of the controller is to provide a way to manipulate |
| 123 settings specific to the RPC implementation and to find out about RPC-level |
| 124 errors. The methods provided by the RpcController interface are intended |
| 125 to be a "least common denominator" set of features which we expect all |
| 126 implementations to support. Specific implementations may provide more |
| 127 advanced features (e.g. deadline propagation). |
| 128 """ |
| 129 |
| 130 # Client-side methods below |
| 131 |
| 132 def Reset(self): |
| 133 """Resets the RpcController to its initial state. |
| 134 |
| 135 After the RpcController has been reset, it may be reused in |
| 136 a new call. Must not be called while an RPC is in progress. |
| 137 """ |
| 138 raise NotImplementedError |
| 139 |
| 140 def Failed(self): |
| 141 """Returns true if the call failed. |
| 142 |
| 143 After a call has finished, returns true if the call failed. The possible |
| 144 reasons for failure depend on the RPC implementation. Failed() must not |
| 145 be called before a call has finished. If Failed() returns true, the |
| 146 contents of the response message are undefined. |
| 147 """ |
| 148 raise NotImplementedError |
| 149 |
| 150 def ErrorText(self): |
| 151 """If Failed is true, returns a human-readable description of the error.""" |
| 152 raise NotImplementedError |
| 153 |
| 154 def StartCancel(self): |
| 155 """Initiate cancellation. |
| 156 |
| 157 Advises the RPC system that the caller desires that the RPC call be |
| 158 canceled. The RPC system may cancel it immediately, may wait awhile and |
| 159 then cancel it, or may not even cancel the call at all. If the call is |
| 160 canceled, the "done" callback will still be called and the RpcController |
| 161 will indicate that the call failed at that time. |
| 162 """ |
| 163 raise NotImplementedError |
| 164 |
| 165 # Server-side methods below |
| 166 |
| 167 def SetFailed(self, reason): |
| 168 """Sets a failure reason. |
| 169 |
| 170 Causes Failed() to return true on the client side. "reason" will be |
| 171 incorporated into the message returned by ErrorText(). If you find |
| 172 you need to return machine-readable information about failures, you |
| 173 should incorporate it into your response protocol buffer and should |
| 174 NOT call SetFailed(). |
| 175 """ |
| 176 raise NotImplementedError |
| 177 |
| 178 def IsCanceled(self): |
| 179 """Checks if the client cancelled the RPC. |
| 180 |
| 181 If true, indicates that the client canceled the RPC, so the server may |
| 182 as well give up on replying to it. The server should still call the |
| 183 final "done" callback. |
| 184 """ |
| 185 raise NotImplementedError |
| 186 |
| 187 def NotifyOnCancel(self, callback): |
| 188 """Sets a callback to invoke on cancel. |
| 189 |
| 190 Asks that the given callback be called when the RPC is canceled. The |
| 191 callback will always be called exactly once. If the RPC completes without |
| 192 being canceled, the callback will be called after completion. If the RPC |
| 193 has already been canceled when NotifyOnCancel() is called, the callback |
| 194 will be called immediately. |
| 195 |
| 196 NotifyOnCancel() must be called no more than once per request. |
| 197 """ |
| 198 raise NotImplementedError |
| 199 |
| 200 |
| 201 class RpcChannel(object): |
| 202 |
| 203 """Abstract interface for an RPC channel. |
| 204 |
| 205 An RpcChannel represents a communication line to a service which can be used |
| 206 to call that service's methods. The service may be running on another |
| 207 machine. Normally, you should not use an RpcChannel directly, but instead |
| 208 construct a stub {@link Service} wrapping it. Example: |
| 209 |
| 210 Example: |
| 211 RpcChannel channel = rpcImpl.Channel("remotehost.example.com:1234") |
| 212 RpcController controller = rpcImpl.Controller() |
| 213 MyService service = MyService_Stub(channel) |
| 214 service.MyMethod(controller, request, callback) |
| 215 """ |
| 216 |
| 217 def CallMethod(self, method_descriptor, rpc_controller, |
| 218 request, response_class, done): |
| 219 """Calls the method identified by the descriptor. |
| 220 |
| 221 Call the given method of the remote service. The signature of this |
| 222 procedure looks the same as Service.CallMethod(), but the requirements |
| 223 are less strict in one important way: the request object doesn't have to |
| 224 be of any specific class as long as its descriptor is method.input_type. |
| 225 """ |
| 226 raise NotImplementedError |
OLD | NEW |