public interface RpcController
An RpcController
mediates a single method call. The primary
purpose of the controller is to provide a way to manipulate settings
specific to the RPC implementation and to find out about RPC-level errors.
Starting with version 2.3.0, RPC implementations should not try to build on this, but should instead provide code generator plugins which generate code specific to the particular RPC implementation. This way the generated code can be more appropriate for the implementation in use and can avoid unnecessary layers of indirection.
The methods provided by the RpcController
interface are intended
to be a "least common denominator" set of features which we expect all
implementations to support. Specific implementations may provide more
advanced features (e.g. deadline propagation).
Modifier and Type | Method and Description |
---|---|
String |
errorText()
If
failed() is true , returns a human-readable description
of the error. |
boolean |
failed()
After a call has finished, returns true if the call failed.
|
boolean |
isCanceled()
If
true , indicates that the client canceled the RPC, so the server
may as well give up on replying to it. |
void |
notifyOnCancel(RpcCallback<Object> callback)
Asks that the given callback be called when the RPC is canceled.
|
void |
reset()
Resets the RpcController to its initial state so that it may be reused in
a new call.
|
void |
setFailed(String reason)
Causes
failed() to return true on the client side. |
void |
startCancel()
Advises the RPC system that the caller desires that the RPC call be
canceled.
|
void reset()
boolean failed()
failed()
most only be called on the client side, and must not be called before a
call has finished.String errorText()
failed()
is true
, returns a human-readable description
of the error.void startCancel()
void setFailed(String reason)
failed()
to return true on the client side. reason
will be incorporated into the message returned by errorText()
.
If you find you need to return machine-readable information about
failures, you should incorporate it into your response protocol buffer
and should NOT call setFailed()
.boolean isCanceled()
true
, indicates that the client canceled the RPC, so the server
may as well give up on replying to it. This method must be called on the
server side only. The server should still call the final "done" callback.void notifyOnCancel(RpcCallback<Object> callback)
null
. The
callback will always be called exactly once. If the RPC completes without
being canceled, the callback will be called after completion. If the RPC
has already been canceled when NotifyOnCancel() is called, the callback
will be called immediately.
notifyOnCancel()
must be called no more than once per request.
It must be called on the server side only.
Copyright © 2008–2015 Google. All rights reserved.