Package org.apache.camel
Interface AggregationStrategy
public interface AggregationStrategy
A strategy for aggregating two exchanges together into a single exchange.
On the first invocation of the
aggregate
method the oldExchange parameter is null. The reason is that we have not aggregated anything yet.
So its only the newExchange that has a value. Usually you just return the newExchange in this
situation. But you still have the power to decide what to do, for example you can do some alternation on the exchange
or remove some headers. And a more common use case is for instance to count some values from the body payload. That
could be to sum up a total amount etc.
Note that oldExchange may be null more than once when this strategy is throwing a
RuntimeException
and parallelProcessing is used. You can work around this behavior using
the stopOnAggregateException option.
It is possible that newExchange is null which could happen if there was no data possible to
acquire. Such as when using a PollEnricher to poll from a JMS queue which is empty and a timeout was set.
Important: In the aggregate method, do not create a new exchange instance to return, instead return either the old or
new exchange from the input parameters; favor returning the old exchange whenever possible.
Possible implementations include performing some kind of combining or delta processing, such as adding line items
together into an invoice or just using the newest exchange and removing old exchanges such as for state tracking or
market data prices; where old values are of little use.
If an implementation also implements Service
then any
EIP that allowing configuring a AggregationStrategy
will invoke the
Service.start()
and Service.stop()
to control the lifecycle aligned
with the EIP itself.
If an implementation also implements CamelContextAware
then any
EIP that allowing configuring a AggregationStrategy
will inject the
CamelContext
prior to using the aggregation strategy.-
Method Summary
Modifier and TypeMethodDescriptionAggregates an old and new exchange together to create a single combined exchangedefault Exchange
Aggregates an old and new exchange together to create a single combined exchange.default boolean
Indicates if this aggregation strategy uses pre-completion mode.default void
onCompletion
(Exchange exchange) The aggregatedExchange
has completed Important: This method must not throw any exceptions.default void
onCompletion
(Exchange exchange, Exchange inputExchange) The aggregatedExchange
has completed Important: This method must not throw any exceptions.default void
onOptimisticLockFailure
(Exchange oldExchange, Exchange newExchange) Callback when the aggregatedExchange
fails to add in theOptimisticLockingAggregationRepository
because of anOptimisticLockingAggregationRepository.OptimisticLockingException
.default boolean
preComplete
(Exchange oldExchange, Exchange newExchange) Determines if the aggregation should complete the current group, and start a new group, or the aggregation should continue using the current group.default void
A timeout occurred.
-
Method Details
-
aggregate
Aggregates an old and new exchange together to create a single combined exchange Important: In the aggregate method, do not create a new exchange instance to return, instead return either the old or new exchange from the input parameters; favor returning the old exchange whenever possible.- Parameters:
oldExchange
- the oldest exchange (is null on first aggregation as we only have the new exchange)newExchange
- the newest exchange (can be null if there was no data possible to acquire)- Returns:
- a combined composite of the two exchanges, return either the old or new exchange from the input parameters; favor returning the old exchange whenever possible)
-
aggregate
Aggregates an old and new exchange together to create a single combined exchange. Important: In the aggregate method, do not create a new exchange instance to return, instead return either the old or new exchange from the input parameters; favor returning the old exchange whenever possible. Important: Only Multicast, Recipient List, and Splitter EIP supports this method with access to the input exchange. All other EIPs does not and uses theaggregate(Exchange, Exchange)
method instead.- Parameters:
oldExchange
- the oldest exchange (is null on first aggregation as we only have the new exchange)newExchange
- the newest exchange (can be null if there was no data possible to acquire)inputExchange
- the input exchange (input to the EIP)- Returns:
- a combined composite of the two exchanges, return either the old or new exchange from the input parameters; favor returning the old exchange whenever possible)
-
canPreComplete
default boolean canPreComplete()Indicates if this aggregation strategy uses pre-completion mode.- Returns:
- true if this strategy uses pre-completion mode, or false otherwise.
-
preComplete
Determines if the aggregation should complete the current group, and start a new group, or the aggregation should continue using the current group. This callback will only be called ifcanPreComplete()
returns true.- Parameters:
oldExchange
- the oldest exchange (is null on first aggregation as we only have the new exchange)newExchange
- the newest exchange (can be null if there was no data possible to acquire)- Returns:
- true to complete current group and start a new group, or false to keep using current
-
onCompletion
The aggregatedExchange
has completed Important: This method must not throw any exceptions.- Parameters:
exchange
- the current aggregated exchange, or the originalExchange
if no aggregation has been done before the completion occurred
-
onCompletion
The aggregatedExchange
has completed Important: This method must not throw any exceptions.- Parameters:
exchange
- the current aggregated exchange, or the originalExchange
if no aggregation has been done before the completion occurredinputExchange
- the input exchange (input to the EIP)
-
timeout
A timeout occurred. Important: This method must not throw any exceptions.- Parameters:
exchange
- the current aggregated exchange, or the originalExchange
if no aggregation has been done before the timeout occurredindex
- the index, may be -1 if not possible to determine the indextotal
- the total, may be -1 if not possible to determine the totaltimeout
- the timeout value in millis, may be -1 if not possible to determine the timeout
-
onOptimisticLockFailure
Callback when the aggregatedExchange
fails to add in theOptimisticLockingAggregationRepository
because of anOptimisticLockingAggregationRepository.OptimisticLockingException
. Please note that when aggregatingExchange
's to be careful not to modify and return theoldExchange
from theaggregate(org.apache.camel.Exchange, org.apache.camel.Exchange)
method. If you are using the default MemoryAggregationRepository this will mean you have modified the value of an object already referenced/stored by the MemoryAggregationRepository. This makes it impossible for optimistic locking to work correctly with the MemoryAggregationRepository. You should instead return either the newnewExchange
or a completely new instance ofExchange
. This is due to the nature of how the underlyingConcurrentHashMap
performs CAS operations on the value identity.- See Also:
-