HystrixObservableCollapser (Hystrix Javadoc 1.4.3)

java.lang.Object
- com.netflix.hystrix.HystrixObservableCollapser<K,BatchReturnType,ResponseType,RequestArgumentType>

Type Parameters:
K - The key used to match BatchReturnType and RequestArgumentType
BatchReturnType - The type returned from the HystrixCommand that will be invoked on batch executions.
ResponseType - The type returned from this command.
RequestArgumentType - The type of the request argument. If multiple arguments are needed, wrap them in another object or a Tuple.

All Implemented Interfaces:

HystrixInvokable<ResponseType>, HystrixObservable<ResponseType>
```
public abstract class HystrixObservableCollapser<K,BatchReturnType,ResponseType,RequestArgumentType>
extends java.lang.Object
implements HystrixObservable<ResponseType>
```
Collapse multiple requests into a single HystrixCommand execution based on a time window and optionally a max batch size.
This allows an object model to have multiple calls to the command that execute/queue many times in a short period (milliseconds) and have them all get batched into a single backend call.
Typically the time window is something like 10ms give or take.
NOTE: Do NOT retain any state within instances of this class.
It must be stateless or else it will be non-deterministic because most instances are discarded while some are retained and become the "collapsers" for all the ones that are discarded.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`HystrixObservableCollapser.Scope` The scope of request collapsing.
`static class`	`HystrixObservableCollapser.Setter` Fluent interface for arguments to the `HystrixObservableCollapser` constructor.

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`HystrixObservableCollapser()` Collapser with default `HystrixCollapserKey` derived from the implementing class name and scoped to `HystrixObservableCollapser.Scope.REQUEST` and default configuration.
`protected`	`HystrixObservableCollapser(HystrixCollapserKey collapserKey)` Collapser scoped to `HystrixObservableCollapser.Scope.REQUEST` and default configuration.
`protected`	`HystrixObservableCollapser(HystrixObservableCollapser.Setter setter)` Construct a `HystrixObservableCollapser` with defined `HystrixObservableCollapser.Setter` that allows injecting property and strategy overrides and other optional arguments.

Method Summary

Methods
Modifier and Type	Method and Description
`protected abstract HystrixObservableCommand<BatchReturnType>`	`createCommand(java.util.Collection<HystrixCollapser.CollapsedRequest<ResponseType,RequestArgumentType>> requests)` Factory method to create a new `HystrixObservableCommand<BatchReturnType>` command object each time a batch needs to be executed.
`protected abstract rx.functions.Func1<BatchReturnType,K>`	`getBatchReturnTypeKeySelector()` Function that returns the key used for matching returned objects against request argument types.
`protected abstract rx.functions.Func1<BatchReturnType,ResponseType>`	`getBatchReturnTypeToResponseTypeMapper()` Function for mapping from BatchReturnType to ResponseType.
`protected java.lang.String`	`getCacheKey()` Key to be used for request caching.
`HystrixCollapserKey`	`getCollapserKey()` Key of the `HystrixObservableCollapser` used for properties, metrics, caches, reporting etc.
`HystrixCollapserMetrics`	`getMetrics()` Return the `HystrixCollapserMetrics` for this collapser
`abstract RequestArgumentType`	`getRequestArgument()` The request arguments to be passed to the `HystrixCommand`.
`protected abstract rx.functions.Func1<RequestArgumentType,K>`	`getRequestArgumentKeySelector()` Function that returns the key used for matching request arguments against returned objects.
`HystrixObservableCollapser.Scope`	`getScope()` Scope of collapsing.
`rx.Observable<ResponseType>`	`observe()` Used for asynchronous execution with a callback by subscribing to the `Observable`.
`protected abstract void`	`onMissingResponse(HystrixCollapser.CollapsedRequest<ResponseType,RequestArgumentType> r)` Invoked if a `HystrixCollapser.CollapsedRequest` in the batch does not have a response set on it.
`protected java.util.Collection<java.util.Collection<HystrixCollapser.CollapsedRequest<ResponseType,RequestArgumentType>>>`	`shardRequests(java.util.Collection<HystrixCollapser.CollapsedRequest<ResponseType,RequestArgumentType>> requests)` Override to split (shard) a batch of requests into multiple batches that will each call `createCommand` separately.
`rx.Observable<ResponseType>`	`toObservable()` A lazy `Observable` that will execute when subscribed to.
`rx.Observable<ResponseType>`	`toObservable(rx.Scheduler observeOn)` A lazy `Observable` that will execute when subscribed to.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - HystrixObservableCollapser
```
protected HystrixObservableCollapser()
```
    Collapser with default HystrixCollapserKey derived from the implementing class name and scoped to HystrixObservableCollapser.Scope.REQUEST and default configuration.
  - HystrixObservableCollapser
```
protected HystrixObservableCollapser(HystrixCollapserKey collapserKey)
```
    Collapser scoped to HystrixObservableCollapser.Scope.REQUEST and default configuration.
    
    Parameters:
    collapserKey - HystrixCollapserKey that identifies this collapser and provides the key used for retrieving properties, request caches, publishing metrics etc.
  - HystrixObservableCollapser
```
protected HystrixObservableCollapser(HystrixObservableCollapser.Setter setter)
```
    Construct a HystrixObservableCollapser with defined HystrixObservableCollapser.Setter that allows injecting property and strategy overrides and other optional arguments.
    Null values will result in the default being used.
    
    Parameters:
    setter - Fluent interface for constructor arguments
- Method Detail
  - getCollapserKey
```
public HystrixCollapserKey getCollapserKey()
```
    Key of the HystrixObservableCollapser used for properties, metrics, caches, reporting etc.
    
    Returns:
    HystrixCollapserKey identifying this HystrixObservableCollapser instance
  - getScope
```
public HystrixObservableCollapser.Scope getScope()
```
    Scope of collapsing.
    - REQUEST: Requests within the scope of a HystrixRequestContext will be collapsed.
      Typically this means that requests within a single user-request (ie. HTTP request) are collapsed. No interaction with other user requests. 1 queue per user request.
    - GLOBAL: Requests from any thread (ie. all HTTP requests) within the JVM will be collapsed. 1 queue for entire app.
    Default: HystrixObservableCollapser.Scope.REQUEST (defined via constructor)
    Returns:
    HystrixObservableCollapser.Scope that collapsing should be performed within.
  - getMetrics
```
public HystrixCollapserMetrics getMetrics()
```
    Return the HystrixCollapserMetrics for this collapser
    
    Returns:
    HystrixCollapserMetrics for this collapser
  - getRequestArgument
```
public abstract RequestArgumentType getRequestArgument()
```
    The request arguments to be passed to the HystrixCommand.
    Typically this means to take the argument(s) provided to the constructor and return it here.
    If there are multiple arguments that need to be bundled, create a single object to contain them, or use a Tuple.
    
    Returns:
    RequestArgumentType
  - createCommand
```
protected abstract HystrixObservableCommand<BatchReturnType> createCommand(java.util.Collection<HystrixCollapser.CollapsedRequest<ResponseType,RequestArgumentType>> requests)
```
    Factory method to create a new HystrixObservableCommand<BatchReturnType> command object each time a batch needs to be executed.
    Do not return the same instance each time. Return a new instance on each invocation.
    Process the 'requests' argument into the arguments the command object needs to perform its work.
    If a batch or requests needs to be split (sharded) into multiple commands, see HystrixObservableCollapser.shardRequests(java.util.Collection<com.netflix.hystrix.HystrixCollapser.CollapsedRequest<ResponseType, RequestArgumentType>>)
    IMPLEMENTATION NOTE: Be fast (ie. <1ms) in this method otherwise it can block the Timer from executing subsequent batches. Do not do any processing beyond constructing the command and returning it.
    
    Parameters:
    requests - Collection<CollapsedRequest<ResponseType, RequestArgumentType>> containing HystrixCollapser.CollapsedRequest objects containing the arguments of each request collapsed in this batch.
    
    Returns:
    HystrixObservableCommand<BatchReturnType> which when executed will retrieve results for the batch of arguments as found in the Collection of HystrixCollapser.CollapsedRequest objects
  - shardRequests
```
protected java.util.Collection<java.util.Collection<HystrixCollapser.CollapsedRequest<ResponseType,RequestArgumentType>>> shardRequests(java.util.Collection<HystrixCollapser.CollapsedRequest<ResponseType,RequestArgumentType>> requests)
```
    Override to split (shard) a batch of requests into multiple batches that will each call createCommand separately.
    The purpose of this is to allow collapsing to work for services that have sharded backends and batch executions that need to be shard-aware.
    For example, a batch of 100 requests could be split into 4 different batches sharded on name (ie. a-g, h-n, o-t, u-z) that each result in a separate HystrixCommand being created and executed for them.
    By default this method does nothing to the Collection and is a pass-thru.
    
    Parameters:
    requests - Collection<CollapsedRequest<ResponseType, RequestArgumentType>> containing HystrixCollapser.CollapsedRequest objects containing the arguments of each request collapsed in this batch.
    
    Returns:
    Collection of Collection<CollapsedRequest<ResponseType, RequestArgumentType>> objects sharded according to business rules.
    The CollapsedRequest instances should not be modified or wrapped as the CollapsedRequest instance object contains state information needed to complete the execution.
  - getBatchReturnTypeKeySelector
```
protected abstract rx.functions.Func1<BatchReturnType,K> getBatchReturnTypeKeySelector()
```
    Function that returns the key used for matching returned objects against request argument types.
    The key returned from this function should match up with the key returned from HystrixObservableCollapser.getRequestArgumentKeySelector();
    
    Returns:
    key selector function
  - getRequestArgumentKeySelector
```
protected abstract rx.functions.Func1<RequestArgumentType,K> getRequestArgumentKeySelector()
```
    Function that returns the key used for matching request arguments against returned objects.
    The key returned from this function should match up with the key returned from HystrixObservableCollapser.getBatchReturnTypeKeySelector();
    
    Returns:
    key selector function
  - onMissingResponse
```
protected abstract void onMissingResponse(HystrixCollapser.CollapsedRequest<ResponseType,RequestArgumentType> r)
```
    Invoked if a HystrixCollapser.CollapsedRequest in the batch does not have a response set on it.
    This allows setting an exception (via HystrixCollapser.CollapsedRequest.setException(Exception)) or a fallback response (via HystrixCollapser.CollapsedRequest.setResponse(Object)).
    
    Parameters:
    r - HystrixCollapser.CollapsedRequest that needs a response or exception set on it.
  - getBatchReturnTypeToResponseTypeMapper
```
protected abstract rx.functions.Func1<BatchReturnType,ResponseType> getBatchReturnTypeToResponseTypeMapper()
```
    Function for mapping from BatchReturnType to ResponseType.
    Often these two types are exactly the same so it's just a pass-thru.
    
    Returns:
    function for mapping from BatchReturnType to ResponseType
  - observe
```
public rx.Observable<ResponseType> observe()
```
    Used for asynchronous execution with a callback by subscribing to the Observable.
    This eagerly starts execution the same as HystrixCollapser.queue() and HystrixCollapser.execute(). A lazy Observable can be obtained from HystrixObservableCollapser.toObservable().
    Callback Scheduling
    - When using HystrixCommandProperties.ExecutionIsolationStrategy.THREAD this defaults to using Schedulers.computation() for callbacks.
    - When using HystrixCommandProperties.ExecutionIsolationStrategy.SEMAPHORE this defaults to using Schedulers.immediate() for callbacks.
    Use HystrixObservableCollapser.toObservable(rx.Scheduler) to schedule the callback differently.
    See https://github.com/Netflix/RxJava/wiki for more information.
    Specified by:
    
    observe in interface HystrixObservable<ResponseType>
    
    Returns:
    Observable<R> that executes and calls back with the result of of HystrixCommand<BatchReturnType> execution after mapping the <BatchReturnType> into <ResponseType>
  - toObservable
```
public rx.Observable<ResponseType> toObservable()
```
    A lazy Observable that will execute when subscribed to.
    Callback Scheduling
    - When using HystrixCommandProperties.ExecutionIsolationStrategy.THREAD this defaults to using Schedulers.computation() for callbacks.
    - When using HystrixCommandProperties.ExecutionIsolationStrategy.SEMAPHORE this defaults to using Schedulers.immediate() for callbacks.
    See https://github.com/Netflix/RxJava/wiki for more information.
    Specified by:
    
    toObservable in interface HystrixObservable<ResponseType>
    
    Returns:
    Observable<R> that lazily executes and calls back with the result of of HystrixCommand<BatchReturnType> execution after mapping the <BatchReturnType> into <ResponseType>
  - toObservable
```
public rx.Observable<ResponseType> toObservable(rx.Scheduler observeOn)
```
    A lazy Observable that will execute when subscribed to.
    See https://github.com/Netflix/RxJava/wiki for more information.
    
    Parameters:
    observeOn - The Scheduler to execute callbacks on.
    
    Returns:
    Observable<R> that lazily executes and calls back with the result of of HystrixCommand<BatchReturnType> execution after mapping the <BatchReturnType> into <ResponseType>
  - getCacheKey
```
protected java.lang.String getCacheKey()
```
    Key to be used for request caching.
    By default this returns null which means "do not cache".
    To enable caching override this method and return a string key uniquely representing the state of a command instance.
    If multiple command instances in the same request scope match keys then only the first will be executed and all others returned from cache.
    
    Returns:
    String cacheKey or null if not to cache

Hystrix: Latency and Fault Tolerance for Distributed Systems

Class HystrixObservableCollapser<K,BatchReturnType,ResponseType,RequestArgumentType>

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

HystrixObservableCollapser

HystrixObservableCollapser

HystrixObservableCollapser

Method Detail

getCollapserKey

getScope

getMetrics

getRequestArgument

createCommand

shardRequests

getBatchReturnTypeKeySelector

getRequestArgumentKeySelector

onMissingResponse

getBatchReturnTypeToResponseTypeMapper

observe

toObservable

toObservable

getCacheKey