zipkin2

Class Call<V>

java.lang.Object

zipkin2.Call<V>

Type Parameters:

V - the success type, typically not null except when V 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, either 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

Nested Classes

Modifier and Type	Class and 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 and Description
Call()

Method Summary

Modifier and Type	Method and 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 the callback 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 the flatMapper 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 the mapper function.
static void	propagateIfFatal(Throwable t)

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Call

public Call()

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.

emptyList

public static <T> Call<List<T>> emptyList()

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 the mapper 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 the flatMapper 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.

 getTracesCall = getIdsCall.flatMap(ids -> getTraces(ids));

 // this would now invoke the chain
 traces = getTracesCall.enqueue(tracesCallback);
 

Cancelation propagates to the mapped call.

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 the callback 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

public abstract Call<V> clone()

Returns a copy of this object, so you can make an identical follow-up request.

Overrides:

clone in class Object