codekingpro/portable-devtools

1# Protocol Buffers - Google's data interchange format2# Copyright 2008 Google Inc.  All rights reserved.3#4# Use of this source code is governed by a BSD-style5# license that can be found in the LICENSE file or at6# https://developers.google.com/open-source/licenses/bsd7 8"""DEPRECATED:  Declares the RPC service interfaces.9 10This module declares the abstract interfaces underlying proto2 RPC11services.  These are intended to be independent of any particular RPC12implementation, so that proto2 services can be used on top of a variety13of implementations.  Starting with version 2.3.0, RPC implementations should14not try to build on these, but should instead provide code generator plugins15which generate code specific to the particular RPC implementation.  This way16the generated code can be more appropriate for the implementation in use17and can avoid unnecessary layers of indirection.18"""19 20__author__ = 'petar@google.com (Petar Petrov)'21 22 23class RpcException(Exception):24  """Exception raised on failed blocking RPC method call."""25  pass26 27 28class Service(object):29 30  """Abstract base interface for protocol-buffer-based RPC services.31 32  Services themselves are abstract classes (implemented either by servers or as33  stubs), but they subclass this base interface. The methods of this34  interface can be used to call the methods of the service without knowing35  its exact type at compile time (analogous to the Message interface).36  """37 38  def GetDescriptor():39    """Retrieves this service's descriptor."""40    raise NotImplementedError41 42  def CallMethod(self, method_descriptor, rpc_controller,43                 request, done):44    """Calls a method of the service specified by method_descriptor.45 46    If "done" is None then the call is blocking and the response47    message will be returned directly.  Otherwise the call is asynchronous48    and "done" will later be called with the response value.49 50    In the blocking case, RpcException will be raised on error.51 52    Preconditions:53 54    * method_descriptor.service == GetDescriptor55    * request is of the exact same classes as returned by56      GetRequestClass(method).57    * After the call has started, the request must not be modified.58    * "rpc_controller" is of the correct type for the RPC implementation being59      used by this Service.  For stubs, the "correct type" depends on the60      RpcChannel which the stub is using.61 62    Postconditions:63 64    * "done" will be called when the method is complete.  This may be65      before CallMethod() returns or it may be at some point in the future.66    * If the RPC failed, the response value passed to "done" will be None.67      Further details about the failure can be found by querying the68      RpcController.69    """70    raise NotImplementedError71 72  def GetRequestClass(self, method_descriptor):73    """Returns the class of the request message for the specified method.74 75    CallMethod() requires that the request is of a particular subclass of76    Message. GetRequestClass() gets the default instance of this required77    type.78 79    Example:80      method = service.GetDescriptor().FindMethodByName("Foo")81      request = stub.GetRequestClass(method)()82      request.ParseFromString(input)83      service.CallMethod(method, request, callback)84    """85    raise NotImplementedError86 87  def GetResponseClass(self, method_descriptor):88    """Returns the class of the response message for the specified method.89 90    This method isn't really needed, as the RpcChannel's CallMethod constructs91    the response protocol message. It's provided anyway in case it is useful92    for the caller to know the response type in advance.93    """94    raise NotImplementedError95 96 97class RpcController(object):98 99  """An RpcController mediates a single method call.100 101  The primary purpose of the controller is to provide a way to manipulate102  settings specific to the RPC implementation and to find out about RPC-level103  errors. The methods provided by the RpcController interface are intended104  to be a "least common denominator" set of features which we expect all105  implementations to support.  Specific implementations may provide more106  advanced features (e.g. deadline propagation).107  """108 109  # Client-side methods below110 111  def Reset(self):112    """Resets the RpcController to its initial state.113 114    After the RpcController has been reset, it may be reused in115    a new call. Must not be called while an RPC is in progress.116    """117    raise NotImplementedError118 119  def Failed(self):120    """Returns true if the call failed.121 122    After a call has finished, returns true if the call failed.  The possible123    reasons for failure depend on the RPC implementation.  Failed() must not124    be called before a call has finished.  If Failed() returns true, the125    contents of the response message are undefined.126    """127    raise NotImplementedError128 129  def ErrorText(self):130    """If Failed is true, returns a human-readable description of the error."""131    raise NotImplementedError132 133  def StartCancel(self):134    """Initiate cancellation.135 136    Advises the RPC system that the caller desires that the RPC call be137    canceled.  The RPC system may cancel it immediately, may wait awhile and138    then cancel it, or may not even cancel the call at all.  If the call is139    canceled, the "done" callback will still be called and the RpcController140    will indicate that the call failed at that time.141    """142    raise NotImplementedError143 144  # Server-side methods below145 146  def SetFailed(self, reason):147    """Sets a failure reason.148 149    Causes Failed() to return true on the client side.  "reason" will be150    incorporated into the message returned by ErrorText().  If you find151    you need to return machine-readable information about failures, you152    should incorporate it into your response protocol buffer and should153    NOT call SetFailed().154    """155    raise NotImplementedError156 157  def IsCanceled(self):158    """Checks if the client cancelled the RPC.159 160    If true, indicates that the client canceled the RPC, so the server may161    as well give up on replying to it.  The server should still call the162    final "done" callback.163    """164    raise NotImplementedError165 166  def NotifyOnCancel(self, callback):167    """Sets a callback to invoke on cancel.168 169    Asks that the given callback be called when the RPC is canceled.  The170    callback will always be called exactly once.  If the RPC completes without171    being canceled, the callback will be called after completion.  If the RPC172    has already been canceled when NotifyOnCancel() is called, the callback173    will be called immediately.174 175    NotifyOnCancel() must be called no more than once per request.176    """177    raise NotImplementedError178 179 180class RpcChannel(object):181 182  """Abstract interface for an RPC channel.183 184  An RpcChannel represents a communication line to a service which can be used185  to call that service's methods.  The service may be running on another186  machine. Normally, you should not use an RpcChannel directly, but instead187  construct a stub {@link Service} wrapping it.  Example:188 189  Example:190    RpcChannel channel = rpcImpl.Channel("remotehost.example.com:1234")191    RpcController controller = rpcImpl.Controller()192    MyService service = MyService_Stub(channel)193    service.MyMethod(controller, request, callback)194  """195 196  def CallMethod(self, method_descriptor, rpc_controller,197                 request, response_class, done):198    """Calls the method identified by the descriptor.199 200    Call the given method of the remote service.  The signature of this201    procedure looks the same as Service.CallMethod(), but the requirements202    are less strict in one important way:  the request object doesn't have to203    be of any specific class as long as its descriptor is method.input_type.204    """205    raise NotImplementedError206