com.ibm.commerce.marketing.promotion

Interface Promotion

  • All Superinterfaces:
    java.io.Serializable, XMLizable
    All Known Implementing Classes:
    DefaultPromotion


    public interface Promotion
    extends XMLizable
    In general, the promotion is a unit of defined business logic that offers customers incentives when certain conditions have been satisfied. It is defined as an interface in the PromotionEngine, which means different implementations of a Promotion can be supplied by the implementer who customizes the promotion engine. In WebSphere Commerce, each individual promotion can be serialized as an XML document with components following a “pattern based” model. Promotion has its state and lifecycle. In this class, it provides the APIs for the promotion.
    • Field Detail

      • DATEFORMAT

        static final java.text.SimpleDateFormat DATEFORMAT
        Formatter for all time related objects
      • PROMOTION_STATE_INACTIVE

        static final int PROMOTION_STATE_INACTIVE
        Value of the state of a promotion used to indicate that it is inactive.
        See Also:
        Constant Field Values
      • PROMOTION_STATE_ACTIVE

        static final int PROMOTION_STATE_ACTIVE
        Value of the state of a promotion used to indicate that it is active.
        See Also:
        Constant Field Values
      • PROMOTION_STATE_DELETED

        static final int PROMOTION_STATE_DELETED
        Value of the state of a promotion used to indicate that it has been marked for deletion.
        See Also:
        Constant Field Values
      • PROMOTION_STATE_SUSPENDED

        static final int PROMOTION_STATE_SUSPENDED
        Value of the state of a promotion used to indicate that it has been suspended.
        See Also:
        Constant Field Values
      • PROMOTION_STATE_OBSOLETE

        static final int PROMOTION_STATE_OBSOLETE
        Value of the state of a promotion used to indicate that it is obsolete.
        See Also:
        Constant Field Values
      • PROMOTION_STATE_ACTIVATING

        static final int PROMOTION_STATE_ACTIVATING
        Value of the state of a promotion used to indicate that it is activating.
        See Also:
        Constant Field Values
      • PROMOTION_STATE_ARCHIVED

        static final int PROMOTION_STATE_ARCHIVED
        Value of the state of a promotion used to indicate that it is archived.
        See Also:
        Constant Field Values
      • PROMOTION_EXCLUSIVE_NONE

        static final int PROMOTION_EXCLUSIVE_NONE
        Value of the exclusiveness setting of a promotion to indicate that it may be combined with any other promotions.
        See Also:
        Constant Field Values
      • PROMOTION_EXCLUSIVE_AT_GROUP_LEVEL

        static final int PROMOTION_EXCLUSIVE_AT_GROUP_LEVEL
        Value of the exclusiveness setting of a promotion to indicate that it can not be combined with any other promotions in the same promotion group.
        See Also:
        Constant Field Values
      • PROMOTION_EXCLUSIVE_AT_GLOBAL_LEVEL

        static final int PROMOTION_EXCLUSIVE_AT_GLOBAL_LEVEL
        Value of the exclusiveness setting of a promotion to indicate that it can not be combined with any other promotions.
        See Also:
        Constant Field Values
      • PROMOTION_EXCLUSIVE_STACKABLE_AT_GROUP_LEVEL

        static final int PROMOTION_EXCLUSIVE_STACKABLE_AT_GROUP_LEVEL
        Value of the exclusiveness setting of a promotion to indicate that it may be combined with any other promotions and it can also apply on items that have already been targeted by other promotions of the same promotion group.
        See Also:
        Constant Field Values
      • PROMOTION_EXCLUSIVE_RBD_ORDERDISCOUNT_COMPATIBLE

        static final int PROMOTION_EXCLUSIVE_RBD_ORDERDISCOUNT_COMPATIBLE
        Promotion exclusiveness settings, this is created for backward compatibility reason. Any promotions created with this setting can not be combined with promotions in the "Product Level Promotion" group.
        See Also:
        Constant Field Values
      • PROMOTION_TYPE_TARGETED

        static final int PROMOTION_TYPE_TARGETED
        Value of the promotion type setting of a promotion to indicate that it is applicable to customers who belong to one or more of the targeted customer profiles. When the targeted profile list is empty, it applies to everyone.
        See Also:
        Constant Field Values
      • PROMOTION_TYPE_PRIVATE

        static final int PROMOTION_TYPE_PRIVATE
        Value of the promotion type setting of a promotion to indicate that it is applicable only to those to whom it has been explicitly granted, that is, this promotion is a coupon promotion.
        See Also:
        Constant Field Values
    • Method Detail

      • getCurrency

        java.lang.String getCurrency()
        Returns the currency in which all monetary values in this promotion are defined. Returns it as a string format like "CAD".
        Returns:
        The currency in string format.
      • setCurrency

        void setCurrency(java.lang.String currency)
        Sets the currency in which all monetary values in this promotion will be defined. Currency should be in the string format like "CAD".
        Parameters:
        currency - The currency in string format.
      • getKey

        PromotionKey getKey()
        Returns the key of this promotion.
        Returns:
        The promotion key.
      • getDescription

        java.lang.String getDescription(java.util.Locale locale,
                                        int type)
        Returns the specified type of the description of the promotion in a particular locale. The types of the description include the following:
        0: Administrative description
        1: Customer facing long description
        2: Customer facing short description
        Parameters:
        locale - The Locale of the description to be returned.
        type - The type of the description to be returned.
        Returns:
        String The specified type of the description of the promotion in a locale.
      • getExclusiveLevel

        int getExclusiveLevel()
        Returns the exclusive level of a promotion. Please check the exclusiveness settings for possible values.
        Returns:
        int of the exclusiveness level.
      • getLastUpdate

        java.util.Date getLastUpdate()
        Returns the last updated time of the promotion.
        Returns:
        Date when this promotion was last updated.
      • getLastUpdateBy

        CustomerKey getLastUpdateBy()
        Returns the person who is the last one updates this promotion.
        Returns:
        The customer key of a person who is the last one updates this promotion.
      • getName

        java.lang.String getName()
        Returns the name of the promotion.
        Returns:
        String name of the promotion.
      • getPriority

        java.lang.Integer getPriority()
        Returns the priority of the promotion.
        Returns:
        Integer representing the priority of the promotion.
      • getSchedule

        Schedule getSchedule()
        Returns the schedule associated with this promotion.
        Returns:
        The schedule associated with this promotion
      • getStatus

        int getStatus()
        Returns the status of this promotion.
        Returns:
        The status of this promotion.
      • setDescription

        void setDescription(java.util.Locale locale,
                            int type,
                            java.lang.String description)
        Sets the specified type of the description of the promotion in a particular locale. The types of the description include the following:
        0: Administrative description
        1: Customer facing long description
        2: Customer facing short description
        Parameters:
        locale - The Locale of the description to be set.
        type - The type of the description to be set.
        description - The description to set.
      • setExclusiveLevel

        void setExclusiveLevel(int exclusive)
        Sets the exclusive level of the promotion.
        Parameters:
        exclusive - The exclusive level to set for the promotion.
      • setKey

        void setKey(PromotionKey key)
        Sets the key of the promotion.
        Parameters:
        key - The key to set for the promotion.
      • setLastUpdate

        void setLastUpdate(java.util.Date lastUpdate)
        Sets the last update date for the promotion.
        Parameters:
        lastUpdate - The lastUpdate date for the promotion to set.
      • setLastUpdateBy

        void setLastUpdateBy(CustomerKey lastUpdateBy)
        Sets the customer key for the promotion that is last updated.
        Parameters:
        lastUpdateBy - the customer key to set for the promotion that is last updated.
      • setPriority

        void setPriority(java.lang.Integer priority)
        Sets the priority of the promotion.
        Parameters:
        priority - The priority of the promotion to set.
      • setSchedule

        void setSchedule(Schedule schedule)
        Sets the schedule of the promotion.
        Parameters:
        schedule - The schedule of the promotion to set.
      • setStatus

        void setStatus(int status)
        Sets the status of the promotion.
        Parameters:
        status - The status of the promotion to set.
      • isPromotionCodeRequired

        boolean isPromotionCodeRequired()
        Return whether promotion code is required for this promotion or not.
        Returns:
        boolean representing whether promotion code is required for this promotion or not.
      • getPromotionCodeCondition

        Condition getPromotionCodeCondition()
        Returns the promotion code condition associated with the promotion.
        Returns:
        Condition promotion code condition associated with the promotion.
      • getTargetingCondition

        Condition getTargetingCondition()
        Returns the targeting condition associated with the promotion.
        Returns:
        TargetingCondition the targeting condition associated with the promotion.
      • setPromotionCodeCondition

        void setPromotionCodeCondition(Condition promotionCodeCondition)
        Sets the promotion code condition of the promotion.
        Parameters:
        promotionCodeCondition - The promotion code condition of the promotion to set.
      • setTargetingCondition

        void setTargetingCondition(Condition targetingCondition)
        Sets the targeting condition of the promotion.
        Parameters:
        targetingCondition - the targeting condition of the promotion to set.
      • ignoreTargettingConditionUponProperPromotionCodeEntry

        boolean ignoreTargettingConditionUponProperPromotionCodeEntry()
        Returns whether the targeting condition should be checked at proper promotion code entry.
        Returns:
        boolean true if targeting condition should be skipped on proper promotion code entry.
      • checkTargetingConditionAtRuntime

        boolean checkTargetingConditionAtRuntime()
        Returns the flag value which controls if targeting conditions should be checked at runtime or not
        Returns:
        true if targeting condition needs to be checked at runtime, false otherwise.
      • setCheckTargetingConditionAtRuntime

        void setCheckTargetingConditionAtRuntime(boolean value)
        Sets the flag if targeting condition will be checked at runtime.
        Parameters:
        value - true if you want targeting condition of this promotion to be checked at runtime, false otherwise.
      • setIgnoreTargetingConditionUponProperPromotionCodeEntry

        void setIgnoreTargetingConditionUponProperPromotionCodeEntry(boolean ignore)
        Sets if the targeting condition to be checked at runtime based on promotion code entry.
        Parameters:
        ignore - set to true if the targeting condition should be skipped on proper promotion code entry.
      • addCustomCondition

        void addCustomCondition(Condition restriction)
        Appends a custom condition to the list of custom conditions.
        Parameters:
        restriction - a custom condition to add.
      • getCustomConditions

        java.util.Iterator getCustomConditions()
        Returns all custom conditions in an iterator.
        Returns:
        A list of custom conditions associated with this promotion.
      • getGroupKey

        com.ibm.commerce.marketing.promotion.group.PromotionGroupKey getGroupKey()
        Returns the promotion group key of the promotion.
        Returns:
        PromotionGroup the promotion group key of the promotion.
      • setGroupKey

        void setGroupKey(com.ibm.commerce.marketing.promotion.group.PromotionGroupKey key)
        Sets the promotion group key of the promotion.
        Parameters:
        key - The promotion group key of the promotion to set.
      • getPerOrderLimit

        int getPerOrderLimit()
        Returns the perOrderLimit. This is the maximum number of times a promotion can be applied to an order. When this promotion is a private promotion, this governs the maximum number of coupons for this promotion that can be used together for any order. Returns a value of -1 to indicate that the per order limit is infinite, that is, the number of redemptions are unlimited.
        Returns:
        int the per order redemption limit that represents the maximum number of times a promotion can be applied to an order.
      • getPerShopperLimit

        int getPerShopperLimit()
        Returns the perShopperLimit. This is the maximum number of times a promotion can be applied to any shopper. System keeps the statistics in order to count the number of times a shopper has redeemed a promotion. The total count is not allowed to exceed this limit. Returns a value of -1 to indicate that the per shopper limit is infinite, that is, the number of redemptions are unlimited.
        Returns:
        int the maximum number of times a shopper is entitled to a promotion.
      • getTotalApplicationCountLimit

        int getTotalApplicationCountLimit()
        Returns the totalApplicationCountLimit. This controls how many times overall a promotion can be redeemed. For private promotions, this controls how many coupons will be issued. Returns a value of -1 to indicate that the total limit is infinite, that is, the number of redemptions are unlimited.
        Returns:
        int the limit of how many times a promotion can be redeemed overall.
      • setCustomConditions

        void setCustomConditions(java.util.Vector otherRestrictions)
        Sets the other restrictions that may be added.
        Parameters:
        otherRestrictions - The other restrictions that may be added.
      • setPerOrderLimit

        void setPerOrderLimit(int perOrderLimit)
        Sets the per order redemption limit.
        Parameters:
        perOrderLimit - The per order redemption limit to set.
      • setPerShopperLimit

        void setPerShopperLimit(int perShopperLimit)
        Sets the the maximum number of times a promotion can be applied to any shopper.
        Parameters:
        perShopperLimit - The maximum number of times a promotion can be applied to any shopper to set.
      • setTotalApplicationCountLimit

        void setTotalApplicationCountLimit(int totalApplicationCountLimit)
        Sets the limit of how many times a promotion can be redeemed overall.
        Parameters:
        totalApplicationCountLimit - to set the limit of how many times a promotion can be redeemed overall.
      • getCampaignKey

        CampaignKey getCampaignKey()
        Returns the campaign key associated with the promotion.
        Returns:
        CampaignKey the campaign key associated with the promotion.
      • setCampaignKey

        void setCampaignKey(CampaignKey campaignkey)
        Sets the campaign key associated with the promotion.
        Parameters:
        campaignkey - to set campaign key associated with the promotion.
      • getRevision

        int getRevision()
        Returns the revision. Revision number of this promotion. Promotions belong to the same store with the same version number but different revision number are consider different levels of the same promotion.
        Returns:
        the revision number of the promotion.
      • getType

        int getType()
        Returns the type of the promotion. Types can be either targeted(0) or private(1).
        Returns:
        int representing a type of the promotion.
      • getVersion

        int getVersion()
        Returns the version of this promotion. Promotions with different version numbers are considered different promotions. Among all the promotions with same name in the same store, only one is active at any given time. This one is identified by promotion name, version or revision numbers, and store ID. The rest of them will be marked as obsolete.
        Returns:
        int version number of the promotion.
      • setType

        void setType(int type)
        Sets the type of promotion. 0: targeted 1: private (that is, a coupon is required to redeem this promotion).
        Parameters:
        type - The type of promotion to set, either targeted or private.
      • getCode

        java.lang.String getCode()
        Returns the visualCue. visualCue is the text entered either to be used as promotion code or to assist the generation of the promotion code.
        Returns:
        String of the visualCue. VisualCue is the text entered either to be used as promotion code or to assist the generation of the promotion code.
      • setCode

        void setCode(java.lang.String code)
        Sets the visualCue. visualCue is the text entered either to be used as promotion code or to assist the generation of the promotion code.
        Parameters:
        code - The visualCue to set. VisualCue is the text entered either to be used as promotion code or to assist the generation of the promotion code.
      • getPurchaseCondition

        Condition getPurchaseCondition()
        Returns the purchaseCondition. Purchase condition is the condition that governs certain purchases the customer has to make in order to qualify for a promotion.
        Returns:
        Condition. Purchase condition is the condition that governs certain purchases the customer has to make in order to qualify for a promotion.
      • setPurchaseCondition

        void setPurchaseCondition(Condition condition)
        Sets the purchaseCondition. Purchase condition is the condition that governs certain purchases the customer has to make in order to qualify for a promotion.
        Parameters:
        condition - The condition to set. Purchase condition is the condition that governs certain purchases the customer has to make in order to qualify for a promotion.
      • addExemptedPolicy

        void addExemptedPolicy(PromotionPolicyKey key)
        Appends a policy to the list of policies from which this promotion is explicitly exempted.
        Parameters:
        key - the key of the exempted policy to be added.
      • removeExemptedPolicy

        void removeExemptedPolicy(PromotionPolicyKey key)
        Removes a promotion policy from the exempted list.
        Parameters:
        key - the key of the promotion policy to be removed.
      • getExemptedPolicies

        java.util.Iterator getExemptedPolicies()
        Returns a list of explicitly exempted promotion policies.
        Returns:
        an iterator of explicitly exempted promotion policies.
      • addExplicitlyAppliedPolicy

        void addExplicitlyAppliedPolicy(PromotionPolicyKey key)
        Adds a promotion policy to the list of policies that are explicitly marked as applicable to a promotion.
        Parameters:
        key - the key of the applicable policy that to be added.
      • removeExplicitlyAppliedPolicy

        void removeExplicitlyAppliedPolicy(PromotionPolicyKey key)
        Removes a promotion policy from the list of policies explicitly marked as applicable to this promotion.
        Parameters:
        key - the key of the promotion policy to be removed from the list.
      • getExplicitlyAppliedPolicies

        java.util.Iterator getExplicitlyAppliedPolicies()
        Returns an iterator of all the promotion policies that are explicitly marked as applicable to this promotion.
        Returns:
        an iterator of the applicable policies that are explicitly marked as applicable to this promotion.
      • getCouponAttribute

        com.ibm.commerce.marketing.promotion.CouponAttribute getCouponAttribute()
        Returns the coupon attributes associated with the promotion.
        Returns:
        CouponAttributes the coupon attributes associated with the promotion.
      • setCouponAttribute

        void setCouponAttribute(com.ibm.commerce.marketing.promotion.CouponAttribute attrs)
        Sets the coupon attributes associated with the promotion.
        Parameters:
        attrs - The coupon attributes associated with the promotion.
      • getTargetSales

        java.math.BigDecimal getTargetSales()
        Returns the target sales figure
        Returns:
        target sales figure, null if no value is specified
      • setTargetSales

        void setTargetSales(java.math.BigDecimal sales)
        Sets the target sales figure, null is allowed
        Parameters:
        sales - the target sales figure
      • getCorrespondingRBDTypeName

        java.lang.String getCorrespondingRBDTypeName()
        Deprecated. Introduced for backward compatibility reasons. This method will be removed in the next release
        Returns the corresponding Rules-Based Discount type, if one is available.
        Returns:
        The discount type, null if one is not set.
      • setCorrespondingRBDTypeName

        void setCorrespondingRBDTypeName(java.lang.String newName)
        Deprecated. Introduced for backward compatibility reasons. this method will be removed in the next release
        Sets the corresponding Rules-Based Discount type.
        Parameters:
        newName - The Rules-Based Discount type.
      • evaluate

        boolean evaluate(PromotionContext context)
                  throws PromotionRuntimeException
        Evaluates if this promotion is applicable to the current order which is part of the context object being passed to this method.
        Parameters:
        context - PromotionContext, note that this parameter is both in and out parameter.If the current promotion is applicable, this method will further modify the PromotionContext parameter as an output.
        Returns:
        true if this promotion is applicable to the order in the context object, false otherwise.
        Throws:
        PromotionRuntimeException - if any exception is thrown in the process of evaluating this promotion it will be wrapped in a PromotionRuntimeException and thrown to the caller.
      • setPromotionCodeRequired

        void setPromotionCodeRequired(boolean aPromotionCodeRequired)
        Sets the promotion code required flag.
        Parameters:
        aPromotionCodeRequired - true if a correct promotion code is required to redeem this promotion, false otherwise.