com.adobe.cq.commerce.api

Interface CommerceSession

All Known Implementing Classes:

AbstractJcrCommerceSession

public interface CommerceSession

The CommerceSession provides anonymous or authenticated access to a (possibly remote) commerce server.

Session persistence is divided into two main parts: the cart entries (each one modeled by the CartEntry interface), and the various order properties (collectively modeled by a Map<String, Object>).

In theory the various order properties could be updated as required via one (or more) calls to updateOrder(), and then the order submitted via an empty call to placeOrder(). However, in practice, security constraints (such as being forbidden from storing CCV values) necessitate passing some of the order's properties in the final (placeOrder()) call.

It's up to the individual implementation to determine how many check-out steps there should be, and how much information to include (only) in the final call.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	CommerceSession.CartEntry CartEntry represents shopping cart line-items with a certain product and quantity.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	PN_QUANTITY The property name for CartEntry quantity when passed in the property map.
static java.lang.String	PN_READONLY Property name for read-only CartEntry.

Method Summary

Modifier and Type	Method and Description
void	addCartEntry(Product product, int quantity) Add a new entry to the cart.
void	addCartEntry(Product product, int quantity, java.util.Map<java.lang.String,java.lang.Object> properties) Add a new entry to the cart.
void	addPromotion(java.lang.String path) Apply a promotion to this session's cart.
void	addVoucher(java.lang.String code) Apply a voucher to this session's cart.
void	deleteCartEntry(int entryNumber) Delete an existing cart entry.
java.util.List<java.lang.String>	getAvailableCountries() Return the list of countries supported for this session/cart.
java.util.List<PaymentMethod>	getAvailablePaymentMethods() Return the list of payment methods supported for this session/cart.
java.util.List<ShippingMethod>	getAvailableShippingMethods() Return the list of shipping methods supported for this session/cart.
java.util.List<CommerceSession.CartEntry>	getCartEntries() Get the cart entries as a List.
int	getCartEntryCount() Get the number of cart entries.
java.lang.String	getCartPreTaxPrice() Deprecated. since 5.6, use getCartPrice(Predicate) instead.
java.lang.String	getCartPrice(Predicate filter) Shortcut for getting a formatted string of the first applicable price, according to the filter.
java.util.List<PriceInfo>	getCartPriceInfo(Predicate filter) Get detailed price information about the cart filtered by the provided predicate (usually a PriceFilter).
java.lang.String	getCartTax() Deprecated. since 5.6, use getCartPrice(Predicate) instead.
java.lang.String	getCartTotalPrice() Deprecated. since 5.6, use getCartPrice(Predicate) instead.
java.util.Map<java.lang.String,java.lang.Object>	getOrder() Get the current order details.
java.util.Map<java.lang.String,java.lang.String>	getOrderDetails() Deprecated. since 5.6, use getOrder() instead.
java.util.Map<java.lang.String,java.lang.Object>	getOrderDetails(java.lang.String predicate) Get a subset of the current order details.
java.lang.String	getOrderId() Get a unique ID which identifies the current cart/order.
java.lang.String	getOrderShipping() Deprecated. since 5.6, use getCartPrice(Predicate) instead.
java.lang.String	getOrderTotalPrice() Deprecated. since 5.6, use getCartPrice(Predicate) instead.
java.lang.String	getOrderTotalTax() Deprecated. since 5.6, use getCartPrice(Predicate) instead.
PlacedOrder	getPlacedOrder(java.lang.String orderId) Fetch a specific (previously-placed) order.
PlacedOrderResult	getPlacedOrders(java.lang.String predicate, int pageNumber, int pageSize, java.lang.String sortId) Get a list of previously placed orders.
java.lang.String	getPriceInfo(Product product) Deprecated. since 5.6, use getProductPrice(Product)
java.lang.String	getProductPrice(Product product) Shortcut for getting a formatted string for the first price for a product.
java.lang.String	getProductPrice(Product product, Predicate filter) Shortcut for getting a formatted string for the first applicable price for a product as defined by the provided predicate (usually a PriceFilter).
java.util.List<PriceInfo>	getProductPriceInfo(Product product) Get a list of all detailed price infos for a product See PriceInfo for more details.
java.util.List<PriceInfo>	getProductPriceInfo(Product product, Predicate filter) Get a list of detailed price infos for a product filtered by the provided predicate (usually a PriceFilter).
java.util.List<PromotionInfo>	getPromotions() Get a list of promotions that are active for this cart.
SmartListManager	getSmartListManager() Get the smart list manager for the commerce service implementation.
java.util.Locale	getUserLocale() Return the forced user locale or null, if no locale was set before.
java.util.List<VoucherInfo>	getVoucherInfos() Get a list of vouchers that were added to this cart via addVoucher(String), or that were assigned by the commerce engine.
java.util.List<Voucher>	getVouchers() Deprecated. since 5.6.200; use getVoucherInfos() instead
void	logout() Logs the current user out.
void	modifyCartEntry(int entryNumber, int quantity) Modify quantity of an existing cart entry.
void	modifyCartEntry(int entryNumber, java.util.Map<java.lang.String,java.lang.Object> delta) Modify properties of an existing cart entry.
void	placeOrder(java.util.Map<java.lang.String,java.lang.Object> orderDetailsDelta) Submit the current order.
void	removePromotion(java.lang.String path) Remove a promotion.
void	removeVoucher(java.lang.String code) Remove a voucher that was previously added with addVoucher(String).
void	setUserLocale(java.util.Locale locale) Forces a certain locale for the current user.
void	submitOrder(java.util.Map<java.lang.String,java.lang.String> orderDetailsDelta) Deprecated. since 5.6, use placeOrder(java.util.Map<java.lang.String, java.lang.Object>) instead.
boolean	supportsClientsidePromotionResolution() Client-side promotion resolution allows a ClientContext store (the CartMgr in the OOTB implementation) to resolve promotions and then adjust the current CommerceSession via addPromotion(String) and removePromotion(String).
void	updateOrder(java.util.Map<java.lang.String,java.lang.Object> delta) Update a subset of the current order details.
void	updateOrderDetails(java.util.Map<java.lang.String,java.lang.Object> details, java.lang.String predicate) A predicate-based update call which makes it easier to update/clear a particular payment method, shipping method, address, etc.
void	updateOrderDetails(java.util.Map<java.lang.String,java.lang.String> delta) Deprecated. since 5.6, use updateOrder(java.util.Map<java.lang.String, java.lang.Object>) instead.

Field Detail

PN_QUANTITY

static final java.lang.String PN_QUANTITY

The property name for CartEntry quantity when passed in the property map.

See Also:

Constant Field Values

PN_READONLY

static final java.lang.String PN_READONLY

Property name for read-only CartEntry.

See Also:

Constant Field Values

Method Detail

logout

void logout()
     throws CommerceException

Logs the current user out.

Throws:

CommerceException

setUserLocale

void setUserLocale(java.util.Locale locale)

Forces a certain locale for the current user. Prices will be returned according the locale's currency, if available.

Parameters:

locale -

getUserLocale

java.util.Locale getUserLocale()

Return the forced user locale or null, if no locale was set before.

Returns:

getAvailableCountries

java.util.List<java.lang.String> getAvailableCountries()
                                                throws CommerceException

Return the list of countries supported for this session/cart. While many implementations will in fact return a session-independent result, putting the method on CommerceSession allows more sophisticated implementations to perform session/cart-dependent processing (such as export restrictions on ITAR products).

Returns:

Throws:

CommerceException

getAvailableShippingMethods

java.util.List<ShippingMethod> getAvailableShippingMethods()
                                                    throws CommerceException

Return the list of shipping methods supported for this session/cart. While many implementations will in fact return a session-independent result, putting the method on CommerceSession allows more sophisticated implementations to perform session/cart-dependent processing (such as air-freight restrictions on high-VOC products).

Returns:

Throws:

CommerceException

getAvailablePaymentMethods

java.util.List<PaymentMethod> getAvailablePaymentMethods()
                                                  throws CommerceException

Return the list of payment methods supported for this session/cart. While many implementations will in fact return a session-independent result, putting the method on CommerceSession allows more sophisticated implementations to perform session/cart-dependent processing (such as locale-specific payment vendors).

Returns:

Throws:

CommerceException

getProductPriceInfo

java.util.List<PriceInfo> getProductPriceInfo(Product product)
                                       throws CommerceException

Get a list of all detailed price infos for a product See PriceInfo for more details.

Parameters:

product -

Returns:

Throws:

CommerceException

getProductPriceInfo

java.util.List<PriceInfo> getProductPriceInfo(Product product,
                                              Predicate filter)
                                       throws CommerceException

Get a list of detailed price infos for a product filtered by the provided predicate (usually a PriceFilter).

See PriceInfo for more details.

Parameters:

product - The product.

filter - An optional predicate used for filtering the PriceInfos. Pass null to fetch all PriceInfos.

Returns:

A list of all PriceInfos which match the provided predicate.

Throws:

CommerceException

getProductPrice

java.lang.String getProductPrice(Product product,
                                 Predicate filter)
                          throws CommerceException

Shortcut for getting a formatted string for the first applicable price for a product as defined by the provided predicate (usually a PriceFilter).

See PriceInfo for more details.

Parameters:

product - The product

filter - An optional predicate used for filtering the PriceInfos. Pass null to fetch all PriceInfos.

Returns:

A formatted price string.

Throws:

CommerceException

getProductPrice

java.lang.String getProductPrice(Product product)
                          throws CommerceException

Shortcut for getting a formatted string for the first price for a product.

See PriceInfo for more details.

Parameters:

product - The product.

Returns:

A formatted price string.

Throws:

CommerceException

getCartEntryCount

int getCartEntryCount()
               throws CommerceException

Get the number of cart entries.

Returns:

Throws:

CommerceException

getCartEntries

java.util.List<CommerceSession.CartEntry> getCartEntries()
                                                  throws CommerceException

Get the cart entries as a List.

Returns:

Throws:

CommerceException

getCartPriceInfo

java.util.List<PriceInfo> getCartPriceInfo(Predicate filter)
                                    throws CommerceException

Get detailed price information about the cart filtered by the provided predicate (usually a PriceFilter).

Current components expect the following prices, in this order:

1. "CART" (cart subtotal, generally pre-tax)
2. "ORDER" (order total, generally including tax and shipping)

Examples:

 
 // get the cart subtotal
 session.getCartPrice(null);
 // get cart total
 session.getCartPrice(new PriceFilter("POST_TAX"));
 // get order tax
 session.getCartPrice(new PriceFilter("ORDER", "TAX"));
 
 

Parameters:

filter - An optional predicate used for filtering the PriceInfos. Pass null to fetch all PriceInfos.

Returns:

a list of prices, can be empty if no price matches.

Throws:

CommerceException

getCartPrice

java.lang.String getCartPrice(Predicate filter)
                       throws CommerceException

Shortcut for getting a formatted string of the first applicable price, according to the filter.

Parameters:

filter - An optional predicate used for filtering the PriceInfos. Pass null to fetch all PriceInfos.

Returns:

Formatted price string of first matching price

Throws:

CommerceException

See Also:

getCartPriceInfo(Predicate)

addCartEntry

void addCartEntry(Product product,
                  int quantity)
           throws CommerceException

Add a new entry to the cart.

Parameters:

product - The product to add

quantity - The number of items to add

Throws:

CommerceException

addCartEntry

void addCartEntry(Product product,
                  int quantity,
                  java.util.Map<java.lang.String,java.lang.Object> properties)
           throws CommerceException

Add a new entry to the cart.

Parameters:

product - The product to add

quantity - The number of items to add

properties - the Map of additional properties (key-value pairs)

Throws:

CommerceException

modifyCartEntry

void modifyCartEntry(int entryNumber,
                     int quantity)
              throws CommerceException

Modify quantity of an existing cart entry.

Parameters:

entryNumber - The cart entry's number

quantity - The new quantity

Throws:

CommerceException

modifyCartEntry

void modifyCartEntry(int entryNumber,
                     java.util.Map<java.lang.String,java.lang.Object> delta)
              throws CommerceException

Modify properties of an existing cart entry.

Parameters:

entryNumber - the cart entry number

delta - a Map of properties (key-value pairs) to be modified

Throws:

CommerceException

deleteCartEntry

void deleteCartEntry(int entryNumber)
              throws CommerceException

Delete an existing cart entry.

Parameters:

entryNumber - The cart entry's number

Throws:

CommerceException

addVoucher

void addVoucher(java.lang.String code)
         throws CommerceException

Apply a voucher to this session's cart.

Parameters:

code - the voucher's code

Throws:

CommerceException

removeVoucher

void removeVoucher(java.lang.String code)
            throws CommerceException

Remove a voucher that was previously added with addVoucher(String).

Parameters:

code - the voucher's code

Throws:

CommerceException

getVoucherInfos

java.util.List<VoucherInfo> getVoucherInfos()
                                     throws CommerceException

Get a list of vouchers that were added to this cart via addVoucher(String), or that were assigned by the commerce engine.

Returns:

Throws:

CommerceException

supportsClientsidePromotionResolution

boolean supportsClientsidePromotionResolution()

Client-side promotion resolution allows a ClientContext store (the CartMgr in the OOTB implementation) to resolve promotions and then adjust the current CommerceSession via addPromotion(String) and removePromotion(String). In contrast, if a CommerceSession wishes to resolve its own promotions on the server, it should return false here and need only implement getPromotions() to return the resolved promotion info.

Returns:

true if underlying implementation has support

addPromotion

void addPromotion(java.lang.String path)
           throws CommerceException

Apply a promotion to this session's cart.

Parameters:

path - A string uniquely identifying the promotion (generally a path)

Throws:

CommerceException

removePromotion

void removePromotion(java.lang.String path)
              throws CommerceException

Remove a promotion.

Parameters:

path - A string uniquely identifying the promotion (generally a path)

Throws:

CommerceException

getPromotions

java.util.List<PromotionInfo> getPromotions()
                                     throws CommerceException

Get a list of promotions that are active for this cart. Promotions might have been added via addPromotion(String), or might have been assigned by the commerce engine.

Returns:

Throws:

CommerceException

getOrderId

java.lang.String getOrderId()
                     throws CommerceException

Get a unique ID which identifies the current cart/order. Note that the semantics of this ID are highly implementation-dependent. Hybris, for example, will return null until the first product is added to the cart. Other systems may have different semantics.

Returns:

A unique ID

Throws:

CommerceException

getOrderDetails

java.util.Map<java.lang.String,java.lang.Object> getOrderDetails(java.lang.String predicate)
                                                          throws CommerceException

Get a subset of the current order details. The OOTB commerce components assume support for the following predicates:

• CommerceConstants.BILLING_ADDRESS_PREDICATE
• CommerceConstants.SHIPPING_ADDRESS_PREDICATE

In addition, implementations would be expected to support predicates defined by any available ShippingMethods and PaymentMethods.

Parameters:

predicate - A String identifying a predicate which in turn identifies the subset.

Returns:

A Map of name/value pairs

Throws:

CommerceException

getOrder

java.util.Map<java.lang.String,java.lang.Object> getOrder()
                                                   throws CommerceException

Get the current order details. In order to facilitate usage within forms, it is suggested that implementations to prefix any predicate details with their predicate (eg: "billing.street").

Returns:

A Map of name/value pairs

Throws:

CommerceException

updateOrderDetails

void updateOrderDetails(java.util.Map<java.lang.String,java.lang.Object> details,
                        java.lang.String predicate)
                 throws CommerceException

A predicate-based update call which makes it easier to update/clear a particular payment method, shipping method, address, etc.

Parameters:

details - A Map containing the order properties to update.

predicate - A predicate to assign to the properties.

Throws:

CommerceException

updateOrder

void updateOrder(java.util.Map<java.lang.String,java.lang.Object> delta)
          throws CommerceException

Update a subset of the current order details. Entries in the Map which do not yet exist will be added to the order, while entries that already exist will be updated.

Parameters:

delta - A Map of name/value pairs

Throws:

CommerceException

placeOrder

void placeOrder(java.util.Map<java.lang.String,java.lang.Object> orderDetailsDelta)
         throws CommerceException

Submit the current order. Note that the semantics of submitting an order are somewhat implementation-dependent.

Parameters:

orderDetailsDelta - An optional set of order details to update before submission. Useful for passing properties which cannot be stored, such as the CCV.

Throws:

CommerceException

getPlacedOrders

PlacedOrderResult getPlacedOrders(java.lang.String predicate,
                                  int pageNumber,
                                  int pageSize,
                                  java.lang.String sortId)
                           throws CommerceException

Get a list of previously placed orders.

Parameters:

predicate - An optional implementation-specific predicate name. Implementations should support at least CommerceConstants.OPEN_ORDERS_PREDICATE.

pageNumber - the requested page number of the list of placed orders

pageSize - the number of orders in a page

sortId - the identifier of the sorting used to sort the list of placed orders

Returns:

a PlacedOrderResult object which contains the list of implementation-specific order summary info, the pagination and sorting info of the returned orders. If PaginationInfo is null in the returned object then the commerce implementation doesn't support pagination. If the returned object does not contain any CommerceSort object then the returned orders are unsorted.

Throws:

CommerceException

getPlacedOrder

PlacedOrder getPlacedOrder(java.lang.String orderId)
                    throws CommerceException

Fetch a specific (previously-placed) order.

Parameters:

orderId - An implementation-specific id identifying the placed order

Returns:

a PlacedOrder

Throws:

CommerceException

getSmartListManager

SmartListManager getSmartListManager()

Get the smart list manager for the commerce service implementation.

Returns:

A SmartListManager of order predicate names.

getPriceInfo

@Deprecated
java.lang.String getPriceInfo(Product product)
                                   throws CommerceException

Deprecated. since 5.6, use getProductPrice(Product)

Get formatted price for a product.

Returns:

Throws:

CommerceException

getCartPreTaxPrice

@Deprecated
java.lang.String getCartPreTaxPrice()
                                         throws CommerceException

Deprecated. since 5.6, use getCartPrice(Predicate) instead.

Get formatted pre-tax price.

Returns:

Throws:

CommerceException

getCartTax

@Deprecated
java.lang.String getCartTax()
                                 throws CommerceException

Deprecated. since 5.6, use getCartPrice(Predicate) instead.

Get formatted tax.

Returns:

Throws:

CommerceException

getCartTotalPrice

@Deprecated
java.lang.String getCartTotalPrice()
                                        throws CommerceException

Deprecated. since 5.6, use getCartPrice(Predicate) instead.

Get formatted cart total.

Returns:

Throws:

CommerceException

getOrderShipping

@Deprecated
java.lang.String getOrderShipping()
                                       throws CommerceException

Deprecated. since 5.6, use getCartPrice(Predicate) instead.

Get formatted shipping price.

Returns:

Throws:

CommerceException

getOrderTotalTax

@Deprecated
java.lang.String getOrderTotalTax()
                                       throws CommerceException

Deprecated. since 5.6, use getCartPrice(Predicate) instead.

Get formatted total tax.

Returns:

Throws:

CommerceException

getOrderTotalPrice

@Deprecated
java.lang.String getOrderTotalPrice()
                                         throws CommerceException

Deprecated. since 5.6, use getCartPrice(Predicate) instead.

Get formatted order total.

Returns:

Throws:

CommerceException

getVouchers

@Deprecated
java.util.List<Voucher> getVouchers()
                                         throws CommerceException

Deprecated. since 5.6.200; use getVoucherInfos() instead

Get a list of vouchers that were added to this cart via addVoucher(String).

Returns:

Throws:

CommerceException

updateOrderDetails

@Deprecated
void updateOrderDetails(java.util.Map<java.lang.String,java.lang.String> delta)
                             throws CommerceException

Deprecated. since 5.6, use updateOrder(java.util.Map<java.lang.String, java.lang.Object>) instead.

Update a set of details within the current order.

Parameters:

delta -

Throws:

CommerceException

getOrderDetails

@Deprecated
java.util.Map<java.lang.String,java.lang.String> getOrderDetails()
                                                                      throws CommerceException

Deprecated. since 5.6, use getOrder() instead.

Get the full details of the current order.

Returns:

Throws:

CommerceException

submitOrder

@Deprecated
void submitOrder(java.util.Map<java.lang.String,java.lang.String> orderDetailsDelta)
                      throws CommerceException

Deprecated. since 5.6, use placeOrder(java.util.Map<java.lang.String, java.lang.Object>) instead.

Submit the current order.

Parameters:

orderDetailsDelta -

Throws:

CommerceException