Package io.wcm.caravan.pipeline

Interface JsonPipeline

  • @ProviderType
public interface JsonPipeline
    A pipeline aids consuming/orchestrating services to transform, merge and cache JSON responses from a CaravanHttpClient and allows to
    • select only specific parts of the JSON tree with a JsonPath expression (using collect(String, String))
    • merge all content of another pipeline into a new property of its own result document (using merge(JsonPipeline, String))
    • cache the original result, or the result of any transformation/aggregation step (using addCachePoint(CacheStrategy)
    • access the overall output either as a Jackson JsonNode, a JSON string, or as a type-mapped Java object
    Note that JsonPipeline's are immutable. None of the methods will alter the current instance, but instead will return a new instance with the desired behavior (and an updated descriptor that will be used to generate unique cache keys)

    • Method Detail

      • getDescriptor

        String getDescriptor()
        Provides a string representation of all the actions executed by this pipeline. Description is supposed to help in creation of understandable logging messages. It could be also used to generate cache keys. See sample of action description: "GET(serviceId/path)+SELECT($..someProperty into targetPeropty)"
        Returns:
        description of pipeline actions

      • getSourceServices

        SortedSet<String> getSourceServices()
        Returns:
        all logical service IDs that were used in generating the pipeline's result

      • getRequests

        List<io.wcm.caravan.io.http.request.CaravanHttpRequest> getRequests()
        Returns:
        all resilient HTTP requests involved in producing the pipeline's output

      • getPerformanceMetrics

        io.wcm.caravan.common.performance.PerformanceMetrics getPerformanceMetrics()
        Returns:
        pipeline performance metrics

      • assertExists

        JsonPipeline assertExists​(String jsonPath,
                          int statusCode,
                          String msg)
        Raises an exception in case, if expected content is not present in the actual JSON node of this pipeline.
        Parameters:
        jsonPath - a JSONPath expression
        statusCode - the appropriate status code to send to the client if the assumption fails
        msg - the expression to look for
        Returns:
        a pipeline that fails with a JsonPipelineInputException if no content is found at the given path

      • extract

        JsonPipeline extract​(String jsonPath)
        Extracts a single (first) property from the pipeline's response by specifying a JSONPath expression. An extraction result is saved as a single JSON property in the root node of the result JSON object.
        Parameters:
        jsonPath - a JSONPath expression that matches a single leaf in the source JSON object
        Returns:
        a new pipeline that will only emit a single JSON object with the extraction result

      • extract

        JsonPipeline extract​(String jsonPath,
                     String targetProperty)
        Extracts a single (first) property from the pipeline's response by specifying a JSONPath expression. An extraction result is saved as a single JSON property in a new node of the result JSON object and named by the targetProperty parameter.
        Parameters:
        jsonPath - a JSONPath expression that matches a single leaf in the source JSON object
        targetProperty - the name of the single property to save extraction results in a response JSON object
        Returns:
        a new pipeline that will only emit a single JSON object with the extraction result

      • collect

        JsonPipeline collect​(String jsonPath)
        Extracts multiple properties (or individual entries from a property array!) from the pipeline's response by specifying a JSONPath expression. An extraction result is saved as a JSON array in the root node of the result JSON object.
        Parameters:
        jsonPath - a JSONPath expression that can match multiple items in the source JSON object
        Returns:
        a new pipeline that will only emit a single JSON object with the extraction result

      • collect

        JsonPipeline collect​(String jsonPath,
                     String targetProperty)
        Extracts multiple properties (or individual entries from a property array!) from the pipeline's response by specifying a JSONPath expression. An extraction result is saved as a JSON array in a new node of the result JSON object and named by the targetProperty parameter.
        Parameters:
        jsonPath - a jsonPath expression that can match multiple items in the source JSON object
        targetProperty - the name of the single node to save extraction results in a response JSON object
        Returns:
        a new pipeline that will only emit a single JSON object with the extraction result

      • merge

        JsonPipeline merge​(JsonPipeline secondarySource)
        Merges/Zips the JSON response objects of this pipeline and another pipeline, specifying by secondarySource parameter. A merge result is a new JSON object, where the JSON object of this pipeline and the JSON object of the secondary source are saved on the root node level.
        Parameters:
        secondarySource - another pipeline that returns a single JSON object to be merged
        Returns:
        a new pipeline that will emit a single JSON object with the merge result

      • merge

        JsonPipeline merge​(JsonPipeline secondarySource,
                   String targetProperty)
        Merges/Zips the JSON response objects of this pipeline and another pipeline, specifying by secondarySource parameter. A merge result is a new JSON object, where the JSON object of this pipeline is saved on the root node level. The JSON object of the secondary source is saved as a new node in the result JSON object and named by the targetProperty parameter.
        Parameters:
        secondarySource - another pipeline that returns a single JSON object to be merged
        targetProperty - the name of the single node to save the content of the secondary source in merged JSON object
        Returns:
        a new pipeline that will emit a single JSON object with the merge result

      • applyAction

        JsonPipeline applyAction​(JsonPipelineAction action)
        Applies an action on this pipeline, specifying an algorithm by the implementation of JsonPipelineAction.
        Parameters:
        action - a JSON pipeline action, that provides the actual algorithm
        Returns:
        a new pipeline that emits the result of the action execution

      • addCachePoint

        JsonPipeline addCachePoint​(CacheStrategy strategy)
        Makes the result of the current pipeline cacheable.
        Parameters:
        strategy - - specifies details for the caching behavior
        Returns:
        a new cache-aware pipeline with the same response as the current pipeline

      • handleException

        JsonPipeline handleException​(JsonPipelineExceptionHandler exceptionHandler)
        Catches all exceptions from any of the previous pipeline steps, and passes them to the given exception handler function, together with a fallback content object that is initialized with the appropriate status code for the given exception, and the max-age value set to 0. Based on the type of the exception and the status code, the exception handler function can decide to return fallback content, rethrow the exception as it is, or wrap it in an exception with a more informative error message. JsonPipelineExceptionHandlers contains some common exception handling strategies for providing fallback content or rethrowing 404 and 50x errors.
        Parameters:
        exceptionHandler - the function to call when an exception is caught
        Returns:
        a new pipeline with the same descriptor but additional exception handling behaviour from the given function
        See Also:
        JsonPipelineExceptionHandlers

      • getOutput

        rx.Observable<JsonPipelineOutput> getOutput()
        Subscribes asynchronous client to the full pipeline output that consists of a JsonNode payload and some additional metadata. Any first subscription calls a pipeline to execute listed in it operations.
        Returns:
        an Observable that will emit a single JsonPipelineOutput

      • getJsonOutput

        rx.Observable<com.fasterxml.jackson.databind.JsonNode> getJsonOutput()
        Subscribes asynchronous client to the JSON payload of the pipeline. Use it for the subscription, if you're not interested in metadata. Any first subscription calls a pipeline to execute listed in it operations.
        Returns:
        an Observable that will emit a single JSON node (of type ObjectNode or ArrayNode) when the response has been fetched (and processed by all stages of the pipeline)

      • getStringOutput

        rx.Observable<String> getStringOutput()
        Subscribes asynchronous client to the serialized payload of the pipeline. Use it for the subscription, if you're not interested in metadata. Any first subscription calls a pipeline to execute listed in it operations.
        Returns:
        an Observable that will emit a single JSON String when the response has been fetched (and processed by all stages of the pipeline)