Package org.broadleafcommerce.core.order.service

Interface OrderService

All Known Implementing Classes:
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 Details

    • 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:
      • org.broadleafcommerce.profile.web.core.CustomerState#getCustomer()

    • 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 -
      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 -
      Returns:
      the named order requested
      See Also:

    • findOrderById

      Order findOrderById(Long orderId)
      Looks up an Order by its database id
      Parameters:
      orderId -
      Returns:
      the requested Order

    • findOrdersByIds

      List<Order> findOrdersByIds(List<Long> orderIds)
      Looks up a list of Orders by their database ids
      Parameters:
      orderIds -
      Returns:
      a list of Orders

    • 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

    • findOrdersByDateRange

      List<Order> findOrdersByDateRange(Date startDate, Date endDate)

    • findOrdersByDaysCount

      List<Order> findOrdersByDaysCount(Integer daysCount, Integer batchSize)

    • findOrdersForCustomersInDateRange

      List<Order> findOrdersForCustomersInDateRange(List<Long> customerIds, Date startDate, Date endDate)

    • 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

    • save

      Order save(Order order, boolean priceOrder, boolean repriceItems) throws PricingException
      Saves the given order while optionally repricing the order (meaning, going through the pricing workflow) along with updating the prices of individual items in the order, as opposed to just pricing taxes/shipping/etc.
      Parameters:
      order -
      priceOrder -
      repriceItems - whether or not to reprice the items inside of the order via Order.updatePrices()
      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, OfferException
      Adds the given OfferCode to the order. Optionally prices the order as well.
      Parameters:
      order -
      offerCode -
      priceOrder -
      Returns:
      the modified Order
      Throws:
      PricingException
      OfferMaxUseExceededException
      OfferException

    • addOfferCodes

      Order addOfferCodes(Order order, List<OfferCode> offerCodes, boolean priceOrder) throws PricingException, OfferException
      Adds the given OfferCodes to the order. Optionally prices the order as well.
      Parameters:
      order -
      offerCodes -
      priceOrder -
      Returns:
      Throws:
      PricingException
      OfferMaxUseExceededException
      OfferException

    • 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:

    • getAutomaticallyMergeLikeItems

      boolean getAutomaticallyMergeLikeItems()
      Returns:
      whether or not like-items will be automatically merged
      See Also:

    • 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(boolean) 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 -
      orderItemRequestDTO -
      priceOrder -
      Returns:
      the order the item was added to
      Throws:
      WorkflowException
      Throwable
      AddToCartException
      See Also:

    • 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 -
      orderItemRequestDTO -
      priceOrder -
      Returns:
      the order the item was added to
      Throws:
      WorkflowException
      Throwable
      AddToCartException
      See Also:

    • getTotalChildOrderItems

      int getTotalChildOrderItems(OrderItemRequestDTO orderItemRequestDTO)

    • addChildItems

      void addChildItems(OrderItemRequestDTO orderItemRequestDTO, int numAdditionRequests, int currentAddition, ProcessContext<CartOperationRequest> context, List<ActivityMessageDTO> orderMessages) throws WorkflowException
      Throws:
      WorkflowException

    • addDependentOrderItem

      void addDependentOrderItem(OrderItemRequestDTO parentOrderItemRequest, OrderItemRequestDTO dependentOrderItem)

    • 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 -
      orderItemRequestDTO -
      priceOrder -
      Returns:
      the order the item was added to
      Throws:
      UpdateCartException
      RemoveFromCartException
      See Also:

    • 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:

    • isMoveNamedOrderItems

      boolean isMoveNamedOrderItems()
      Returns:
      whether items will be removed from the wishlist when added to the cart
      See Also:

    • 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

      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(boolean) 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:

    • 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(boolean) 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 -

    • removeCreditCardPaymentsFromOrder

      @Transactional("blTransactionManager") void removeCreditCardPaymentsFromOrder(Order order)

    • 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 -

    • preValidateUpdateQuantityOperation

      void preValidateUpdateQuantityOperation(Order cart, OrderItemRequestDTO dto)
      Invokes the extension handler of the same name to provide the ability for a module to throw an exception and interrupt an update quantity 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

    • acquireLock

      boolean acquireLock(Order order)
      Parameters:
      order -
      Returns:
      whether or not the lock was acquired
      See Also:

    • releaseLock

      boolean releaseLock(Order order)
      Parameters:
      order -
      Returns:
      whether or not the lock was released
      See Also:

    • refresh

      void refresh(Order order)

    • findCartForCustomerWithEnhancements

      Order findCartForCustomerWithEnhancements(Customer customer)
      Retrieve an enhanced version of the cart for the customer. Enhanced carts are generally provided by commercial Broadleaf modules.
      Parameters:
      customer - the user for whom the enhanced cart is retrieved
      Returns:
      the enhanced cart, or the basic cart if no enhancement is available

    • findCartForCustomerWithEnhancements

      Order findCartForCustomerWithEnhancements(Customer customer, Order candidateOrder)
      For the customer, use the candidateOrder as the source of enhancement for generating an enhanced cart. Enhanced carts are generally provided by commercial Broadleaf modules.
      Parameters:
      customer - the user for whom the enhanced cart is generated
      candidateOrder - the source of enhancement
      Returns:
      the enhanced cart, or the untouched candidateOrder if no enhancement is available

    • findOrdersByEmail

      List<Order> findOrdersByEmail(String email)
      Looks up all Orders for the specified email, regardless of current OrderStatus
      Parameters:
      email -
      Returns:
      the requested Orders

    • readBatchOrders

      List<Order> readBatchOrders(int start, int pageSize, List<OrderStatus> orderStatusList)

    • readNumberOfOrders

      Long readNumberOfOrders()