org.cyclos.services.marketplace

Interface OrderService

All Superinterfaces:

CRUDService<OrderDTO,OrderData,OrderDataParams>, Service

All Known Subinterfaces:

OrderServiceLocal

All Known Implementing Classes:

OrderServiceSecurity

public interface OrderService
extends CRUDService<OrderDTO,OrderData,OrderDataParams>

Service interface for web shop orders. Orders can be created via the logged user's shopping cart (with status OrderStatus.SHOPPING_CART) or as a new sale by the seller (with status OrderStatus.DRAFT).

Shopping carts are always for a logged user, and contains one order per seller and currency. The workflow is:

• Initially, the status is OrderStatus.SHOPPING_CART when the first product is added, via #addToCart(Long, BigDecimal). Product quantity can be modified with #modifyQuantityOnCart(Long, BigDecimal) or removed with #removeCartItem(Long). Alternatively, an entire cart can be removed with #removeCart(Long, Long).
• Once the cart is ok, it can be checked out with the checkout(ShoppingCartCheckoutParams) method. This will change the order status to OrderStatus.PENDING_SELLER. If the delivery price is known, the total order amount is reserved on the buyer's account, the confirmation password (if any) is checked and the stock is updated.
• If the delivery price was not known, the seller will then need to fill in the delivery price and accept. In that case, the order will return for buyer's confirm (the status will be set to OrderStatus.PENDING_BUYER). Otherwise, if the delivery price was known, the amount reservation will be returned and the actual payment will be performed, and the new status will be OrderStatus.COMPLETED.
• If the delivery price was previously set by the seller, the buyer will need to provide the confirmation password (if any) and accept. The actual payment will then be performed and the stock will be updated. The final status will be OrderStatus.COMPLETED.

When a seller is creating an order:

• The order may be saved as many times as the seller wants, by using the CRUDService.save(org.cyclos.model.EntityDTO) method. Only orders with the OrderStatus.DRAFT status can be created / modified. No deeper validation is performed on draft orders.
• When the order is ready, the seller submits it for the buyer to approve, using the submitToBuyer(OrderDTO) method. At that point, the order needs the list of products and the delivery address, price and time set.
• The buyer selects the payment type and inputs the confirmation password (if any). The stock is then updated, the payment is performed and the new status will be OrderStatus.COMPLETED.

When the status is OrderStatus.PENDING_BUYER, the buyer may reject the order, and the new status will be OrderStatus.REJECTED_BY_BUYER. The same accounts for OrderStatus.PENDING_SELLER and OrderStatus.REJECTED_BY_SELLER.

Author:

luis, micael

Method Summary

Modifier and Type	Method and Description
OrderStatus	accept(@NotNull AcceptOrderParams params) Accepts the given order, which should be in either OrderStatus.PENDING_BUYER or OrderStatus.PENDING_SELLER status, and needs the delivery price to be already set.
int	addToCart(@NotNull BasicAdVO adVO, java.math.BigDecimal quantity) Adds the given product to the logged user's shopping cart, returning the total count of ads in the cart.
ShoppingCartDTO	adjustAndGetMyCart() Returns the current logged user's shopping cart, adjusting all quantities
OrderData	adjustShoppingCartAndGetData(@NotNull OrderVO vo) Perform adjustments to the shopping cart quantities and returns the data for it
void	checkCartStock(@NotNull UserLocatorVO seller, @NotNull CurrencyVO currency) Checks that all items on the given cart are still on stock
ShoppingCartCheckoutResult	checkout(@NotNull ShoppingCartCheckoutParams dto) Checks out the logged user's shopping cart with the given seller and currency, checking the confirmation password (if any), and reserving the amount when the delivery price is previously known (otherwise, the buyer still needs to confirm before the payment is done).
int	countCartItems() Returns the total number of items in the logged user's shopping cart
OrderData	getCheckoutData(@NotNull UserLocatorVO seller, @NotNull CurrencyVO currency) Returns data for checkout the cart items of the given seller and currency
ShoppingCartDTO	getMyCart() Returns the current logged user's shopping cart, without adjusting any quantity
OrderData	getOrderData(@NotNull OrderVO vo) Returns data of an order
UserSalesData	getUserSalesData(@NotNull UserLocatorVO locator) Returns data for viewing a user sales
int	modifyQuantityOnCart(@NotNull BasicAdVO adVO, java.math.BigDecimal quantity) Updates the quantity for the given product on the logged user's shopping cart returning the total count of ads in the cart.
void	reject(@NotNull RejectOrderParams params) Rejects the given order
int	removeCart(@NotNull UserLocatorVO seller, CurrencyVO currency) Removes the logged user's shopping cart for the given seller and currency returning the remaining count of ads in the cart
int	removeCartById(@NotNull java.lang.Long id) Same as CRUDService.remove(Long) but returning the total count of items present the whole shopping cart
int	removeCartItem(@NotNull BasicAdVO adVO) Removes the given product from the logged user's shopping cart returning the remaining count of ads in the cart.
Page<OrderVO>	search(@NotNull OrderQuery query) Searches for orders based on OrderQuery
void	setDeliveryMethod(@NotNull SetDeliveryMethodParams params) Updates the delivery method information of an order when it is on the OrderStatus.PENDING_SELLER status and there is no delivery information yet.
java.lang.Long	submitToBuyer(@NotNull OrderDTO order) Submits the given order for buyer approval

Methods inherited from interface org.cyclos.services.CRUDService

getData, getDataForNew, load, remove, removeAll, save

Method Detail

accept

OrderStatus accept(@NotNull
                   @NotNull AcceptOrderParams params)
            throws FrameworkException,
                   TransferException

Accepts the given order, which should be in either OrderStatus.PENDING_BUYER or OrderStatus.PENDING_SELLER status, and needs the delivery price to be already set. When the buyer hasn't yet chosen a payment type, it is required now. Also, when no amount was reserved, the confirmation password will be checked before performing the actual payment.

Throws:

TransferException - When there was a problem while reserving the amount, like there is no available balance

PasswordException - The given confirmation password is invalid

IllegalActionException - The given order is not in either OrderStatus.PENDING_BUYER or OrderStatus.PENDING_SELLER status

FrameworkException

addToCart

int addToCart(@NotNull
              @NotNull BasicAdVO adVO,
              java.math.BigDecimal quantity)
       throws FrameworkException,
              OutOfStockException,
              CannotBuyException

Adds the given product to the logged user's shopping cart, returning the total count of ads in the cart.
When the given quantity is null, the minimum allowed quantity on the shopping cart for the given product is assumed

Throws:

OutOfStockException - When the given quantity is greater than the available stock

FrameworkException

CannotBuyException

adjustAndGetMyCart

ShoppingCartDTO adjustAndGetMyCart()
                            throws FrameworkException

Returns the current logged user's shopping cart, adjusting all quantities

Throws:

FrameworkException

adjustShoppingCartAndGetData

OrderData adjustShoppingCartAndGetData(@NotNull
                                       @NotNull OrderVO vo)
                                throws FrameworkException

Perform adjustments to the shopping cart quantities and returns the data for it

Throws:

FrameworkException

checkCartStock

void checkCartStock(@NotNull
                    @NotNull UserLocatorVO seller,
                    @NotNull
                    @NotNull CurrencyVO currency)
             throws FrameworkException,
                    OutOfStockException

Checks that all items on the given cart are still on stock

Throws:

FrameworkException

OutOfStockException

checkout

ShoppingCartCheckoutResult checkout(@NotNull
                                    @NotNull ShoppingCartCheckoutParams dto)
                             throws FrameworkException,
                                    OutOfStockException,
                                    InsufficientBalanceException,
                                    CannotBuyException

Checks out the logged user's shopping cart with the given seller and currency, checking the confirmation password (if any), and reserving the amount when the delivery price is previously known (otherwise, the buyer still needs to confirm before the payment is done).

Returns:

A result containing the order and the remaining webshop ads added to the shopping cart.

Throws:

EntityNotFoundException - When there is no current shopping cart order with the given seller and currency

OutOfStockException - When at least one of the expected items exceeds the available stock

InsufficientBalanceException - When there was a problem while reserving the amount

PasswordException - The given confirmation password is invalid

CannotBuyException - When the seller has no visibility over buyer group

FrameworkException

countCartItems

int countCartItems()
            throws FrameworkException

Returns the total number of items in the logged user's shopping cart

Throws:

FrameworkException

getCheckoutData

OrderData getCheckoutData(@NotNull
                          @NotNull UserLocatorVO seller,
                          @NotNull
                          @NotNull CurrencyVO currency)
                   throws FrameworkException,
                          EntityNotFoundException

Returns data for checkout the cart items of the given seller and currency

Throws:

EntityNotFoundException - When there is no current shopping cart order with the given seller and currency

FrameworkException

getMyCart

ShoppingCartDTO getMyCart()
                   throws FrameworkException

Returns the current logged user's shopping cart, without adjusting any quantity

Throws:

FrameworkException

getOrderData

OrderData getOrderData(@NotNull
                       @NotNull OrderVO vo)
                throws FrameworkException

Returns data of an order

Throws:

FrameworkException

getUserSalesData

UserSalesData getUserSalesData(@NotNull
                               @NotNull UserLocatorVO locator)
                        throws FrameworkException

Returns data for viewing a user sales

Throws:

FrameworkException

modifyQuantityOnCart

int modifyQuantityOnCart(@NotNull
                         @NotNull BasicAdVO adVO,
                         java.math.BigDecimal quantity)
                  throws FrameworkException,
                         IllegalActionException,
                         OutOfStockException

Updates the quantity for the given product on the logged user's shopping cart returning the total count of ads in the cart.

Throws:

IllegalActionException - When the given ad is not in the logged user's shopping cart

OutOfStockException - When the new quantity is greater than the available stock

FrameworkException

reject

void reject(@NotNull
            @NotNull RejectOrderParams params)
     throws FrameworkException

Rejects the given order

Throws:

IllegalActionException - When the given order is not in either OrderStatus.PENDING_BUYER or OrderStatus.PENDING_SELLER statuses.

FrameworkException

removeCart

int removeCart(@NotNull
               @NotNull UserLocatorVO seller,
               CurrencyVO currency)
        throws FrameworkException

Removes the logged user's shopping cart for the given seller and currency returning the remaining count of ads in the cart

Throws:

FrameworkException

removeCartById

int removeCartById(@NotNull
                   @NotNull java.lang.Long id)
            throws FrameworkException

Same as CRUDService.remove(Long) but returning the total count of items present the whole shopping cart

Throws:

FrameworkException

See Also:

CRUDService.remove(java.lang.Long)

removeCartItem

int removeCartItem(@NotNull
                   @NotNull BasicAdVO adVO)
            throws FrameworkException

Removes the given product from the logged user's shopping cart returning the remaining count of ads in the cart.

Throws:

IllegalActionException - When the given ad is not in the logged user's shopping cart

FrameworkException

search

Page<OrderVO> search(@NotNull
                     @NotNull OrderQuery query)
              throws FrameworkException

Searches for orders based on OrderQuery

Throws:

FrameworkException

setDeliveryMethod

void setDeliveryMethod(@NotNull
                       @NotNull SetDeliveryMethodParams params)
                throws FrameworkException

Updates the delivery method information of an order when it is on the OrderStatus.PENDING_SELLER status and there is no delivery information yet. Afterwards, the new status will be OrderStatus.PENDING_BUYER for final approval.

Throws:

IllegalActionException - When the referenced order is not on the OrderStatus.PENDING_SELLER status or already has delivery information

FrameworkException

submitToBuyer

java.lang.Long submitToBuyer(@NotNull
                             @NotNull OrderDTO order)
                      throws FrameworkException,
                             OutOfStockException

Submits the given order for buyer approval

Throws:

OutOfStockException - When any of the order products have ran out of stock right before processing

FrameworkException