Package zipkin2

Class Call<V>

  • Type Parameters:
    V - the success type, typically not null except when V is Void.
    All Implemented Interfaces:
    java.lang.Cloneable
    Direct Known Subclasses:
    Call.Base
    public abstract class Call<V>
extends java.lang.Object
implements java.lang.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 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<java.util.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​(java.lang.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<java.util.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​(java.lang.Throwable t)

      • execute

        public abstract V execute()
                   throws java.io.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:
        java.io.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 java.lang.Object