org.cyclos.services.marketplace

Interface OrderService

All Superinterfaces:

CRUDService<OrderDTO,OrderData,OrderDataParams>, Service

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

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.REALIZED.

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(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.
void	addToCart(java.lang.Long adId, java.math.BigDecimal quantity) Adds the given product to the logged user's shopping cart, returning the updated shopping cart.
void	checkCartStock(UserLocatorVO seller, CurrencyVO currency) Checks that all items on the given cart are still on stock
java.lang.Long	checkout(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(UserLocatorVO seller, 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, it's read-write because updates the messages.
UserSalesData	getUserSalesData(UserLocatorVO locator) Returns data for viewing an user sales
void	modifyQuantityOnCart(java.lang.Long adId, java.math.BigDecimal quantity) Updates the quantity for the given product on the logged user's shopping cart
void	reject(RejectOrderParams params) Rejects the given order
void	removeCart(UserLocatorVO seller, CurrencyVO currency) Removes the logged user's shopping cart for the given seller and currency
void	removeCartItem(java.lang.Long adId) Removes the given product from the logged user's shopping cart
Page<OrderVO>	search(OrderQuery query) Searches for orders based on OrderQuery
void	setDeliveryMethod(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(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(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

void addToCart(java.lang.Long adId,
               java.math.BigDecimal quantity)
        throws FrameworkException,
               OutOfStockException,
               CannotBuyException

Adds the given product to the logged user's shopping cart, returning the updated shopping 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

checkCartStock

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

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

Throws:

FrameworkException

OutOfStockException

checkout

java.lang.Long checkout(ShoppingCartCheckoutParams dto)
                 throws FrameworkException,
                        OutOfStockException,
                        TransferException,
                        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)

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

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

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(UserLocatorVO seller,
                          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, it's read-write because updates the messages.

Throws:

FrameworkException

getUserSalesData

UserSalesData getUserSalesData(UserLocatorVO locator)
                        throws FrameworkException

Returns data for viewing an user sales

Throws:

FrameworkException

modifyQuantityOnCart

void modifyQuantityOnCart(java.lang.Long adId,
                          java.math.BigDecimal quantity)
                   throws FrameworkException,
                          IllegalActionException,
                          OutOfStockException

Updates the quantity for the given product on the logged user's shopping 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(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

void removeCart(UserLocatorVO seller,
                CurrencyVO currency)
         throws FrameworkException

Removes the logged user's shopping cart for the given seller and currency

Throws:

FrameworkException

removeCartItem

void removeCartItem(java.lang.Long adId)
             throws FrameworkException

Removes the given product from the logged user's shopping cart

Throws:

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

FrameworkException

search

Page<OrderVO> search(OrderQuery query)
              throws FrameworkException

Searches for orders based on OrderQuery

Throws:

FrameworkException

setDeliveryMethod

void setDeliveryMethod(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(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