org.broadleafcommerce.core.order.service

Interface OrderService

All Known Subinterfaces:

LegacyCartService, LegacyOrderService

All Known Implementing Classes:

LegacyCartServiceImpl, LegacyOrderServiceImpl, OrderServiceImpl

public interface OrderService

The general interface for interacting with shopping carts and completed Orders. In Broadleaf Commerce, a Cart and an Order are the same thing. A "cart" becomes an order after it has been submitted. Most of the methods in this order are used to modify the cart. However, it is also common to use this service for "named" orders (aka wishlists).

Method Summary

Methods

Modifier and Type	Method and Description
Order	addAllItemsFromNamedOrder(Order namedOrder, boolean priceOrder) Adds all orderItems to the current cart from the same Customer that owns the named order.
OrderItem	addGiftWrapItemToOrder(Order order, GiftWrapOrderItemRequest itemRequest, boolean priceOrder) Adds a GiftWrapItem to the order based on the itemRequest.
Order	addItem(Long orderId, OrderItemRequestDTO orderItemRequestDTO, boolean priceOrder) Initiates the addItem workflow that will attempt to add the given quantity of the specified item to the Order.
Order	addItemFromNamedOrder(Order namedOrder, OrderItem orderItem, boolean priceOrder) Adds the passed in orderItem to the current cart for the same Customer that owns the named order.
Order	addItemFromNamedOrder(Order namedOrder, OrderItem orderItem, int quantity, boolean priceOrder) This method performs the same function as addItemFromNamedOrder(Order, OrderItem, boolean) except that instead of adding all of the quantity from the named order to the cart, it will only add/move the specific quantity requested.
Order	addItemWithPriceOverrides(Long orderId, OrderItemRequestDTO orderItemRequestDTO, boolean priceOrder) Initiates the addItem workflow that will attempt to add the given quantity of the specified item to the Order.
Order	addOfferCode(Order order, OfferCode offerCode, boolean priceOrder) Adds the given OfferCode to the order.
Order	addOfferCodes(Order order, List<OfferCode> offerCodes, boolean priceOrder) Adds the given OfferCodes to the order.
OrderPayment	addPaymentToOrder(Order order, OrderPayment payment, Referenced securePaymentInfo) Associates a given OrderPayment with an Order and then saves the order.
void	cancelOrder(Order order) Deletes the given order.
Order	confirmOrder(Order order) Changes the OrderStatus to SUBMITTED
Order	createNamedOrderForCustomer(String name, Customer customer) Creates a new Order for the given customer with the given name.
Order	createNewCartForCustomer(Customer customer) Creates a new Order for the given customer.
void	deleteOrder(Order cart)
Order	findCartForCustomer(Customer customer) Looks up the current shopping cart for the customer.
OrderItem	findLastMatchingItem(Order order, Long skuId, Long productId) Looks through the given order and returns the latest added OrderItem that matches on the skuId and productId.
Order	findNamedOrderForCustomer(String name, Customer customer) Looks up an Order by the given customer and a specified order name.
Order	findOrderById(Long orderId) Looks up an Order by its database id
Order	findOrderById(Long orderId, boolean refresh) Looks up an Order by its database id and optionally calls refresh to ensure that the entity manager pulls the instance from the DB and not from cache
Order	findOrderByOrderNumber(String orderNumber) Looks up Orders and returns the order matching the given orderNumber
List<Order>	findOrdersForCustomer(Customer customer) Looks up all Orders for the specified customer, regardless of current OrderStatus
List<Order>	findOrdersForCustomer(Customer customer, OrderStatus status) Looks up all Orders for the specified customer that are in the specified OrderStatus.
List<OrderPayment>	findPaymentsForOrder(Order order) Returns all OrderPayment objects that are associated with the given order
boolean	getAutomaticallyMergeLikeItems()
Order	getNullOrder() The null order is the default order for all customers when they initially enter the site.
boolean	isDeleteEmptyNamedOrders()
boolean	isMoveNamedOrderItems()
void	preValidateCartOperation(Order cart) Invokes the extension handler of the same name to provide the ability for a module to throw an exception and interrupt a cart operation.
void	printOrder(Order order, org.apache.commons.logging.Log log) This debugging method will print out a console-suitable representation of the current state of the order, including the items in the order and all pricing related information for the order.
Order	reloadOrder(Order order) Detaches the given order from the current entity manager and then reloads a fresh version from the database.
Order	removeAllOfferCodes(Order order, boolean priceOrder) Removes all offer codes for the given order.
void	removeAllPaymentsFromOrder(Order order) Deletes all the OrderPayment Info's on the order.
Order	removeInactiveItems(Long orderId, boolean priceOrder)
Order	removeItem(Long orderId, Long orderItemId, boolean priceOrder) Initiates the removeItem workflow that will attempt to remove the specified OrderItem from the given Order
Order	removeOfferCode(Order order, OfferCode offerCode, boolean priceOrder) Remove the given OfferCode for the order.
void	removePaymentFromOrder(Order order, OrderPayment paymentInfo) Deletes the OrderPayment Info from the order.
void	removePaymentsFromOrder(Order order, PaymentType paymentInfoType) Deletes the OrderPayment Info of the passed in type from the order Note that this method will also delete any associated Secure OrderPayment Infos if necessary.
Order	save(Order order, Boolean priceOrder) Persists the given order to the database.
void	setAutomaticallyMergeLikeItems(boolean automaticallyMergeLikeItems) When set to true, the system when items are added to the cart, they will automatically be merged.
void	setDeleteEmptyNamedOrders(boolean deleteEmptyNamedOrders) Sets whether or not to delete named orders once all items have been removed.
void	setMoveNamedOrderItems(boolean moveNamedOrderItems) Determines whether or not items will be removed from the named order (wishlist) when they are moved to the Customer's current cart.
Order	updateItemQuantity(Long orderId, OrderItemRequestDTO orderItemRequestDTO, boolean priceOrder) Initiates the updateItem workflow that will attempt to update the item quantity for the specified OrderItem in the given Order.
Order	updateProductOptionsForItem(Long orderId, OrderItemRequestDTO orderItemRequestDTO, boolean priceOrder) Since required product option can be added after the item is in the cart, we use this method to apply product option on an existing item in the cart.

Method Detail

createNewCartForCustomer

Order createNewCartForCustomer(Customer customer)

Creates a new Order for the given customer. Generally, you will want to use the customer that is on the current request, which can be grabbed by utilizing the CustomerState utility class. The default Broadleaf implementation of this method will provision a new Order in the database and set the current customer as the owner of the order. If the customer has an email address associated with their profile, that will be copied as well. If the customer is a new, anonymous customer, his username will be set to his database id.

Parameters:

customer -

Returns:

the newly created order

See Also:

CustomerState

createNamedOrderForCustomer

Order createNamedOrderForCustomer(String name,
                                Customer customer)

Creates a new Order for the given customer with the given name. Typically, this represents a "wishlist" order that the customer can save but not check out with.

Parameters:

name - the wishlist name

customer -

args - additional arguments to be used by Broadleaf extensions

Returns:

the newly created named order

findNamedOrderForCustomer

Order findNamedOrderForCustomer(String name,
                              Customer customer)

Looks up an Order by the given customer and a specified order name. This is typically used to retrieve a "wishlist" order.

Parameters:

name -

customer -

args - additional arguments to be used by Broadleaf extensions

Returns:

the named order requested

See Also:

createNamedOrderForCustomer(String name, Customer customer)

findOrderById

Order findOrderById(Long orderId)

Looks up an Order by its database id

Parameters:

orderId -

Returns:

the requested Order

findOrderById

Order findOrderById(Long orderId,
                  boolean refresh)

Looks up an Order by its database id and optionally calls refresh to ensure that the entity manager pulls the instance from the DB and not from cache

Parameters:

orderId -

Returns:

the requested Order

findCartForCustomer

Order findCartForCustomer(Customer customer)

Looks up the current shopping cart for the customer. Note that a shopping cart is simply an Order with OrderStatus = IN_PROCESS. If for some reason the given customer has more than one current IN_PROCESS Order, the default Broadleaf implementation will return the first match found. Furthermore, also note that the current shopping cart for a customer must never be named -- an Order with a non-null "name" property indicates that it is a wishlist and not a shopping cart.

Parameters:

customer -

Returns:

the current shopping cart for the customer

findOrdersForCustomer

List<Order> findOrdersForCustomer(Customer customer)

Looks up all Orders for the specified customer, regardless of current OrderStatus

Parameters:

customer -

Returns:

the requested Orders

findOrdersForCustomer

List<Order> findOrdersForCustomer(Customer customer,
                                OrderStatus status)

Looks up all Orders for the specified customer that are in the specified OrderStatus.

Parameters:

customer -

status -

Returns:

the requested Orders

findOrderByOrderNumber

Order findOrderByOrderNumber(String orderNumber)

Looks up Orders and returns the order matching the given orderNumber

Parameters:

orderNumber -

Returns:

the requested Order

findPaymentsForOrder

List<OrderPayment> findPaymentsForOrder(Order order)

Returns all OrderPayment objects that are associated with the given order

Parameters:

order -

Returns:

the list of all OrderPayment objects

addPaymentToOrder

OrderPayment addPaymentToOrder(Order order,
                             OrderPayment payment,
                             Referenced securePaymentInfo)

Associates a given OrderPayment with an Order and then saves the order. Note that it is acceptable for the securePaymentInfo to be null. For example, if the secure credit card details are handled by a third party, a given application may never have associated securePaymentInfos

Parameters:

order -

payment -

securePaymentInfo - - null if it doesn't exist

Returns:

the persisted version of the OrderPayment

save

Order save(Order order,
         Boolean priceOrder)
           throws PricingException

Persists the given order to the database. If the priceOrder flag is set to true, the pricing workflow will execute before the order is written to the database. Generally, you will want to price the order in every request scope once, and preferrably on the last call to save() for performance reasons. However, if you have logic that depends on the Order being priced, there are no issues with saving as many times as necessary.

Parameters:

order -

priceOrder -

Returns:

the persisted Order, which will be a different instance than the Order passed in

Throws:

PricingException

cancelOrder

void cancelOrder(Order order)

Deletes the given order. Note that the default Broadleaf implementation in OrderServiceImpl will actually remove the Order instance from the database.

Parameters:

order -

addOfferCode

Order addOfferCode(Order order,
                 OfferCode offerCode,
                 boolean priceOrder)
                   throws PricingException,
                          OfferMaxUseExceededException

Adds the given OfferCode to the order. Optionally prices the order as well.

Parameters:

order -

offerCode -

priceOrder -

Returns:

the modified Order

Throws:

PricingException

OfferMaxUseExceededException

addOfferCodes

Order addOfferCodes(Order order,
                  List<OfferCode> offerCodes,
                  boolean priceOrder)
                    throws PricingException,
                           OfferMaxUseExceededException

Adds the given OfferCodes to the order. Optionally prices the order as well.

Parameters:

order -

offerCodes -

priceOrder -

Returns:

Throws:

PricingException

OfferMaxUseExceededException

removeOfferCode

Order removeOfferCode(Order order,
                    OfferCode offerCode,
                    boolean priceOrder)
                      throws PricingException

Remove the given OfferCode for the order. Optionally prices the order as well.

Parameters:

order -

offerCode -

priceOrder -

Returns:

the modified Order

Throws:

PricingException

removeAllOfferCodes

Order removeAllOfferCodes(Order order,
                        boolean priceOrder)
                          throws PricingException

Removes all offer codes for the given order. Optionally prices the order as well.

Parameters:

order -

priceOrder -

Returns:

the modified Order

Throws:

PricingException

getNullOrder

Order getNullOrder()

The null order is the default order for all customers when they initially enter the site. Upon the first addition of a product to a cart, a non-null order will be provisioned for the user.

Returns:

a shared, static, unmodifiable NullOrder

See Also:

for more information

getAutomaticallyMergeLikeItems

boolean getAutomaticallyMergeLikeItems()

Returns:

whether or not like-items will be automatically merged

See Also:

setAutomaticallyMergeLikeItems(boolean)

setAutomaticallyMergeLikeItems

void setAutomaticallyMergeLikeItems(boolean automaticallyMergeLikeItems)

When set to true, the system when items are added to the cart, they will automatically be merged. For example, when a user adds an item to the cart and then adds the item again, the item will have its quantity changed to 2 instead of the cart containing two separate items. If this logic needs to be more complex, it is possible to extend the behavior by overriding OrderOfferProcessor.buildIdentifier().

Parameters:

automaticallyMergeLikeItems -

confirmOrder

Order confirmOrder(Order order)

Changes the OrderStatus to SUBMITTED

Parameters:

order - to confirm

Returns:

the order that was confirmed

findLastMatchingItem

OrderItem findLastMatchingItem(Order order,
                             Long skuId,
                             Long productId)

Looks through the given order and returns the latest added OrderItem that matches on the skuId and productId. Generally, this is used to retrieve the OrderItem that was just added to the cart. The default Broadleaf implementation will attempt to match on skuId first, and failing that, it will look at the productId. Note that the behavior is slightly undeterministic in the case that setAutomaticallyMergeLikeItems is set to true and the last added sku matches on a previously added sku. In this case, the sku that has the merged items would be returned, so the total quantity of the OrderItem might not match exactly what was just added.

Parameters:

order -

skuId -

productId -

Returns:

the best matching OrderItem with highest index in the list of OrderItems in the order

addGiftWrapItemToOrder

OrderItem addGiftWrapItemToOrder(Order order,
                               GiftWrapOrderItemRequest itemRequest,
                               boolean priceOrder)
                                 throws PricingException

Adds a GiftWrapItem to the order based on the itemRequest. A GiftWrapItem is a product (for example, a "Gift Box with Red Ribbon") that contains a list of OrderItems that should be wrapped by this GiftWrapItem. The OrderItems must already exist and belong to an order before they are able to be wrapped by the GiftWrapItem

Parameters:

order -

itemRequest -

priceOrder -

Returns:

the GiftWrapItem instance that was created and attached to the order

Throws:

PricingException

addItem

Order addItem(Long orderId,
            OrderItemRequestDTO orderItemRequestDTO,
            boolean priceOrder)
              throws AddToCartException

Initiates the addItem workflow that will attempt to add the given quantity of the specified item to the Order. The item to be added can be determined in a few different ways. For example, the SKU can be specified directly or it can be determine based on a Product and potentially some specified ProductOptions for that given product. The minimum required parameters for OrderItemRequest are: productId and quantity or alternatively, skuId and quantity When priceOrder is false, the system will not reprice the order. This is more performant in cases such as bulk adds where the repricing could be done for the last item only. This method differs from the addItemWithPriceOverrides(Long, OrderItemRequestDTO, boolean) in that it will clear any values set on the OrderItemRequestDTO for the overrideSalePrice or overrideRetailPrice. This design is intended to ensure that override pricing is not called by mistake. Implementors should use this method when no manual price overrides are allowed.

Parameters:

orderId -

orderItemRequest -

priceOrder -

Returns:

the order the item was added to

Throws:

WorkflowException

Throwable

AddToCartException

See Also:

OrderItemRequestDTO

addItemWithPriceOverrides

Order addItemWithPriceOverrides(Long orderId,
                              OrderItemRequestDTO orderItemRequestDTO,
                              boolean priceOrder)
                                throws AddToCartException

Initiates the addItem workflow that will attempt to add the given quantity of the specified item to the Order. The item to be added can be determined in a few different ways. For example, the SKU can be specified directly or it can be determine based on a Product and potentially some specified ProductOptions for that given product. The minimum required parameters for OrderItemRequest are: productId and quantity or alternatively, skuId and quantity When priceOrder is false, the system will not reprice the order. This is more performant in cases such as bulk adds where the repricing could be done for the last item only. As opposed to the addItem(Long, OrderItemRequestDTO, boolean) method, this method allows the passed in OrderItemRequestDTO to contain values for the overrideSale or overrideRetail price fields. This design is intended to ensure that override pricing is not called by mistake. Implementors should use this method when manual price overrides are allowed.

Parameters:

orderId -

orderItemRequest -

priceOrder -

Returns:

the order the item was added to

Throws:

WorkflowException

Throwable

AddToCartException

See Also:

OrderItemRequestDTO

updateItemQuantity

Order updateItemQuantity(Long orderId,
                       OrderItemRequestDTO orderItemRequestDTO,
                       boolean priceOrder)
                         throws UpdateCartException,
                                RemoveFromCartException

Initiates the updateItem workflow that will attempt to update the item quantity for the specified OrderItem in the given Order. The new quantity is specified in the OrderItemRequestDTO Minimum required parameters for OrderItemRequest: orderItemId, quantity

Parameters:

orderId -

orderItemRequest -

priceOrder -

Returns:

the order the item was added to

Throws:

UpdateCartException

RemoveFromCartException

See Also:

OrderItemRequestDTO

removeItem

Order removeItem(Long orderId,
               Long orderItemId,
               boolean priceOrder)
                 throws RemoveFromCartException

Initiates the removeItem workflow that will attempt to remove the specified OrderItem from the given Order

Parameters:

orderId -

orderItemId -

priceOrder -

Returns:

the order the item was added to

Throws:

RemoveFromCartException

See Also:

OrderItemRequestDTO

isMoveNamedOrderItems

boolean isMoveNamedOrderItems()

Returns:

whether items will be removed from the wishlist when added to the cart

See Also:

setMoveNamedOrderItems(boolean)

setMoveNamedOrderItems

void setMoveNamedOrderItems(boolean moveNamedOrderItems)

Determines whether or not items will be removed from the named order (wishlist) when they are moved to the Customer's current cart.

Parameters:

moveNamedOrderItems -

isDeleteEmptyNamedOrders

boolean isDeleteEmptyNamedOrders()

Returns:

whether empty wishlists will be deleted automatically

See Also:

setDeleteEmptyNamedOrders(boolean)

setDeleteEmptyNamedOrders

void setDeleteEmptyNamedOrders(boolean deleteEmptyNamedOrders)

Sets whether or not to delete named orders once all items have been removed.

Parameters:

deleteEmptyNamedOrders -

addItemFromNamedOrder

Order addItemFromNamedOrder(Order namedOrder,
                          OrderItem orderItem,
                          boolean priceOrder)
                            throws RemoveFromCartException,
                                   AddToCartException

Adds the passed in orderItem to the current cart for the same Customer that owns the named order. This method will remove the item from the wishlist based on whether the setMoveNamedOrderItems flag is set. Note that if an item was in a wishlist and is no longer able to be added to the cart, the item will still be removed from the wishlist. Note that this method does not change the association of the OrderItems to the new order -- instead, those OrderItems is completely removed and a new OrderItem that mirrors it is created.

Parameters:

namedOrder -

orderItem -

priceOrder -

Returns:

the cart with the requested orderItem added to it

Throws:

RemoveFromCartException

AddToCartException

addItemFromNamedOrder

Order addItemFromNamedOrder(Order namedOrder,
                          OrderItem orderItem,
                          int quantity,
                          boolean priceOrder)
                            throws RemoveFromCartException,
                                   AddToCartException,
                                   UpdateCartException

This method performs the same function as addItemFromNamedOrder(Order, OrderItem, boolean) except that instead of adding all of the quantity from the named order to the cart, it will only add/move the specific quantity requested.

Parameters:

namedOrder -

orderItem -

quantity -

priceOrder -

Returns:

the cart with the requested orderItem added to it

Throws:

RemoveFromCartException

AddToCartException

UpdateCartException

See Also:

addItemFromNamedOrder(Order, OrderItem, boolean)

addAllItemsFromNamedOrder

Order addAllItemsFromNamedOrder(Order namedOrder,
                              boolean priceOrder)
                                throws RemoveFromCartException,
                                       AddToCartException

Adds all orderItems to the current cart from the same Customer that owns the named order. This method will remove the item from the wishlist based on whether the setMoveNamedOrderItems flag is set. Note that any items that are in the wishlist but are no longer able to be added to a cart will still be removed from the wishlist. Note that this method does not change the association of the OrderItems to the new order -- instead, those OrderItems is completely removed and a new OrderItem that mirrors it is created.

Parameters:

namedOrder -

priceOrder -

Returns:

Throws:

RemoveFromCartException

AddToCartException

removeAllPaymentsFromOrder

void removeAllPaymentsFromOrder(Order order)

Deletes all the OrderPayment Info's on the order.

Parameters:

order -

removePaymentsFromOrder

void removePaymentsFromOrder(Order order,
                           PaymentType paymentInfoType)

Deletes the OrderPayment Info of the passed in type from the order Note that this method will also delete any associated Secure OrderPayment Infos if necessary.

Parameters:

order -

paymentInfoType -

removePaymentFromOrder

void removePaymentFromOrder(Order order,
                          OrderPayment paymentInfo)

Deletes the OrderPayment Info from the order. Note that this method will also delete any associated Secure OrderPayment Infos if necessary.

Parameters:

order -

paymentInfo -

deleteOrder

void deleteOrder(Order cart)

removeInactiveItems

Order removeInactiveItems(Long orderId,
                        boolean priceOrder)
                          throws RemoveFromCartException

Throws:

RemoveFromCartException

updateProductOptionsForItem

Order updateProductOptionsForItem(Long orderId,
                                OrderItemRequestDTO orderItemRequestDTO,
                                boolean priceOrder)
                                  throws UpdateCartException

Since required product option can be added after the item is in the cart, we use this method to apply product option on an existing item in the cart. No validation will happen at this time, as the validation at checkout will take care of any missing product options.

Parameters:

orderId -

orderItemRequestDTO -

priceOrder -

Returns:

Order

Throws:

UpdateCartException

printOrder

void printOrder(Order order,
              org.apache.commons.logging.Log log)

This debugging method will print out a console-suitable representation of the current state of the order, including the items in the order and all pricing related information for the order.

Parameters:

order - the order to debug

log - the Log to use to print a debug-level message

preValidateCartOperation

void preValidateCartOperation(Order cart)

Invokes the extension handler of the same name to provide the ability for a module to throw an exception and interrupt a cart operation.

Parameters:

cart -

reloadOrder

Order reloadOrder(Order order)

Detaches the given order from the current entity manager and then reloads a fresh version from the database.

Parameters:

order -

Returns:

the newly read order