GetContractUnitPriceCmd

All Known Subinterfaces:: GetCustomContractUnitPriceCmd

All Known Implementing Classes:: AbstractGetEntitledPriceCmdImpl, AbstractGetPriceCmdImpl, CatalogFilterGetContractUnitPriceCmdImpl, CompositeGetContractUnitPriceCmdImpl, EnsureOffersExistGetContractUnitPriceCmdImpl, GetCachedEntitledPriceCmdImpl, GetContractUnitPriceCmdImpl, GetExternalEntitledPriceCmdImpl, GetExternalEntitledPriceWithCacheCheckCmdImpl, PriceRuleGetContractUnitPriceCmdImpl

public interface GetContractUnitPriceCmd

This interface calculates the prices for one or more catalog entries with the intent of displaying them in the shopping cart or current order.

There are two ways to specify the catalog entries for which prices should be calculated.

setCatEntryId(Long) - Only one catalog entry's prices are to be calculated. Using this method puts the command in "single catalog entry mode" or simply, single mode.
setCatEntryPrices(CatEntryPrices[]) - Multiple catalog entries' prices are to be calculated. Using this method puts the command in "batch mode."

For each catalog entry specified, there may be multiple trading agreements used to calculate the price, and so the price for each of these trading agreements is returned. Among these prices, there is a "best" price which is returned as well. The best price is usually the lowest price among all trading agreements for a given catalog entry identifier, but this behavior can be customized.

The information related to price calculations for all catalog entries is returned through the getCatEntryPrices() method. This method will return the correct information regardless of whether single mode or batch mode is used. Each of the returned CatEntryPrices objects contains the relevant information for a single catalog entry. This interface also provides methods to access the same information on the first catalog entry for which prices were calculated. In other words, the first CatEntryPrices object in the array returned by getCatEntryPrices() can be accessed by using the methods on that object, or by calling analogous get methods on this command. This is done mainly for backwards compatibility and compatibility with similar interfaces (see below for similar interfaces).

The table below describes the mapping between methods of this command and those of the first CatEntryPrices returned by getCatEntryPrices():

GetContractUnitPriceCmd method	CatEntryPrices method	Best or All Prices?
`getTradingId()`	`CatEntryPrices.getTradingId()`	Best
`getTcId()`	`CatEntryPrices.getTcId()`	Best
`getOfferId()`	`CatEntryPrices.getOfferId()`	Best
`getOffer()`	`CatEntryPrices.getOffer()`	Best
`getBasePrice()`	`CatEntryPrices.getBasePrice()`	Best
`getPrice()`	`CatEntryPrices.getUnitPrice()`	Best
`getApplicableTradingIds()`	`CatEntryPrices.getAllTradingIds()`	All
Not applicable	`CatEntryPrices.getTradingTcIds()`	All
Not applicable	`CatEntryPrices.getOfferIds()`	All
Not applicable	`CatEntryPrices#getOffers()`	All
Not applicable	`CatEntryPrices.getTradingBasePrices()`	All
`getApplicableTradingUnitPrices()`	`CatEntryPrices.getTradingUnitPrices()`	All

Note that the methods that return price information per trading agreement (those with the "all" designation) for a catalog entry also include the best price among them.

This command is closely related to GetContractSpecialPriceCmd and GetProductContractUnitPriceCmd. In fact, the default implementation is the same for all three. However, because they are used in different situations, it is possible to customize each situation differently.

To customize price calculations when viewing the shopping cart or current order, register a class that implements this interface (or a subclass of an existing class such as GetContractUnitPriceCmdImpl) in the command registry. The calculations for the other commands will be unaffected.

Field Summary

Fields
Modifier and Type Field and Description

static java.lang.String COPYRIGHT
IBM copyright notice field.

static java.lang.String NAME
The name of this command.

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`COPYRIGHT` IBM copyright notice field.
`static java.lang.String`	`NAME` The name of this command.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`java.lang.Long[]`	`getApplicableTradingIds()` Returns the identifiers of the trading agreements that were used to determine the prices for a catalog entry.
`MonetaryAmount[]`	`getApplicableTradingUnitPrices()` Returns the prices that were determined for each of the applied trading agreements for a catalog entry.
`MonetaryAmount`	`getBasePrice()` Returns the best price of the input catalog entry before any currency conversions.
`CatEntryPrices[]`	`getCatEntryPrices()` Returns the price related information for the input catalog entries.
`com.ibm.commerce.order.objects.OfferAccessBean`	`getOffer()` Returns the offer access bean that was used to determine the price.
`java.lang.Long`	`getOfferId()` Returns the identifier of the offer that was used to determine the price.
`MonetaryAmount`	`getPrice()` Returns the best price of the catalog entry in the requested currency.
`java.lang.Long`	`getTcId()` Returns the identifier of the term condition which was used to calculate the best price.
`java.lang.Long`	`getTradingId()` Returns the identifier of the trading agreement which was used to calculate the best price.
`void`	`reset()` Resets this command so that it is in its default state.
`void`	`setCatEntryId(java.lang.Long anCatEntryId)` Sets the identifier of the catalog entry whose price is to be calculated.
`void`	`setCatEntryPrices(CatEntryPrices[] aCatEntryPrices)` Sets the information of one or more catalog entries whose prices are to be calculated.
`void`	`setCurrency(java.lang.String astrCurrency)` Sets the desired currency to be used for the output price.
`void`	`setErrorMode(boolean aErrorMode)` Sets whether an exception will be thrown when the price cannot be found for the input catalog entry.
`void`	`setMemberId(java.lang.Long anMemberId)` Sets the member identifier to be used for determining which trading agreements are valid to use to calculate the price.
`void`	`setOfferIds(java.lang.Long[] aOfferIds)` Sets the identifiers of the input offers to be used for price.
`void`	`setOrganizationId(java.lang.Long anOrganizationId)` Sets the organization identifier to be used in conjunction with the `member identifier` for verifying and searching for trading agreements.
`void`	`setQuantity(QuantityAmount aQuantityAmount)` Sets the quantity of the input catalog entry that is to be priced.
`void`	`setStoreId(java.lang.Integer aStoreId)` Sets the identifier of the store to be used for calculating the price.
`void`	`setTradingIds(java.lang.Long[] aTradingIds)` Sets the identifiers of the input trading agreements.

- Field Detail
  - COPYRIGHT
```
static final java.lang.String COPYRIGHT
```
    IBM copyright notice field.
    
    See Also:
    
    Constant Field Values
  - NAME
```
static final java.lang.String NAME
```
    The name of this command.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getApplicableTradingIds
```
java.lang.Long[] getApplicableTradingIds()
```
    Returns the identifiers of the trading agreements that were used to determine the prices for a catalog entry.
    If this command is used in single mode, these identifiers will reflect the trading agreements that were specified for that catalog entry. If this command is used in batch mode, then these identifiers will reflect the trading agreements that were used for the first catalog entry in the input array.
    
    Returns:
    
    The identifiers of all the trading agreements that were used to obtain the prices for the specified catalog entry. This array may be null or empty if getPrice() returns null.
  - getApplicableTradingUnitPrices
```
MonetaryAmount[] getApplicableTradingUnitPrices()
```
    Returns the prices that were determined for each of the applied trading agreements for a catalog entry. Each element in the returned array corresponds to the element at the same index in the array returned by getApplicableTradingIds().
    If this command is used in single mode, these prices will reflect the prices that were found for the input catalog entry. If this command is used in batch mode, then these prices will reflect the prices that were used for the first catalog entry in the input array.
    
    Returns:
    
    The unit price amounts of the specified catalog entry in that each of them was determined individually for its corresponding trading agreement. This array may be null or empty if getPrice() returns null.
  - getBasePrice
```
MonetaryAmount getBasePrice()
```
    Returns the best price of the input catalog entry before any currency conversions. This is only set when the requested currency is different from the base currency, in which case the base price must be converted to the requested price.
    If this command is used in single mode, this price will be for the input catalog entry. If this command is used in batch mode, then this price will be for the first catalog entry in the input array.
    
    Returns:
    
    The best price found for the specified catalog entry. This value will be null if no currency conversion was performed to obtain the price in the requested currency.
  - getCatEntryPrices
```
CatEntryPrices[] getCatEntryPrices()
```
    Returns the price related information for the input catalog entries. Each element in the array will have various information set as a result of calling this command.
    The following values reflect information about the best price for the catalog entry:
    The following values reflect information about all prices for the catalog entry:
    - CatEntryPrices.getAllTradingIds()
    - CatEntryPrices.getTradingTcIds()
    - CatEntryPrices.getOfferIds()
    - CatEntryPrices#getOffers()
    - CatEntryPrices.getTradingBasePrices()
    - CatEntryPrices.getTradingUnitPrices()
    If this command is used in single mode, this array will contain one element corresponding to the input catalog entry. If this command is used in batch mode, then this array will contain the same catalog entry information, in the same order, as the input array.
    In the latter case, the array itself is not guaranteed to be the same as the input array, and the elements are not guaranteed to be the same as those in the input array. However, for optimization purposes, they may be the same array and elements. In other words, users of this command should make no assumptions that the input array and elements are the same or different from the returned array.
    Returns:
    
    The price related information of the input catalog entries. This array will not be null or empty. See setCatEntryPrices(com.ibm.commerce.price.commands.CatEntryPrices[]) for information on the input array.
  - getOffer
```
com.ibm.commerce.order.objects.OfferAccessBean getOffer()
```
    Returns the offer access bean that was used to determine the price.
    If this command is used in single mode, this offer will be for the input catalog entry. If this command is used in batch mode, then this offer will be for the first catalog entry in the input array.
    
    Returns:
    
    The offer access bean associated with the offer that was used to determine the best price, or null if no offer was used or getPrice() returns null.
  - getOfferId
```
java.lang.Long getOfferId()
```
    Returns the identifier of the offer that was used to determine the price.
    If this command is used in single mode, this offer will be for the input catalog entry. If this command is used in batch mode, then this offer will be for the first catalog entry in the input array.
    
    Returns:
    
    The identifier of the offer that was used to determine the price, or null if no offer was used or getPrice() returns null.
  - getPrice
```
MonetaryAmount getPrice()
```
    Returns the best price of the catalog entry in the requested currency.
    If this command is used in single mode, this price will be for the input catalog entry. If this command is used in batch mode, then this price will be for the first catalog entry in the input array.
    
    Returns:
    
    The best price of the catalog entry in the requested currency. This value may be null if the error mode is set to true and no price was found.
  - getTcId
```
java.lang.Long getTcId()
```
    Returns the identifier of the term condition which was used to calculate the best price.
    If this command is used in single mode, this term condition will be for the input catalog entry. If this command is used in batch mode, then this term condition will be for the first catalog entry in the input array.
    
    Returns:
    
    The identifier of the term condition that was used to determine the best price. This value may be null if no term condition was used to determine the price or getPrice() returns null.
  - getTradingId
```
java.lang.Long getTradingId()
```
    Returns the identifier of the trading agreement which was used to calculate the best price.
    If this command is used in single mode, this trading agreement will be for the input catalog entry. If this command is used in batch mode, then this trading agreement will be for the first catalog entry in the input array.
    
    Returns:
    
    The identifier of the trading agreement that was used to determine the best price. This value may be null if no trading agreement was used to determine the price or getPrice() returns null.
  - reset
```
void reset()
```
    Resets this command so that it is in its default state.
    The original definition of this method described in com.ibm.websphere.command.Command.reset() requires that this method sets the output properties to the values they had before the execute() method was run. The original definition also requires that after calling this method, isReadyToCallExecute() method returns true.
    In addition to the above, this command requires that input parameters must also be set to their original default values. For example, consider the following sequence of calls:
```
 GetContractUnitPriceCmd cmd = ...
 cmd.setCatEntryId(id);
 cmd.reset();
 cmd.setCatEntryPrices(catEntryPricesArray);
 
```
    After these calls are executed, cmd will behave as though only setCatEntryPrices(CatEntryPrices[]) had been called.
  - setCatEntryId
```
void setCatEntryId(java.lang.Long anCatEntryId)
```
    Sets the identifier of the catalog entry whose price is to be calculated. Using this method sets up the command in single mode. If setCatEntryPrices(CatEntryPrices[]) is called with a non-null value, the catalog entries in that array will be used (which sets up this command in batch mode) and will override the catalog entry set by this method.
    Either this method or setCatEntryPrices(CatEntryPrices[]) must be called with non-null parameters before executing this command. The default value is null.
    
    Parameters:
    
    anCatEntryId - The identifier of the catalog entry whose price is to be calculated. If null, single mode will not be enabled and setting up batch mode by calling setCatEntryPrices(CatEntryPrices[]) will be required.
  - setCatEntryPrices
```
void setCatEntryPrices(CatEntryPrices[] aCatEntryPrices)
```
    Sets the information of one or more catalog entries whose prices are to be calculated. Calling this method with a non-null, non-empty array will set up this command in batch mode and override the catalog entry set by setCatEntryId(Long).
    See setTradingIds(Long[]) for a description of how the trading agreements in the CatEntryPrices specified by this method are used to determine price.
    Either this method or setCatEntryId(Long) must be called with non-null parameters before executing this command. The default value is null.
    
    Parameters:
    
    aCatEntryPrices - The information of one or more catalog entries whose prices are to be retrieved. If null, the value from setCatEntryId(Long) will be used. If empty, the behavior of this command is undefined.
  - setCurrency
```
void setCurrency(java.lang.String astrCurrency)
```
    Sets the desired currency to be used for the output price.
    This input value is optional. The default value is obtained from another source, such as CurrencyManager#getCurrency(StoreAccessBean, String, Integer). This currency will only be used in conjunction with setCatEntryId(Long).
    
    Parameters:
    
    astrCurrency - The currency to look up the price. If null, the default value will be used. If the supplied currency is empty or not supported for the store, a default store currency will be used.
  - setErrorMode
```
void setErrorMode(boolean aErrorMode)
```
    Sets whether an exception will be thrown when the price cannot be found for the input catalog entry.
    This input value is optional. The default value is true.
    
    Parameters:
    
    aErrorMode - True indicates an exception will be thrown when a price cannot be found, false indicates exceptions will be ignored and null will be returned for the price instead.
  - setMemberId
```
void setMemberId(java.lang.Long anMemberId)
```
    Sets the member identifier to be used for determining which trading agreements are valid to use to calculate the price. See setTradingIds(Long[]) for details on how the trading agreements are used.
    This input value is optional. The default value is obtained from CommandContext#getUserId().
    
    Parameters:
    
    anMemberId - The member identifier to be used to verify the input list of trading agreements. If null, the default value will be used.
  - setOfferIds
```
void setOfferIds(java.lang.Long[] aOfferIds)
```
    Sets the identifiers of the input offers to be used for price.
    This input value is optional. The default value is the list of all qualifying offers. These offers will only be used in conjunction with setCatEntryId(Long).
    
    Parameters:
    
    aOfferIds - The reference number of one or more offers that are to be used for determining the price. If null or empty, then the "best" of all qualifying offers will be used. Otherwise, the "best" of the specified offers will be returned.
  - setOrganizationId
```
void setOrganizationId(java.lang.Long anOrganizationId)
```
    Sets the organization identifier to be used in conjunction with the member identifier for verifying and searching for trading agreements. This value will only be used when the member identifier provided is different from the CommandContext#getUserId().
    This input value is optional. The default value is the EntitlementContext#getActiveOrganizationId().
    
    Parameters:
    
    anOrganizationId - The organization identifier to be used in conjunction with the member identifier to verify the input list of trading agreements. If null, the default value will be used.
  - setQuantity
```
void setQuantity(QuantityAmount aQuantityAmount)
```
    Sets the quantity of the input catalog entry that is to be priced. The quantity helps determine which prices are to be used when there are multiple price ranges.
    For example, consider the table below:
    
    Quantity range Price per unit
    
    1-5 10 USD
    
    6-10 9 USD
    
    If the quantity specified by this method is 2, the price per unit will be 10 USD. If the quantity is 8, the price per unit will be 9 USD.
    If the quantity amount is not specified, then the nominal quantity (rounded up to the nearest multiple as specified in the quantityMultiple attribute) of the Catalog entry is assumed to be the requested quantity. See the CATENTSHIP table for more information. This behavior can be implemented by calling RetrievePricesCmd.
    This input value is optional. The default value is the nominal quantity for the catalog entry. This quantity will only be used in conjunction with setCatEntryId(Long).
    
    Parameters:
    
    aQuantityAmount - The quantity amount of the catalog entry. If null, the nominal quantity will be used as described above.
  - setStoreId
```
void setStoreId(java.lang.Integer aStoreId)
```
    Sets the identifier of the store to be used for calculating the price.
    This input value is optional. The default value is CommandContext#getStoreId().
    
    Parameters:
    
    aStoreId - The reference number of a store to be used for calculating the price. If null, the command context will be used to determine the store.
  - setTradingIds
```
void setTradingIds(java.lang.Long[] aTradingIds)
```
    Sets the identifiers of the input trading agreements.
    Each member is entitled to a number of trading agreements (possibly zero), depending on the member and store. The trading agreements for each catalog entry are provided in one of three ways (from highest to lowest precedence):
    1. setCatEntryPrices(CatEntryPrices[]) (each catalog entry can have different trading agreements defined or none);
    2. This method;
    3. ContractCmdUtil#getCurrentTradingAgreements(CommandContext).
    The specified trading agreements will be checked against the entitled agreements for the specified member. Only the valid trading agreements will be used. If no trading agreements are specified, all entitled trading agreements will be used.
    This input value is optional. The default value is null.
    Parameters:
    
    aTradingIds - The identifiers of the trading agreements to be used to determine the prices. If null or empty, the current or entitled trading agreements will be used as described above.

Quantity range	Price per unit
1-5	10 USD
6-10	9 USD

COPYRIGHT

NAME

getApplicableTradingIds

getApplicableTradingUnitPrices

getBasePrice

getCatEntryPrices

getOffer

getOfferId

getPrice

getTcId

getTradingId

reset

setCatEntryId

setCatEntryPrices

setCurrency

setErrorMode

setMemberId

setOfferIds

setOrganizationId

setQuantity

setStoreId

setTradingIds