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 Type	Method and Description
Exchange	aggregate(Exchange oldExchange, Exchange newExchange) 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.
default Exchange	aggregate(Exchange oldExchange, Exchange newExchange, Exchange inputExchange) Aggregates an old and new exchange together to create a single combined exchange.
default boolean	canPreComplete() Indicates if this aggregation strategy uses pre-completion mode.
default void	onCompletion(Exchange exchange) The aggregated Exchange has completed Important: This method must not throw any exceptions.
default void	onOptimisticLockFailure(Exchange oldExchange, Exchange newExchange) Callback when the aggregated Exchange fails to add in the OptimisticLockingAggregationRepository because of an OptimisticLockingAggregationRepository.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	timeout(Exchange exchange, int index, int total, long timeout) A timeout occurred.

Method Detail

aggregate

Exchange aggregate(Exchange oldExchange,
                   Exchange newExchange)

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

default Exchange aggregate(Exchange oldExchange,
                           Exchange newExchange,
                           Exchange inputExchange)

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 and Recipient List EIP supports this method with access to the input exchange. All other EIPs does not and uses the aggregate(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

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. This callback will only be called if canPreComplete() 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

default void onCompletion(Exchange exchange)

The aggregated Exchange has completed Important: This method must not throw any exceptions.

Parameters:

exchange - the current aggregated exchange, or the original Exchange if no aggregation has been done before the completion occurred

timeout

default void timeout(Exchange exchange,
                     int index,
                     int total,
                     long timeout)

A timeout occurred.

Important: This method must not throw any exceptions.

Parameters:

exchange - the current aggregated exchange, or the original Exchange if no aggregation has been done before the timeout occurred

index - the index, may be -1 if not possible to determine the index

total - the total, may be -1 if not possible to determine the total

timeout - the timeout value in millis, may be -1 if not possible to determine the timeout

onOptimisticLockFailure

default void onOptimisticLockFailure(Exchange oldExchange,
                                     Exchange newExchange)

Callback when the aggregated Exchange fails to add in the OptimisticLockingAggregationRepository because of an OptimisticLockingAggregationRepository.OptimisticLockingException.

Please note that when aggregating Exchange's to be careful not to modify and return the oldExchange from the aggregate(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 new newExchange or a completely new instance of Exchange. This is due to the nature of how the underlying ConcurrentHashMap performs CAS operations on the value identity.

See Also:

ConcurrentHashMap