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 aCaravanHttpClient
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
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) - select only specific parts of the JSON tree with a JsonPath expression (using
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description JsonPipeline
addCachePoint(CacheStrategy strategy)
Makes the result of the current pipeline cacheable.JsonPipeline
applyAction(JsonPipelineAction action)
Applies an action on this pipeline, specifying an algorithm by the implementation ofJsonPipelineAction
.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.JsonPipeline
collect(String jsonPath)
Extracts multiple properties (or individual entries from a property array!) from the pipeline's response by specifying a JSONPath expression.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.JsonPipeline
extract(String jsonPath)
Extracts a single (first) property from the pipeline's response by specifying a JSONPath expression.JsonPipeline
extract(String jsonPath, String targetProperty)
Extracts a single (first) property from the pipeline's response by specifying a JSONPath expression.String
getDescriptor()
Provides a string representation of all the actions executed by this pipeline.rx.Observable<com.fasterxml.jackson.databind.JsonNode>
getJsonOutput()
Subscribes asynchronous client to the JSON payload of the pipeline.rx.Observable<JsonPipelineOutput>
getOutput()
Subscribes asynchronous client to the full pipeline output that consists of aJsonNode
payload and some additional metadata.io.wcm.caravan.common.performance.PerformanceMetrics
getPerformanceMetrics()
List<io.wcm.caravan.io.http.request.CaravanHttpRequest>
getRequests()
SortedSet<String>
getSourceServices()
rx.Observable<String>
getStringOutput()
Subscribes asynchronous client to the serialized payload of the pipeline.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.JsonPipeline
merge(JsonPipeline secondarySource)
Merges/Zips the JSON response objects of this pipeline and another pipeline, specifying by secondarySource parameter.JsonPipeline
merge(JsonPipeline secondarySource, String targetProperty)
Merges/Zips the JSON response objects of this pipeline and another pipeline, specifying by secondarySource parameter.
-
-
-
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 expressionstatusCode
- the appropriate status code to send to the client if the assumption failsmsg
- 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 objecttargetProperty
- 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 objecttargetProperty
- 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 mergedtargetProperty
- 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 ofJsonPipelineAction
.- 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 aJsonNode
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
orArrayNode
) 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)
-
-