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 // Author: kenton@google.com (Kenton Varda)
32 //  Based on original Protocol Buffers design by
33 //  Sanjay Ghemawat, Jeff Dean, and others.
34 //
35 // DEPRECATED:  This module declares the abstract interfaces underlying proto2
36 // RPC services.  These are intented to be independent of any particular RPC
37 // implementation, so that proto2 services can be used on top of a variety
38 // of implementations.  Starting with version 2.3.0, RPC implementations should
39 // not try to build on these, but should instead provide code generator plugins
40 // which generate code specific to the particular RPC implementation.  This way
41 // the generated code can be more appropriate for the implementation in use
42 // and can avoid unnecessary layers of indirection.
43 //
44 //
45 // When you use the protocol compiler to compile a service definition, it
46 // generates two classes:  An abstract interface for the service (with
47 // methods matching the service definition) and a "stub" implementation.
48 // A stub is just a type-safe wrapper around an RpcChannel which emulates a
49 // local implementation of the service.
50 //
51 // For example, the service definition:
52 //   service MyService {
53 //     rpc Foo(MyRequest) returns(MyResponse);
54 //   }
55 // will generate abstract interface "MyService" and class "MyService::Stub".
56 // You could implement a MyService as follows:
57 //   class MyServiceImpl : public MyService {
58 //    public:
59 //     MyServiceImpl() {}
60 //     ~MyServiceImpl() {}
61 //
62 //     // implements MyService ---------------------------------------
63 //
64 //     void Foo(google::protobuf::RpcController* controller,
65 //              const MyRequest* request,
66 //              MyResponse* response,
67 //              Closure* done) {
68 //       // ... read request and fill in response ...
69 //       done->Run();
70 //     }
71 //   };
72 // You would then register an instance of MyServiceImpl with your RPC server
73 // implementation.  (How to do that depends on the implementation.)
74 //
75 // To call a remote MyServiceImpl, first you need an RpcChannel connected to it.
76 // How to construct a channel depends, again, on your RPC implementation.
77 // Here we use a hypothentical "MyRpcChannel" as an example:
78 //   MyRpcChannel channel("rpc:hostname:1234/myservice");
79 //   MyRpcController controller;
80 //   MyServiceImpl::Stub stub(&channel);
81 //   FooRequest request;
82 //   FooRespnose response;
83 //
84 //   // ... fill in request ...
85 //
86 //   stub.Foo(&controller, request, &response, NewCallback(HandleResponse));
87 //
88 // On Thread-Safety:
89 //
90 // Different RPC implementations may make different guarantees about what
91 // threads they may run callbacks on, and what threads the application is
92 // allowed to use to call the RPC system.  Portable software should be ready
93 // for callbacks to be called on any thread, but should not try to call the
94 // RPC system from any thread except for the ones on which it received the
95 // callbacks.  Realistically, though, simple software will probably want to
96 // use a single-threaded RPC system while high-end software will want to
97 // use multiple threads.  RPC implementations should provide multiple
98 // choices.
99 
100 #ifndef GOOGLE_PROTOBUF_SERVICE_H__
101 #define GOOGLE_PROTOBUF_SERVICE_H__
102 
103 #include <string>
104 #include <google/protobuf/stubs/common.h>
105 
106 namespace google {
107 namespace protobuf {
108 
109 // Defined in this file.
110 class Service;
111 class RpcController;
112 class RpcChannel;
113 
114 // Defined in other files.
115 class Descriptor;            // descriptor.h
116 class ServiceDescriptor;     // descriptor.h
117 class MethodDescriptor;      // descriptor.h
118 class Message;               // message.h
119 
120 // Abstract base interface for protocol-buffer-based RPC services.  Services
121 // themselves are abstract interfaces (implemented either by servers or as
122 // stubs), but they subclass this base interface.  The methods of this
123 // interface can be used to call the methods of the Service without knowing
124 // its exact type at compile time (analogous to Reflection).
125 class LIBPROTOBUF_EXPORT Service {
126  public:
Service()127   inline Service() {}
128   virtual ~Service();
129 
130   // When constructing a stub, you may pass STUB_OWNS_CHANNEL as the second
131   // parameter to the constructor to tell it to delete its RpcChannel when
132   // destroyed.
133   enum ChannelOwnership {
134     STUB_OWNS_CHANNEL,
135     STUB_DOESNT_OWN_CHANNEL
136   };
137 
138   // Get the ServiceDescriptor describing this service and its methods.
139   virtual const ServiceDescriptor* GetDescriptor() = 0;
140 
141   // Call a method of the service specified by MethodDescriptor.  This is
142   // normally implemented as a simple switch() that calls the standard
143   // definitions of the service's methods.
144   //
145   // Preconditions:
146   // * method->service() == GetDescriptor()
147   // * request and response are of the exact same classes as the objects
148   //   returned by GetRequestPrototype(method) and
149   //   GetResponsePrototype(method).
150   // * After the call has started, the request must not be modified and the
151   //   response must not be accessed at all until "done" is called.
152   // * "controller" is of the correct type for the RPC implementation being
153   //   used by this Service.  For stubs, the "correct type" depends on the
154   //   RpcChannel which the stub is using.  Server-side Service
155   //   implementations are expected to accept whatever type of RpcController
156   //   the server-side RPC implementation uses.
157   //
158   // Postconditions:
159   // * "done" will be called when the method is complete.  This may be
160   //   before CallMethod() returns or it may be at some point in the future.
161   // * If the RPC succeeded, "response" contains the response returned by
162   //   the server.
163   // * If the RPC failed, "response"'s contents are undefined.  The
164   //   RpcController can be queried to determine if an error occurred and
165   //   possibly to get more information about the error.
166   virtual void CallMethod(const MethodDescriptor* method,
167                           RpcController* controller,
168                           const Message* request,
169                           Message* response,
170                           Closure* done) = 0;
171 
172   // CallMethod() requires that the request and response passed in are of a
173   // particular subclass of Message.  GetRequestPrototype() and
174   // GetResponsePrototype() get the default instances of these required types.
175   // You can then call Message::New() on these instances to construct mutable
176   // objects which you can then pass to CallMethod().
177   //
178   // Example:
179   //   const MethodDescriptor* method =
180   //     service->GetDescriptor()->FindMethodByName("Foo");
181   //   Message* request  = stub->GetRequestPrototype (method)->New();
182   //   Message* response = stub->GetResponsePrototype(method)->New();
183   //   request->ParseFromString(input);
184   //   service->CallMethod(method, *request, response, callback);
185   virtual const Message& GetRequestPrototype(
186     const MethodDescriptor* method) const = 0;
187   virtual const Message& GetResponsePrototype(
188     const MethodDescriptor* method) const = 0;
189 
190  private:
191   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(Service);
192 };
193 
194 // An RpcController mediates a single method call.  The primary purpose of
195 // the controller is to provide a way to manipulate settings specific to the
196 // RPC implementation and to find out about RPC-level errors.
197 //
198 // The methods provided by the RpcController interface are intended to be a
199 // "least common denominator" set of features which we expect all
200 // implementations to support.  Specific implementations may provide more
201 // advanced features (e.g. deadline propagation).
202 class LIBPROTOBUF_EXPORT RpcController {
203  public:
RpcController()204   inline RpcController() {}
205   virtual ~RpcController();
206 
207   // Client-side methods ---------------------------------------------
208   // These calls may be made from the client side only.  Their results
209   // are undefined on the server side (may crash).
210 
211   // Resets the RpcController to its initial state so that it may be reused in
212   // a new call.  Must not be called while an RPC is in progress.
213   virtual void Reset() = 0;
214 
215   // After a call has finished, returns true if the call failed.  The possible
216   // reasons for failure depend on the RPC implementation.  Failed() must not
217   // be called before a call has finished.  If Failed() returns true, the
218   // contents of the response message are undefined.
219   virtual bool Failed() const = 0;
220 
221   // If Failed() is true, returns a human-readable description of the error.
222   virtual string ErrorText() const = 0;
223 
224   // Advises the RPC system that the caller desires that the RPC call be
225   // canceled.  The RPC system may cancel it immediately, may wait awhile and
226   // then cancel it, or may not even cancel the call at all.  If the call is
227   // canceled, the "done" callback will still be called and the RpcController
228   // will indicate that the call failed at that time.
229   virtual void StartCancel() = 0;
230 
231   // Server-side methods ---------------------------------------------
232   // These calls may be made from the server side only.  Their results
233   // are undefined on the client side (may crash).
234 
235   // Causes Failed() to return true on the client side.  "reason" will be
236   // incorporated into the message returned by ErrorText().  If you find
237   // you need to return machine-readable information about failures, you
238   // should incorporate it into your response protocol buffer and should
239   // NOT call SetFailed().
240   virtual void SetFailed(const string& reason) = 0;
241 
242   // If true, indicates that the client canceled the RPC, so the server may
243   // as well give up on replying to it.  The server should still call the
244   // final "done" callback.
245   virtual bool IsCanceled() const = 0;
246 
247   // Asks that the given callback be called when the RPC is canceled.  The
248   // callback will always be called exactly once.  If the RPC completes without
249   // being canceled, the callback will be called after completion.  If the RPC
250   // has already been canceled when NotifyOnCancel() is called, the callback
251   // will be called immediately.
252   //
253   // NotifyOnCancel() must be called no more than once per request.
254   virtual void NotifyOnCancel(Closure* callback) = 0;
255 
256  private:
257   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(RpcController);
258 };
259 
260 // Abstract interface for an RPC channel.  An RpcChannel represents a
261 // communication line to a Service which can be used to call that Service's
262 // methods.  The Service may be running on another machine.  Normally, you
263 // should not call an RpcChannel directly, but instead construct a stub Service
264 // wrapping it.  Example:
265 //   RpcChannel* channel = new MyRpcChannel("remotehost.example.com:1234");
266 //   MyService* service = new MyService::Stub(channel);
267 //   service->MyMethod(request, &response, callback);
268 class LIBPROTOBUF_EXPORT RpcChannel {
269  public:
RpcChannel()270   inline RpcChannel() {}
271   virtual ~RpcChannel();
272 
273   // Call the given method of the remote service.  The signature of this
274   // procedure looks the same as Service::CallMethod(), but the requirements
275   // are less strict in one important way:  the request and response objects
276   // need not be of any specific class as long as their descriptors are
277   // method->input_type() and method->output_type().
278   virtual void CallMethod(const MethodDescriptor* method,
279                           RpcController* controller,
280                           const Message* request,
281                           Message* response,
282                           Closure* done) = 0;
283 
284  private:
285   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(RpcChannel);
286 };
287 
288 }  // namespace protobuf
289 
290 }  // namespace google
291 #endif  // GOOGLE_PROTOBUF_SERVICE_H__
292