Class Call<V>
- java.lang.Object
-
- zipkin2.Call<V>
-
- Type Parameters:
V
- the success type, typically not null except whenV
is Void.
- All Implemented Interfaces:
Cloneable
- Direct Known Subclasses:
Call.Base
public abstract class Call<V> extends Object implements Cloneable
This captures a (usually remote) request and can be used once, eithersynchronously
orasynchronously
. 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
Nested Classes Modifier and Type Class Description static class
Call.Base<V>
static interface
Call.ErrorHandler<V>
static interface
Call.FlatMapper<V1,V2>
static interface
Call.Mapper<V1,V2>
-
Constructor Summary
Constructors Constructor Description Call()
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract void
cancel()
Requests to cancel this call, even if some implementations may not support it.abstract Call<V>
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.static <T> Call<List<T>>
emptyList()
abstract void
enqueue(Callback<V> callback)
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.<R> Call<R>
flatMap(Call.FlatMapper<V,R> flatMapper)
Maps the result of this call into another, as defined by theflatMapper
function.Call<V>
handleError(Call.ErrorHandler<V> errorHandler)
Returns a call which can attempt to resolve an exception.abstract boolean
isCanceled()
Returns true if cancel() was called.<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
propagateIfFatal(Throwable t)
-
-
-
Method Detail
-
create
public static <V> Call<V> create(V v)
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.
-
map
public 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. 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
public final <R> Call<R> flatMap(Call.FlatMapper<V,R> flatMapper)
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
public final Call<V> handleError(Call.ErrorHandler<V> errorHandler)
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
public static void propagateIfFatal(Throwable t)
-
execute
public abstract V execute() throws IOException
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
public abstract void enqueue(Callback<V> callback)
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.
-
-