Stay organized with collections
Save and categorize content based on your preferences.
publicinterfaceRpcController
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).
Methods
errorText()
publicabstractStringerrorText()
If failed() is true, returns a human-readable description of the error.
After a call has finished, returns true if the call failed. The possible reasons for failure
depend on the RPC implementation. failed() most only be called on the client side, and
must not be called before a call has finished.
If 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.
Asks that the given callback be called when the RPC is canceled. The parameter passed to the
callback will always be 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.
Resets the RpcController to its initial state so that it may be reused in a new call. This can
be called from the client side only. It must not be called while an RPC is in progress.
setFailed(String reason)
publicabstractvoidsetFailed(Stringreason)
Causes 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().
Advises the RPC system that the caller desires that the RPC call be canceled. The RPC system
may cancel it immediately, may wait awhile and then cancel it, or may not even cancel the call
at all. If the call is canceled, the "done" callback will still be called and the RpcController
will indicate that the call failed at that time.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[],[],null,["# Interface RpcController (3.19.4)\n\n public interface RpcController\n\nAn `RpcController` mediates a single method call. The primary purpose of the controller is\nto provide a way to manipulate settings specific to the RPC implementation and to find out about\nRPC-level errors.\n\nStarting with version 2.3.0, RPC implementations should not try to build on this, but should\ninstead provide code generator plugins which generate code specific to the particular RPC\nimplementation. This way the generated code can be more appropriate for the implementation in use\nand can avoid unnecessary layers of indirection.\n\nThe methods provided by the `RpcController` interface are intended to be a \"least common\ndenominator\" set of features which we expect all implementations to support. Specific\nimplementations may provide more advanced features (e.g. deadline propagation).\n\nMethods\n-------\n\n### errorText()\n\n public abstract String errorText()\n\nIf `failed()` is `true`, returns a human-readable description of the error.\n\n### failed()\n\n public abstract boolean failed()\n\nAfter a call has finished, returns true if the call failed. The possible reasons for failure\ndepend on the RPC implementation. `failed()` most only be called on the client side, and\nmust not be called before a call has finished.\n\n### isCanceled()\n\n public abstract boolean isCanceled()\n\nIf `true`, indicates that the client canceled the RPC, so the server may as well give up\non replying to it. This method must be called on the server side only. The server should still\ncall the final \"done\" callback.\n\n### notifyOnCancel(RpcCallback\\\u003cObject\\\u003e callback)\n\n public abstract void notifyOnCancel(RpcCallback\u003cObject\u003e callback)\n\nAsks that the given callback be called when the RPC is canceled. The parameter passed to the\ncallback will always be `null`. The callback will always be called exactly once. If the\nRPC completes without being canceled, the callback will be called after completion. If the RPC\nhas already been canceled when NotifyOnCancel() is called, the callback will be called\nimmediately.\n\n`notifyOnCancel()` must be called no more than once per request. It must be called on\nthe server side only.\n\n### reset()\n\n public abstract void reset()\n\nResets the RpcController to its initial state so that it may be reused in a new call. This can\nbe called from the client side only. It must not be called while an RPC is in progress.\n\n### setFailed(String reason)\n\n public abstract void setFailed(String reason)\n\nCauses `failed()` to return true on the client side. `reason` will be incorporated\ninto the message returned by `errorText()`. If you find you need to return\nmachine-readable information about failures, you should incorporate it into your response\nprotocol buffer and should NOT call `setFailed()`.\n\n### startCancel()\n\n public abstract void startCancel()\n\nAdvises the RPC system that the caller desires that the RPC call be canceled. The RPC system\nmay cancel it immediately, may wait awhile and then cancel it, or may not even cancel the call\nat all. If the call is canceled, the \"done\" callback will still be called and the RpcController\nwill indicate that the call failed at that time."]]
