java.lang.Object
- com.broadleafcommerce.promotion.offer.service.engine.application.processor.DefaultItemOfferProcessor

All Implemented Interfaces:: ItemOfferProcessor

public class DefaultItemOfferProcessor
extends Object
implements ItemOfferProcessor

Author:: Chad Harchar (charchar)

Field Summary

Fields
Modifier and Type	Field	Description
`protected OrderAndItemOfferHelper`	`helper`
`protected PotentialSavingsCalculator`	`potentialSavingsCalculator`
`protected QualifierAndTargetMarker`	`qualifierAndTargetMarker`

Constructor Summary

Constructors
Constructor	Description
`DefaultItemOfferProcessor(PotentialSavingsCalculator potentialSavingsCalculator, QualifierAndTargetMarker qualifierAndTargetMarker, OrderAndItemOfferHelper helper, boolean isForFulfillment)`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`protected void`	`addFreeGiftsToResult(OfferProcessingContext context, ItemOfferPermutationResult result)`
`protected void`	`addOrderCodeToAdjustmentIfUsed(@NonNull Offer offer, @NonNull com.broadleafcommerce.promotion.offer.client.web.context.info.Adjustment adjustment, @NonNull Set<String> allOrderCodes)`	Adds an offer code to the given `Adjustment` if it is present on the order.
`protected void`	`applyAdjustments(EnhancedOrder order, CandidateItemOffer itemOffer)`
`protected void`	`applyCandidateOffers(EnhancedOrder order, List<CandidateItemOffer> candidateOffers)`
`protected void`	`applyFreeGift(EnhancedOrder order, CandidateItemOffer itemOffer)`	Builds and adds a `FreeGiftItem` to `EnhancedOrder.getFreeGiftItems()` based on `CandidateItemOffer.getCandidateQualifiersMap()` if the given `itemOffer` is a free gift offer.
`void`	`applyItemAdjustments(OfferProcessingContext context, ItemOfferPermutationResult result)`	For item processing, the adjustments are stored on `LineItemOfferDetail` records.
`protected void`	`applyItemOffer(EnhancedOrder order, CandidateItemOffer itemOffer)`
`protected void`	`applyItemQualifiersAndTargets(EnhancedOrder order, CandidateItemOffer itemOffer)`
`protected void`	`applyLineItemAdjustment(CandidateItemOffer itemOffer, LineItemOfferDetail offerDetail, OfferDiscount offerDiscount)`	Adds an `ItemOfferAdjustment` to the given `LineItemOfferDetail`.
`protected void`	`assertCandidateOffersNotNull(CandidateOffers candidateOffers)`
`protected void`	`assertCommonParamsNotNull(EnhancedOrder order, CandidateOffers candidateOffers)`
`protected com.broadleafcommerce.promotion.offer.client.web.context.info.Adjustment`	`buildAdjustmentForFreeGift(EnhancedOrder order, CandidateItemOffer itemOffer)`	Builds an `Adjustment` for a `FreeGiftItem`.
`protected com.broadleafcommerce.promotion.offer.client.web.context.info.FreeGiftItem`	`buildFreeGiftItem(Offer offer, int quantityToAdd, com.broadleafcommerce.promotion.offer.client.web.context.info.Adjustment adjustment)`	Builds a `FreeGiftItem` from the given `Offer`, quantity, and qualifier item ids.
`protected void`	`calculatePotentialSavings(EnhancedOrder order, List<CandidateItemOffer> candidateItemOffers)`
`protected javax.money.MonetaryAmount`	`calculatePriceForBundleRatio(LineItemOfferDetail detail)`
`protected boolean`	`canOfferBeApplied(EnhancedOrder order, CandidateItemOffer itemOffer, List<LineItemOfferDetail> itemDetails)`	Determines whether the `Offer` can be applied by making sure it is `combinable` and that all other offers applied to any `LineItems` are also combinable by checking their `EnhancedLineItem.offerDetails`.
`protected void`	`chooseSaleOrStandardAdjustments(EnhancedOrder order)`	Some `Offers` can only apply to the `EnhancedLineItem.getStandardPrice()`.
`protected void`	`clearStateBetweenPermutations(EnhancedOrder order, List<CandidateItemOffer> candidateOffers)`
`protected ItemOfferPermutationResult`	`computeOfferPermutationValue(OfferProcessingContext context, List<CandidateItemOffer> candidateItemOffers, OrderTotals orderTotals)`
`protected javax.money.MonetaryAmount`	`computeSaleAdjustmentValue(CandidateItemOffer itemOffer, LineItemOfferDetail offerDetail)`
`protected javax.money.MonetaryAmount`	`computeStandardAdjustmentValue(CandidateItemOffer itemOffer, LineItemOfferDetail offerDetail)`
`protected com.broadleafcommerce.promotion.offer.client.web.context.info.OfferItemDetail`	`createOfferItemDetail(CandidateItemOffer itemOffer, String itemId, int quantityPerUsage)`	Creates an `OfferItemDetail` based on the given fields.
`protected List<List<CandidateItemOffer>>`	`expandPermutations(List<CandidateItemOffer> itemOffers)`	This method takes a list of item offers that are compatible with each other and share the same combinability characteristics with other types like order offers and builds additional permutations that influence the order that the offers will be run.
`void`	`findBestItemOffersForPermutation(OfferProcessingContext context, CombinedTypesOfferPermutation ctop)`
`protected Optional<List<CandidateItemOffer>>`	`findBestPermutation(EnhancedOrder order, List<List<CandidateItemOffer>> permutations)`	Determines the best permutation by comparing the resulting total discounts of each permutations.
`protected List<CandidateItemOffer>`	`getCandidateItemOffers(OfferProcessingContext context)`
`protected javax.money.MonetaryAmount`	`getEstimatedFreeGiftValue(EnhancedOrder order, Offer offer)`
`protected int`	`getFreeGiftQuantityToAdd(CandidateItemOffer itemOffer)`	Gets the quantity of the free gift items to be added from the given `CandidateItemOffer`.
`protected List<CandidateItemOffer>`	`getPermutationByComparator(List<CandidateItemOffer> rootPremutation, Comparator<CandidateItemOffer> comparator)`	Uses a `Comparator` to sort `candidate offers`.
`protected List<com.broadleafcommerce.promotion.offer.client.web.context.info.OfferItemDetail>`	`getQualifierDetails(CandidateItemOffer itemOffer)`	Gets a list of `OfferItemDetails` representing qualifiers.
`protected boolean`	`isAdjustmentGoodEnough(CandidateItemOffer itemOffer, LineItemOfferDetail detail)`	Checking to make sure that an offer's adjustment to an item's price is actually better than the original price, especially if the item is on sale since not all offers can apply to a sale price.
`protected void`	`logIfDebugOn(String message, Object... formatArgs)`	Checks if `debug is enabled`, then wraps the message in `String.format(String, Object...)` with the given `formatArgs` and logs it.
`protected void`	`logIfTraceOn(String message, Object... formatArgs)`	Checks if `Log.isTraceEnabled()` trace is enabled}, then wraps the message in `String.format(String, Object...)` with the given `formatArgs` and logs it.
`protected void`	`mergePriceDetails(EnhancedOrder order)`	Checks to see if any `LineItemOfferDetails` need to be combined and if so, combines them.
`void`	`prepareForItemOfferProcessing(EnhancedOrder order, List<CandidateItemOffer> candidateItemOffers)`	Item offer processing can benefit from setup activities that are used by all of the permutations.
`protected void`	`removeDuplicatePermutations(List<List<CandidateItemOffer>> permutations)`	A duplicate permutation means that the permutations have the same offers in the same order.
`protected void`	`setCandidateItemOffers(CandidateOffers candidateOffers, List<CandidateItemOffer> candidateItemOffers)`
`protected void`	`sort(List<CandidateItemOffer> candidateItemOffers)`	The default based on the `CandidateItemOfferComparator`
`protected void`	`splitDetailsIfNecessary(List<LineItemOfferDetail> offerDetails)`	Checks if the discount quantity matches the detail quantity.
`protected void`	`updateBestPermutation(CombinedTypesOfferPermutation ctop, ItemOfferPermutationResult bestPermutation)`

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

Field Detail

potentialSavingsCalculator

protected final PotentialSavingsCalculator potentialSavingsCalculator

qualifierAndTargetMarker

protected final QualifierAndTargetMarker qualifierAndTargetMarker

helper

protected final OrderAndItemOfferHelper helper

Constructor Detail

DefaultItemOfferProcessor

public DefaultItemOfferProcessor(PotentialSavingsCalculator potentialSavingsCalculator,
                                 QualifierAndTargetMarker qualifierAndTargetMarker,
                                 OrderAndItemOfferHelper helper,
                                 boolean isForFulfillment)

Method Detail

findBestItemOffersForPermutation

public void findBestItemOffersForPermutation(OfferProcessingContext context,
                                             CombinedTypesOfferPermutation ctop)

Specified by:: findBestItemOffersForPermutation in interface ItemOfferProcessor

updateBestPermutation

protected void updateBestPermutation(CombinedTypesOfferPermutation ctop,
                                     ItemOfferPermutationResult bestPermutation)

applyItemAdjustments
```
public void applyItemAdjustments(OfferProcessingContext context,
                                 ItemOfferPermutationResult result)
```
Description copied from interface: ItemOfferProcessor

For item processing, the adjustments are stored on LineItemOfferDetail records. These detail records are stored in the ItemOfferPermutationResult.getLineItemDetailMap()

Specified by:

applyItemAdjustments in interface ItemOfferProcessor

prepareForItemOfferProcessing
```
public void prepareForItemOfferProcessing(EnhancedOrder order,
                                          List<CandidateItemOffer> candidateItemOffers)
```
Description copied from interface: ItemOfferProcessor

Item offer processing can benefit from setup activities that are used by all of the permutations. Most notably, finding the maximum savings for a given offer which can be used to prioritize the order in which offers are attempted within a cart.

Specified by:

prepareForItemOfferProcessing in interface ItemOfferProcessor

clearStateBetweenPermutations

protected void clearStateBetweenPermutations(EnhancedOrder order,
                                             List<CandidateItemOffer> candidateOffers)

computeOfferPermutationValue

protected ItemOfferPermutationResult computeOfferPermutationValue(OfferProcessingContext context,
                                                                  List<CandidateItemOffer> candidateItemOffers,
                                                                  OrderTotals orderTotals)

calculatePotentialSavings

protected void calculatePotentialSavings(EnhancedOrder order,
                                         List<CandidateItemOffer> candidateItemOffers)

sort
```
protected void sort(List<CandidateItemOffer> candidateItemOffers)
```
The default based on the CandidateItemOfferComparator

Parameters:

candidateItemOffers -

applyCandidateOffers

protected void applyCandidateOffers(@NonNull
                                    EnhancedOrder order,
                                    @NonNull
                                    List<CandidateItemOffer> candidateOffers)

expandPermutations
```
protected List<List<CandidateItemOffer>> expandPermutations(List<CandidateItemOffer> itemOffers)
```
This method takes a list of item offers that are compatible with each other and share the same combinability characteristics with other types like order offers and builds additional permutations that influence the order that the offers will be run.

Even though two offers are compatible to be in the same offer, the results of the offer engine can be different depending on the order they are applied due to complexities involving qualifiers and bundle offers.

For most scenarios, these complexities can be managed with using explicit priorities, exclusions and stacking rules.
- A permutation based on default sorting rules and potential savings
- A permutation based on considering savings on weighted potential savings
- A permutation based on savings tied to qty 1

getPermutationByComparator
```
protected List<CandidateItemOffer> getPermutationByComparator(List<CandidateItemOffer> rootPremutation,
                                                              Comparator<CandidateItemOffer> comparator)
```
Uses a Comparator to sort candidate offers. The default comparators to use are ItemOfferQtyOneComparator and ItemOfferWeightedPercentSavedComparator. Each ordering is considered its own permutation since the order in which offers are applied affects the end price.

See Also:

ItemOfferQtyOneComparator, ItemOfferWeightedPercentSavedComparator

removeDuplicatePermutations
```
protected void removeDuplicatePermutations(List<List<CandidateItemOffer>> permutations)
```
A duplicate permutation means that the permutations have the same offers in the same order.

Parameters:

permutations - contains lists of compatible CandidateItemOffers

findBestPermutation

protected Optional<List<CandidateItemOffer>> findBestPermutation(EnhancedOrder order,
                                                                 List<List<CandidateItemOffer>> permutations)

Determines the best permutation by comparing the resulting total discounts of each permutations.

applyItemOffer

protected void applyItemOffer(EnhancedOrder order,
                              CandidateItemOffer itemOffer)

canOfferBeApplied

protected boolean canOfferBeApplied(EnhancedOrder order,
                                    CandidateItemOffer itemOffer,
                                    List<LineItemOfferDetail> itemDetails)

Determines whether the Offer can be applied by making sure it is combinable and that all other offers applied to any LineItems are also combinable by checking their EnhancedLineItem.offerDetails.

Returns:: whether the offer can be applied.

applyItemQualifiersAndTargets

protected void applyItemQualifiersAndTargets(EnhancedOrder order,
                                             CandidateItemOffer itemOffer)

splitDetailsIfNecessary
```
protected void splitDetailsIfNecessary(List<LineItemOfferDetail> offerDetails)
```
Checks if the discount quantity matches the detail quantity. If not, splits the price detail.

applyAdjustments

protected void applyAdjustments(EnhancedOrder order,
                                CandidateItemOffer itemOffer)

calculatePriceForBundleRatio

protected javax.money.MonetaryAmount calculatePriceForBundleRatio(LineItemOfferDetail detail)

applyFreeGift
```
protected void applyFreeGift(EnhancedOrder order,
                             CandidateItemOffer itemOffer)
```
Builds and adds a FreeGiftItem to EnhancedOrder.getFreeGiftItems() based on CandidateItemOffer.getCandidateQualifiersMap() if the given itemOffer is a free gift offer.

Parameters:

order - order to apply the free gift offers to

itemOffer - offer to build the FreeGiftItem and get the qualifiers from

getFreeGiftQuantityToAdd
```
protected int getFreeGiftQuantityToAdd(CandidateItemOffer itemOffer)
```
Gets the quantity of the free gift items to be added from the given CandidateItemOffer.

Parameters:

itemOffer - the free gift offer to calculate the quantity of free gift items for

Returns:

the quantity of the free gift items to be added

buildFreeGiftItem

protected com.broadleafcommerce.promotion.offer.client.web.context.info.FreeGiftItem buildFreeGiftItem(Offer offer,
                                                                                                       int quantityToAdd,
                                                                                                       com.broadleafcommerce.promotion.offer.client.web.context.info.Adjustment adjustment)

Builds a FreeGiftItem from the given Offer, quantity, and qualifier item ids.

Parameters:: offer - the free gift offer to build the FreeGiftItem from; quantityToAdd - the quantity of the FreeGiftItem; adjustment - the ItemAdjustment of the FreeGiftItem
Returns:: FreeGiftItem from the given Offer, quantity, and adjustment

buildAdjustmentForFreeGift

protected com.broadleafcommerce.promotion.offer.client.web.context.info.Adjustment buildAdjustmentForFreeGift(EnhancedOrder order,
                                                                                                              CandidateItemOffer itemOffer)

Builds an Adjustment for a FreeGiftItem.

Parameters:: order - the EnhancedOrder the FreeGiftItem will be added to; itemOffer - the CandidateItemOffer for the free gift
Returns:: an Adjustment for then free gift offer

addOrderCodeToAdjustmentIfUsed

protected void addOrderCodeToAdjustmentIfUsed(@NonNull
                                              @NonNull Offer offer,
                                              @NonNull
                                              @NonNull com.broadleafcommerce.promotion.offer.client.web.context.info.Adjustment adjustment,
                                              @NonNull
                                              @NonNull Set<String> allOrderCodes)

Adds an offer code to the given Adjustment if it is present on the order.

Parameters:: offer - Offer from which the adjustment is derived.; adjustment - Adjustment The Adjustment for which an offer code may apply; allOrderCodes - Set of all of the shared or campaign codes set on the order. These may have been used to apply an offer and should be recorded on any Adjustments.

isAdjustmentGoodEnough
```
protected boolean isAdjustmentGoodEnough(CandidateItemOffer itemOffer,
                                         LineItemOfferDetail detail)
```
Checking to make sure that an offer's adjustment to an item's price is actually better than the original price, especially if the item is on sale since not all offers can apply to a sale price.

applyLineItemAdjustment

protected void applyLineItemAdjustment(CandidateItemOffer itemOffer,
                                       LineItemOfferDetail offerDetail,
                                       OfferDiscount offerDiscount)

Adds an ItemOfferAdjustment to the given LineItemOfferDetail.

Parameters:: itemOffer - the CandidateItemOffer to build the ItemOfferAdjustment from; offerDetail - the LineItemOfferDetail to add the ItemOfferAdjustment to; offerDiscount - the OfferDiscount to get the target criteria rule from

getQualifierDetails
```
protected List<com.broadleafcommerce.promotion.offer.client.web.context.info.OfferItemDetail> getQualifierDetails(CandidateItemOffer itemOffer)
```
Gets a list of OfferItemDetails representing qualifiers.

Parameters:

itemOffer - the CandidateItemOffer to get the qualifier items from

Returns:

a list of OfferItemDetails representing qualifiers

createOfferItemDetail

protected com.broadleafcommerce.promotion.offer.client.web.context.info.OfferItemDetail createOfferItemDetail(CandidateItemOffer itemOffer,
                                                                                                              String itemId,
                                                                                                              int quantityPerUsage)

Creates an OfferItemDetail based on the given fields.

Parameters:: itemOffer - the CandidateItemOffer to build the details from; itemId - the item id; quantityPerUsage - the quantity per usage
Returns:: an OfferItemDetail based on the given fields

computeStandardAdjustmentValue

protected javax.money.MonetaryAmount computeStandardAdjustmentValue(CandidateItemOffer itemOffer,
                                                                    LineItemOfferDetail offerDetail)

computeSaleAdjustmentValue

protected javax.money.MonetaryAmount computeSaleAdjustmentValue(CandidateItemOffer itemOffer,
                                                                LineItemOfferDetail offerDetail)

chooseSaleOrStandardAdjustments
```
protected void chooseSaleOrStandardAdjustments(EnhancedOrder order)
```
Some Offers can only apply to the EnhancedLineItem.getStandardPrice(). This method determines whether standard-price-only promotions should be used instead of those that can apply to the sale price as well.

addFreeGiftsToResult

protected void addFreeGiftsToResult(OfferProcessingContext context,
                                    ItemOfferPermutationResult result)

getEstimatedFreeGiftValue

protected javax.money.MonetaryAmount getEstimatedFreeGiftValue(EnhancedOrder order,
                                                               Offer offer)

mergePriceDetails
```
protected void mergePriceDetails(EnhancedOrder order)
```
Checks to see if any LineItemOfferDetails need to be combined and if so, combines them.

getCandidateItemOffers

protected List<CandidateItemOffer> getCandidateItemOffers(OfferProcessingContext context)

setCandidateItemOffers

protected void setCandidateItemOffers(CandidateOffers candidateOffers,
                                      List<CandidateItemOffer> candidateItemOffers)

assertCommonParamsNotNull

protected void assertCommonParamsNotNull(EnhancedOrder order,
                                         CandidateOffers candidateOffers)

assertCandidateOffersNotNull

protected void assertCandidateOffersNotNull(CandidateOffers candidateOffers)

logIfDebugOn
```
protected void logIfDebugOn(String message,
                            Object... formatArgs)
```
Checks if debug is enabled, then wraps the message in String.format(String, Object...) with the given formatArgs and logs it.

logIfTraceOn
```
protected void logIfTraceOn(String message,
                            Object... formatArgs)
```
Checks if Log.isTraceEnabled() trace is enabled}, then wraps the message in String.format(String, Object...) with the given formatArgs and logs it.

Class DefaultItemOfferProcessor

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

potentialSavingsCalculator

qualifierAndTargetMarker

helper

Constructor Detail

DefaultItemOfferProcessor

Method Detail

findBestItemOffersForPermutation

updateBestPermutation

applyItemAdjustments

prepareForItemOfferProcessing

clearStateBetweenPermutations

computeOfferPermutationValue

calculatePotentialSavings

sort

applyCandidateOffers

expandPermutations

getPermutationByComparator

removeDuplicatePermutations

findBestPermutation

applyItemOffer

canOfferBeApplied

applyItemQualifiersAndTargets

splitDetailsIfNecessary

applyAdjustments

calculatePriceForBundleRatio

applyFreeGift

getFreeGiftQuantityToAdd

buildFreeGiftItem

buildAdjustmentForFreeGift

addOrderCodeToAdjustmentIfUsed

isAdjustmentGoodEnough

applyLineItemAdjustment

getQualifierDetails

createOfferItemDetail

computeStandardAdjustmentValue

computeSaleAdjustmentValue

chooseSaleOrStandardAdjustments

addFreeGiftsToResult

getEstimatedFreeGiftValue

mergePriceDetails

getCandidateItemOffers

setCandidateItemOffers

assertCommonParamsNotNull

assertCandidateOffersNotNull

logIfDebugOn

logIfTraceOn