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