Class Call<V>
- Type Parameters:
V
- the success type, typically not null except whenV
is Void.
- All Implemented Interfaces:
Cloneable
- Direct Known Subclasses:
Call.Base
synchronously
or asynchronously
. At any time, from any thread, you
can call cancel(), which might stop an in-flight request or prevent one from
occurring.
Implementations should prepare a call such that there's little or no likelihood of late
runtime exceptions. For example, if the call is to get a trace, the call to listSpans
should propagate input errors vs delay them until a call to execute() or
enqueue(Callback).
Ex.
// Any translation of an input request to remote parameters should happen here, and any related
// errors should propagate here.
Call<List<List<Span>>> listTraces = spanStore.listTraces(request);
// When this executes, it should simply run the remote request.
List<Span> trace = getTraceCall.execute();
An instance of call cannot be invoked more than once, but you can clone() an instance if you need to replay the call. There is no relationship between a call and a number of remote requests. For example, an implementation that stores spans may make hundreds of remote requests, possibly retrying on your behalf.
This type owes its design to retrofit2.Call
, which is nearly the same, except limited
to HTTP transports.
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
static interface
static interface
static interface
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionabstract void
cancel()
Requests to cancel this call, even if some implementations may not support it.clone()
Returns a copy of this object, so you can make an identical follow-up request.static <V> Call<V>
create
(V v) Returns a completed call which has the supplied value.abstract void
Invokes a request asynchronously, signaling thecallback
when complete.abstract V
execute()
Invokes a request, returning a success value or propagating an error to the caller.final <R> Call<R>
flatMap
(Call.FlatMapper<V, R> flatMapper) Maps the result of this call into another, as defined by theflatMapper
function.handleError
(Call.ErrorHandler<V> errorHandler) Returns a call which can attempt to resolve an exception.abstract boolean
Returns true if cancel() was called.final <R> Call<R>
map
(Call.Mapper<V, R> mapper) Maps the result of this call into a different shape, as defined by themapper
function.static void
-
Constructor Details
-
Call
public Call()
-
-
Method Details
-
create
Returns a completed call which has the supplied value. This is useful when input parameters imply there's no call needed. For example, an empty input might always result in an empty output. -
emptyList
-
map
Maps the result of this call into a different shape, as defined by themapper
function. This is used to convert values from one type to another. For example, you could use this to convert between zipkin v1 and v2 span format.getTracesV1Call = getTracesV2Call.map(traces -> v2TracesConverter);
This method intends to be used for chaining. That means "this" instance should be discarded in favor of the result of this method.
-
flatMap
Maps the result of this call into another, as defined by theflatMapper
function. This is used to chain two remote calls together. For example, you could use this to chain a list IDs call to a get by IDs call.
Cancelation propagates to the mapped call.getTracesCall = getIdsCall.flatMap(ids -> getTraces(ids)); // this would now invoke the chain traces = getTracesCall.enqueue(tracesCallback);
This method intends to be used for chaining. That means "this" instance should be discarded in favor of the result of this method.
-
handleError
Returns a call which can attempt to resolve an exception. This is useful when a remote call returns an error when a resource is not found.Here's an example of coercing 404 to empty:
call.handleError((error, callback) -> { if (error instanceof HttpException && ((HttpException) error).code == 404) { callback.onSuccess(Collections.emptyList()); } else { callback.onError(error); } });
-
propagateIfFatal
-
execute
Invokes a request, returning a success value or propagating an error to the caller. Invoking this more than once will result in an error. To repeat a call, make a copy with clone().Eventhough this is a blocking call, implementations may honor calls to cancel() from a different thread.
- Returns:
- a success value. Null is unexpected, except when
V
is Void. - Throws:
IOException
-
enqueue
Invokes a request asynchronously, signaling thecallback
when complete. Invoking this more than once will result in an error. To repeat a call, make a copy with clone(). -
cancel
public abstract void cancel()Requests to cancel this call, even if some implementations may not support it. For example, a blocking call is sometimes not cancelable. -
isCanceled
public abstract boolean isCanceled()Returns true if cancel() was called.Calls can fail before being canceled, so true does always mean cancelation caused a call to fail. That said, successful cancellation does result in a failure.
-
clone
Returns a copy of this object, so you can make an identical follow-up request.
-