Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

1 - Extending the Elastic Path Core

1 - Extending the Elastic Path Core

The Commerce Engine core library contains the classes and interfaces that are shared across all Elastic Path web applications. Core is organized into three layers: the domain layer, which model ecommerce entities such as products and customers; the service layer, which contains services consumed by the Elastic Path web applications; and the data access layer, which manages the database and retrieves data from XML and property files.

This tutorial begins by showing you how to extend the domain layer's Order and Shopping Cart entities to support an automatic renewal option.

Extending Shopping Cart

The ShoppingCart domain object represents a customer's shopping cart. The ShoppingCart manages the items a customer wants to buy and the customer's billing information, so the ShoppingCart needs to know when a customer opts into the automatic renewal.

To implement the automatic renewal, extend the ShoppingCart domain object to hold an autoBill property. This property denotes whether or not a customer has selected the automatic renewal feature.

  1. Navigate to the ext-core project in extensions/core directory.
  2. In the the ext-core project's com.extensions.domain package, found under the src/main/java directory, create a new package named shoppingcart.
  3. In com.extensions.domain.shoppingcart, create a new interface named ExtShoppingCart and add the following code:
                      package com.extensions.domain.shoppingcart;
    
    import com.elasticpath.domain.shoppingcart.ShoppingCart;
    
    /**
     * Extends ShoppingCart interface by adding 'AutoBill' methods.
     */
    public interface ExtShoppingCart extends ShoppingCart {
    	/**
    	 * Checks whether this order has been set as an auto bill order.
    	 *
    	 * @return true in case the order is of type auto bill
    	 */
    	boolean isAutoBill();
    
    	/**
    	 * Sets auto bill flag on this order.
    	 *
    	 * @param autoBill the auto bill flag
    	 */
    	void setAutoBill(boolean autoBill);
    }
                   
  4. In com.extensions.domain.shoppingcart, create a new package named impl
  5. In com.extensions.domain.shoppingcart.impl, create a new class named ExtShoppingCartImpl and add the following code:
                      package com.extensions.domain.shoppingcart.impl;
    
    import com.extensions.domain.shoppingcart.ExtShoppingCart;
    
    import com.elasticpath.domain.shoppingcart.impl.ShoppingCartImpl;
    
    /**
     * Extends 'ShoppingCartImpl' to enable shopping cart to save 'autoBill' value.
     */
    public class ExtShoppingCartImpl extends ShoppingCartImpl implements ExtShoppingCart {
    
    	/**
    	 * Serial version id.
    	 */
    	public static final long serialVersionUID = 5000000001L;
    
    	private boolean autoBill;
    
    	/**
    	 * Returns whether automatic renewal and billing is enabled for this order.
    	 *
    	 * @return true if automatic renewal and billing is enabled.
    	 */
    	public boolean isAutoBill() {
    		return this.autoBill;
    	}
    
    	/**
    	 * Sets whether automatic renewal and billing is enabled for this order.
    	 *
    	 * @param autoBill true to enable automatic renewal and billing
    	 */
    	public void setAutoBill(final boolean autoBill) {
    		this.autoBill = autoBill;
    	}
    }
                   

Extending Orders

The Order domain object represents a customer's order. Elastic Path creates the Order object as the customer completes checkout and saves the Order in the database as a record of the customer's purchase.

To save the autoBill property in the database, you need to extend the Order domain object to have an autoBill property:

  1. In the ext-core project's com.extensions.domain package, create a new package named order.
  2. In com.extensions.domain.order, create an interface named ExtOrder and add the following code:
                      package com.extensions.domain.order;
    
    import com.elasticpath.domain.order.Order;
    
    /**
     * Extends Order interface by adding 'AutoBill' methods.
     */
    public interface ExtOrder extends Order {
    
    	/**
    	 * Returns whether automatic renewal and billing is enabled for this order.
    	 *
    	 * @return true if automatic renewal and billing is enabled.
    	 */
    	boolean isAutoBill();
    
    	/**
    	 * Sets whether automatic renewal and billing is enabled for this order.
    	 *
    	 * @param autoBill true to enable automatic renewal and billing
    	 */
    	void setAutoBill(boolean autoBill);
    }
                   
  3. In com.extensions.domain.order, create a new package named impl
  4. In com.extensions.domain.order.impl, create a new class named ExtOrderImpl and add the following code:
                      package com.extensions.domain.order.impl;
    
    import javax.persistence.Basic;
    import javax.persistence.Column;
    import javax.persistence.DiscriminatorValue;
    import javax.persistence.Entity;
    import javax.persistence.PrimaryKeyJoinColumn;
    import javax.persistence.Table;
    
    import com.extensions.domain.order.ExtOrder;
    
    import com.elasticpath.domain.order.impl.OrderImpl;
    
    /**
     * Implementation of Order extension interface.
     */
    @Entity
    @Table(name = ExtOrderImpl.TABLE_NAME)
    @DiscriminatorValue("extOrder")
    @PrimaryKeyJoinColumn(name = "UIDPK", referencedColumnName = "UIDPK")
    public class ExtOrderImpl extends OrderImpl implements ExtOrder {
    	/**
    	 * Serial version id.
    	 */
    	public static final long serialVersionUID = 5000000092L;
    
    	/**
    	 * Table to which ExtOrderImpl objects will be persisted.
    	 */
    	public static final String TABLE_NAME = "TORDEREXT";
    
    	private boolean autoBill;
    
    	/**
    	 * Checks whether this order has been set as an auto bill order.
    	 *
    	 * @return true in case the order is of type auto bill
    	 */
    	@Basic
    	@Column(name = "AUTOBILL")
    	public boolean isAutoBill() {
    		return autoBill;
    	}
    
    	/**
    	 * Sets auto bill flag on this order.
    	 *
    	 * @param autoBill the auto bill flag
    	 */
    	public void setAutoBill(final boolean autoBill) {
    		this.autoBill = autoBill;
    	}
    
    	/**
    	 * Returns <code>true</code> if this order is equal to the given object.
    	 *
    	 * @param obj the given object
    	 * @return <code>true</code> if this order is equal to the given object
    	 */
    	@Override
    	public boolean equals(final Object obj) {
    		if (!(obj instanceof ExtOrder)) {
    			return false;
    		}
    
    		// check if unextended objects are equal
    		if (!super.equals(obj)) {
    			return false;
    		}
    
    		// compare object id
    		if (this == obj) {
    			return true;
    		}
    
    		// make sure autobill properties are equal
    		ExtOrder other = (ExtOrder) obj;
    		if (this.isAutoBill() == other.isAutoBill()) {
    			return true;
    		}
    
    		return false;
    	}
    
    	@Override
    	public int hashCode() {
    		int code = super.hashCode();
    		if (isAutoBill()) {
    			return code + 1;
    		}
    		return code;
    	}
    }
                   

Passing the autoBill from ShoppingCart to Order

As mentioned above, the Order object is created at checkout and is saved in the database as a record of the customer's purchase. To save the autoBill value as part of the Order, the Order needs to get the autoBill value from the ShoppingCart.

In core, there is a service layer class for handling additional actions before, during, or after the checkout process is complete. You'll overwrite a method of this service to pass the autoBill value from the ShoppingCart to Order.

  1. In the ext-core project's com.extensions package, create a new package named service.shoppingcart.impl.
  2. In com.extensions.service.shoppingcart.impl, create a new class named ExtCheckoutEventHandlerImpl and add the following code:
                      package com.extensions.service.shoppingcart.impl;
    
    import java.util.Collection;
    
    import com.extensions.domain.order.ExtOrder;
    import com.extensions.domain.shoppingcart.impl.ExtShoppingCartImpl;
    
    import com.elasticpath.domain.order.Order;
    import com.elasticpath.domain.order.OrderPayment;
    import com.elasticpath.domain.shoppingcart.ShoppingCart;
    import com.elasticpath.service.shoppingcart.impl.AbstractCheckoutEventHandlerImpl;
    
    /**
     * Defines a handler to deal with checkout events.
     */
    public class ExtCheckoutEventHandlerImpl extends AbstractCheckoutEventHandlerImpl {
    
    	/**
    	 * This event occurs after a checkout has been processed but before the order has been persisted.
    	 * This event occurs between preCheckout and postCheckout.
    	 *
    	 * @param shoppingCart the shopping cart being checked out
    	 * @param orderPayment information about the method of payment
    	 * @param order the order object resulting from the checkout
    	 */
    	public void preCheckoutOrderPersist(final ShoppingCart shoppingCart,
    			final Collection<OrderPayment> orderPayment, final Order order) {
    		((ExtOrder) order).setAutoBill(((ExtShoppingCartImpl) shoppingCart).isAutoBill());
    	}
    }
                   

Replacing Core Beans

Before the Commerce Engine core will use your extended Order, ShoppingCart and CheckoutEventHandler classes, you need to redefine some Java Bean definitions in your core extension's ep-core-plugin.xml:

  • In ext-core/src/main/resources/META-INF/conf/ep-core-plugin.xml, insert the following bean definitions before the </beans> tag:
                      	<bean id="order" class="com.extensions.domain.order.impl.ExtOrderImpl" scope="prototype"/>
    	<bean id="shoppingCart" class="com.extensions.domain.shoppingcart.impl.ExtShoppingCartImpl" scope="prototype"/>
    
    	<bean id="autoBillEventHandler"
    			class="com.extensions.service.shoppingcart.impl.ExtCheckoutEventHandlerImpl">
    	</bean>
    
    	<util:list id="checkoutEventHandlers">
    		<ref bean="autoBillEventHandler"/>
    	</util:list>