Package 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.

  • Constructor Details

    • Call

      public Call()

  • Method Details

    • 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