Custom promotion implementations

The promotion introduced in promotion anatomy was a pattern based promotion. If you decide to create a custom implementation that differs significantly from the current model, you must provide an implementation for the com.ibm.commerce.marketing.promotion.Promotion interface, which is a subclass of XMLizable. The interface definition dictates that your new implementation must provide the same set of basic attributes as our default implementation. However, you have free rein when it comes to how you define your purchase conditions. The default implementation provides a "purchase pattern" based implementation; yours can follow any design as long as the following is observed:

  1. The purchase condition implements the com.ibm.commerce.marketing.promotion.condition.Condition interface.
  2. It returns true if the promotion is applicable, false otherwise. When true is returned, the promotion should append one or more PromotionExecutionRecord (depending on how many times this promotion can be applied to the current order) to the PromotionContext using addPromotionExecutionRecord method.

This event has a low frequency, and the customization is similar to the Filter and Adjustment approach, so no more details will be discussed here. A sample is as follows:


package com.ibm.commerce.marketing.promotion;
/**
 * Contains the IBM Copyright information for HCL Commerce.
 */

import java.math.BigDecimal;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.Iterator;
import java.util.Locale;
import java.util.Vector;

import com.ibm.commerce.marketing.promotion.xml.XMLizable;
import com.ibm.commerce.copyright.IBMCopyright;
import com.ibm.commerce.marketing.promotion.group.PromotionGroupKey;
import com.ibm.commerce.marketing.promotion.condition.Condition;
import com.ibm.commerce.marketing.promotion.dependency.CampaignKey;
import com.ibm.commerce.marketing.promotion.dependency.CustomerKey;
import com.ibm.commerce.marketing.promotion.policy.PromotionPolicyKey;
import com.ibm.commerce.marketing.promotion.runtime.PromotionContext;
import com.ibm.commerce.marketing.promotion.runtime.PromotionRuntimeException;
import com.ibm.commerce.marketing.promotion.schedule.Schedule;

public interface Promotion extends XMLizable {

   /**
    * Formatter for all time related objects
    */
   public static final SimpleDateFormat DATEFORMAT =
     new SimpleDateFormat("dd-MM-yyyy HH:mm:ss");
   /**
    * IBM Copyright
    */
   public static final String COPYRIGHT = IBMCopyright.SHORT_COPYRIGHT;
   /**
    * Promotion states
    */
   public static final int PROMOTION_STATE_INACTIVE = 0;
   /**
    * Promotion States
    */
   public static final int PROMOTION_STATE_ACTIVE = 1;
   /**
    * Promotion states
    */
   public static final int PROMOTION_STATE_DELETED = 2;
   /**
    * Promotion states
    */
   public static final int PROMOTION_STATE_SUSPENDED = 3;
   /**
    * Promotion states
    */
   public static final int PROMOTION_STATE_OBSOLETE = 4;

   /**
    * Promotion exclusiveness settings
    */
   public static final int PROMOTION_EXCLUSIVE_NONE = 0;
   /**
    * Promotion exclusiveness settings
    */
   public static final int PROMOTION_EXCLUSIVE_AT_GROUP_LEVEL = 1;
   /**
    * Promotion exclusiveness settings
    */
   public static final int PROMOTION_EXCLUSIVE_AT_GLOBAL_LEVEL = 2;
   /**
    * Promotion exclusiveness settings, this is created to support backward
    * compatibility.
    * Any promotions created with this setting cannot be combined with promotions
    * in the "Product Level Promotion" group.
    */
   public static final int PROMOTION_EXCLUSIVE_RBD_ORDERDISCOUNT_COMPATIBLE = 3;
   /**
    * Promotion type settings
    */
   public static final int PROMOTION_TYPE_TARGETED = 0;
   /**
    * Promotion type settings
    */
   public static final int PROMOTION_TYPE_PRIVATE = 1;

   /**
    * Returns the currency in which all monetary values in this promotion are
    * defined. Returns the currency in String format like "CAD", "USD", or "CNY".
    * @return String currency in string format
    */
   public String getCurrency();

   /**
    * Sets the currency in which all monetary values in this promotion will be
    * defined. Currency should be in the String format like "CAD", "USD", or "CNY".
    * @param String currency the currency in String format
    */
   public void setCurrency(String currency);

   /**
    * Returns the key of this promotion.
    * @return The promotion key
    */
   public PromotionKey getKey();

   /**
    * Returns the description of this promotion in the locale of the type.
    * @param locale locale of the description to be returned
    * @param type type of the description to be returned
    * @return String
    */
   public String getDescription(Locale locale, int type);

   /**
    * Returns the exclusive level of a promotion.
    * @return int exclusiveness level also see the promotion 
    * exclusiveness settings for possible values
    */
   public int getExclusiveLevel();

   /**
    * Returns the lastUpdate time of the promotion.
    * @return Date when this promotion was last updated
    */
   public Date getLastUpdate();

   /**
    * Returns the lastUpdateBy. The person who last updated this promotion
    * @return CustomerKey key of person who last updated the promotion
    */
   public CustomerKey getLastUpdateBy();

   /**
    * Returns the name of the promotion.
    * @return String name of the promotion
    */
   public String getName();
   /**
    * Returns the priority of the promotion.
    * @return Integer
    */
   public Integer getPriority();

   /**
    * Returns the schedule associated with this promotion.
    * @return Schedule schedule associated with this promotion
    */
   public Schedule getSchedule();

   /**
    * Returns the status of this promotion.
    * @return int see also the different status settings for a promotion
    */
   public int getStatus();

   /**
    * Sets the description for this promotion.
    * @param description The description to set
    * @param locale the locale of the description
    * @param type the type of the promotion
    */
   public void setDescription(Locale locale, int type, String description);
   /**
    * Sets the exclusive.
    * @param exclusive The exclusive to set
    */
   public void setExclusiveLevel(int exclusive);

   /**
    * Sets the key of the promotion.
    * @param key The key to set
    */
   public void setKey(PromotionKey key);

   /**
    * Sets the lastUpdate.
    * @param lastUpdate The lastUpdate to set
    */
   public void setLastUpdate(Date lastUpdate);

   /**
    * Sets the lastUpdateBy.
    * @param lastUpdateBy The lastUpdateBy to set
    */
   public void setLastUpdateBy(CustomerKey lastUpdateBy);

   /**
    * Sets the priority.
    * @param priority The priority to set
    */
   public void setPriority(Integer priority);

   /**
    * Sets the schedule.
    * @param schedule The schedule to set
    */
   public void setSchedule(Schedule schedule);

   /**
    * Sets the status.
    * @param status The status to set
    */
   public void setStatus(int status);

   /**
    * Return whether promotion code is required for this promotion or not
    * @return boolean
    */
   public boolean isPromotionCodeRequired();

   /**
    * Returns the promotionCodeCondition.
    * @return PromotionCodeRequiredCondition
    */
   public Condition getPromotionCodeCondition();

   /**
    * Returns the targetingCondition.
    * @return TargetingCondition
    */
   public Condition getTargetingCondition();

   /**
    * Sets the promotionCodeCondition.
    * @param promotionCodeCondition The promotionCodeCondition to set
    */
   public void setPromotionCodeCondition(Condition promotionCodeCondition);

   /**
    * Sets the targetingCondition.
    * @param targetingCondition The targetingCondition to set
    */
   public void setTargetingCondition(Condition targetingCondition);
   /**
    * Returns the targetingConditionCheckedAtRuntime.
    * @return boolean
    */
   public boolean ignoreTargettingConditionUponProperPromotionCodeEntry();

   /**
    * Returns the flag value which controls if targeting conditions should 
    * be checked at runtime or not.
    * @return true if targeting condition needs to be checked at runtime,
    * false otherwise.
    */
   public boolean checkTargetingConditionAtRuntime();
   /**
    * Sets the checkTargetingConditionAtRuntime flag
    * @param value true if you want targeting condition of this promotion to 
    * be checked at runtime, false otherwise.
    */
   public void setCheckTargetingConditionAtRuntime(boolean value);
   /**
    * Sets the targetingConditionCheckedAtRuntime.
    * @param targetingConditionCheckedAtRuntime The 
    * targetingConditionCheckedAtRuntime to set
    */
   public void setIgnoreTargetingConditionUponProperPromotionCodeEntry (boolean ignore);

   /**
    * Appends a custom condition to the list of custom conditions
    * @param Condition restriction a custom condition
    */
   public void addCustomCondition(Condition restriction);

   /**
    * Returns all custom conditions in an iterator
    * @return Iterator a list of custom conditions associated with this 
    * promotion
    */
   public Iterator getCustomConditions();

   /**
    * Returns the group.
    * @return PromotionGroup
    */
   public PromotionGroupKey getGroupKey();

   /**
    * Sets the group.
    * @param group The group to set
    */
   public void setGroupKey(PromotionGroupKey key);

   /**
    * Returns the perOrderLimit.
    * @return int
    */
   public int getPerOrderLimit();
   /**
    * Returns the perShopperLimit.
    * @return int
    */
   public int getPerShopperLimit();
   /**
    * Returns the totalApplicationCountLimit.
    * @return int
    */
   public int getTotalApplicationCountLimit();

   /**
    * Sets the otherRestrictions.
    * @param otherRestrictions The otherRestrictions to set
    */
   public void setCustomConditions(Vector otherRestrictions);

   /**
    * Sets the perOrderLimit.
    * @param perOrderLimit The perOrderLimit to set
    */
   public void setPerOrderLimit(int perOrderLimit);

   /**
    * Sets the perShopperLimit.
    * @param perShopperLimit The perShopperLimit to set
    */
   public void setPerShopperLimit(int perShopperLimit);

   /**
    * Sets the totalApplicationCountLimit.
    * @param totalApplicationCountLimit The totalApplicationCountLimit 
    * to set
    */
   public void setTotalApplicationCountLimit(int totalApplicationCountLimit);

   /**
    * Returns the campaignKey.
    * @return CampaignKey
    */
   public CampaignKey getCampaignKey();

   /**
    * Sets the campaignID.
    * @param campaignID The campaignID to set
    */
   public void setCampaignKey(CampaignKey campaignkey);
   /**
    * Returns the revision.
    * @return int
    */
   public int getRevision();

   /**
    * Returns the type.
    * @return Integer
    */
   public int getType();

   /**
    * Returns the version.
    * @return int
    */
   public int getVersion();

   /**
    * Sets the type.
    * @param type The type to set
    */
   public void setType(int type);

   /**
    * Returns the visualCue.
    * @return String
    */
   public String getCode();

   /**
    * Sets the visualCue.
    * @param visualCue The visualCue to set
    */
   public void setCode(String code);

   /**
    * Returns the purchase condition in this promtion
    * @return purchase condition
    */
   public Condition getPurchaseCondition();

   /**
    * Sets purchase condition
    * @param condition Condition the purchase condition to be set.
    */
   public void setPurchaseCondition(Condition condition);

   /**
    * Adds a policy to the list of explicitly exempted promotion policies
    *  for this promotion
    * @param key of the promotion policy to be added
    */
   public void addExemptedPolicy(PromotionPolicyKey key);

   /**
    * Removes a promotion policy from the list of explicitly exempted list
    * of policies
    * @param key the key of the policy to be removed.
    */
   public void removeExemptedPolicy(PromotionPolicyKey key);

   /**
    * Returns an iterator of all the explicitly exempted policies.
    * @return iterator of explicitly exempted policies.
    */
   public Iterator getExemptedPolicies();

   /**
    * Adds a promotion policy to the list of policies which are marked 
    * explicitly as applicable to this promotion
    * @param key of the policy to be added
    */
   public void addExplicitlyAppliedPolicy(PromotionPolicyKey key);

   /**
    * Removes a policy from the list of policies which are marked explicitly
    * as applicable to this promotion
    * @param key of the policy to be removed.
    */
   public void removeExplicitlyAppliedPolicy(PromotionPolicyKey key);

   /**
    * Returns an iterator of all the policies which are marked explicitly as
    * applicable to this promotion.
    * @return an iterator of all explicitly applicable policies.
    */
   public Iterator getExplicitlyAppliedPolicies();

   /**
    * Returns the coupon related attributes if this promotion is a private
    * promotion.
    * @return coupon related attributes if this promotion is a private 
    * promotion, null otherwise.
    */
   public CouponAttribute getCouponAttribute();

   /**
    * Sets the coupon related attributes for promotions that are private
    * @param attrs coupon related attributes
    */
   public void setCouponAttribute(CouponAttribute attrs);

   /**
    * Returns the target sales figure
    * @return target sales figure, null if no value is specified
    */
   public BigDecimal getTargetSales();

   /**
    * Sets the target sales figure, null is allowed
    * @param sales taget sales figure
    */
   public void setTargetSales(BigDecimal sales);

   /**
    * Returns the corresponding rule-based promotion type name, if one is 
    * available.
    * @return rule-based promotion type name, null if one is not set.
    * @deprecated Introduced for backward compatibility reasons. This method
    * will be removed in the next release
    */
   public String getCorrespondingRBDTypeName();

   /**
    * Sets the corresponding rule-based promotion type name
    * @param newName discount type name in rule-based promotion
    * @deprecated Introduced for backward compatibility reasons. This
    * method will be removed in the next release
    */
   public void setCorrespondingRBDTypeName(String newName);
   
   /**
    * Evaluates if this promotion is applicable to the current order which 
    * is part of the context object being passed to this method.
    * @param context PromotionContext, note that this parameter is both in
    * and out parameter.
    * @return 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.
    */
   public boolean evaluate(PromotionContext context)
          throws PromotionRuntimeException;

   /**
    * Sets the promotion code required flag.
    * @param aPromotionCodeRequired true if a correct promotion code is
    * required to redeem this promotion, false
    * otherwise.
    */
   public void setPromotionCodeRequired(boolean aPromotionCodeRequired);
}