Personal Library

Concept - Order Creation

Introduction

Note

The feature is introduced in 7.9. with a feature flag. Per default the new order creation handler chains are used. To use the old pipeline-based approach, add the following line to your appserver.properties or development.properties (or some other *.properties file that is loaded).

intershop.order.creationchain.enable = false

References

Glossary

This glossary describes the terms used in this document:

Term	Description
Handler	The implementation of a small functional unit intended to process a single topic which cannot be broken into smaller parts
Handler Definition	The integration of a handler into the context of a chain (using the Component Framework)
Chain	A Chain is composed of one or more Handler Definitions to cover logical steps. From the business point of view it is seen as a sub-chain.
Chain Definition	A complete business flow from business perspective. It comprises one or more sub-chains to one complete "chain".

Basic Design Goals

Application Independence

Minimize the application specific handling related to order creation as much as possible, e.g., promotion code handling via sessions.
Avoid application specific code in handler implementations, e.g., handlers that access request or session.

Performance

Handlers without any dependence to other handlers should be freely combinable related to their execution order in the handler chain:
- Example: It might be wise to process fast validation handlers before time-consuming ones in the pre-order creation handler chain.
  However, this can be a bit tricky, because it depends on the particular situation, e.g., checking max item values of three line items might be faster then payment validation checks, but max item check for 1k line items may change conditions completely.
Introduce performance sensors for each handler implementation (possibly by an abstract super class). Partners and projects may adjust the execution order of handlers in the pre-order creation handler chain to their needs as a kind of performance fine tuning.

Reversibility of Actions

Handlers that perform changes to persistent data have to provide a reversible method to perform rollbacks if necessary. This behavior avoids complex rollback flows in the case of errors.

Basic Handler Chain Framework

Big Picture

Chain Registry

The ChainRegistry contains all ChainDefinition(s) registered for a specific application. A ChainDefinition is added to the ChainRegistry instance of an application either by the Component Framework, if it is specified in an instances.component file, or by adding an instance of ChainDefinition programmatically by calling:

com.intershop.component.handlerchain.capi.ChainRegistry::addChainDefinition(ChainDefinition<?, ?> chainDefinition) : void

A ChainDefinition can be retrieved from the ChainRegistry by providing its Context type, Result type and name:

<C extends Context, R extends Result> com.intershop.component.handlerchain.capi.ChainRegistry::getChainDefinition(Class<C> contextType, Class<R> resultType, String name) : ChainDefinition<C, R>

Example:

...
@Inject ChainRegistry chainRegistry;

ChainDefinition<ExampleContext, ExampleResult> chainDefinition = chainRegistry.getChainDefinition(ExampleContext.class, ExampleResult.class, "ExampleChain");
...

Default Implementation: Class com.intershop.component.handlerchain.internal.ChainRegistryImpl provides a standard implementation of the ChainRegistry interface.

Chain Definition

A ChainDefinition consists of one or more Chain(s). If the ChainDefinition contains multiple Chain(s) than these ones are linked together and executed in the order they are added to the ChainDefinition. A Chain is added to the ChainDefinition either by the Component Framework, if it is specified in an instances.component file, or by adding an instance of Chain programmatically by the following method:

com.intershop.component.handlerchain.capi.ChainDefinition::addChain(Chain<C, R> chain) : void

Example:

Following XML content of an instances.component file defines a ChainDefinition with the name ExampleChainDefinition, consisting of the four Chain(s) Chain1, Chain2, Chain3, Chain4, that will be instantiated and added to the ExampleChainDefinition by the Component Framework:

Example Chain Definition (File: instances.component))

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<components xmlns="http://www.intershop.de/component/2010">
    <fulfill requirement="chainDefinition" of="ChainRegistry">
        <instance name="ExampleChainDefinition" with="ChainDefinition" scope="app">
            <fulfill requirement="name" value="ExampleChain" />
            <fulfill requirement="contextType" value="com.mycompany.component.mycomponent.capi.handlerchain.ExampleContext" />
            <fulfill requirement="resultType" value="com.mycompany.component.mycomponent.capi.handlerchain.ExampleResult" />
            <fulfill requirement="resultMergeStrategy" with="com.mycompany.component.mycomponent.capi.handlerchain.ExampleMergeStrategy" />
            <fulfill requirement="chain">
                <instance name="Chain1" with="Chain" scope="app">>
                    <fulfill requirement="name" value="Chain1" />
                    <fulfill requirement="behaviorOnFailure" value="ROLLBACK" />
                    <fulfill requirement="transactional" value="false" />
                    <fulfill requirement="resultFactory" with="com.mycompany.component.mycomponent.capi.handlerchain.ExampleResultFactory" />
                </instance>
                <instance name="Chain2" with="Chain" scope="app">>
                    <fulfill requirement="name" value="Chain2" />
                    <fulfill requirement="behaviorOnFailure" value="ROLLBACK" />
                    <fulfill requirement="transactional" value="true" />
                    <fulfill requirement="resultFactory" with="com.mycompany.component.mycomponent.capi.handlerchain.ExampleResultFactory" />
                </instance>
                <instance name="Chain3" with="Chain" scope="app">>
                    <fulfill requirement="name" value="Chain3" />
                    <fulfill requirement="behaviorOnFailure" value="ROLLBACK" />
                    <fulfill requirement="transactional" value="false" />
                    <fulfill requirement="resultFactory" with="com.mycompany.component.mycomponent.capi.handlerchain.ExampleResultFactory" />
                </instance>
                <instance name="Chain4" with="Chain" scope="app">>
                    <fulfill requirement="name" value="Chain4" />
                    <fulfill requirement="behaviorOnFailure" value="CONTINUE" />
                    <fulfill requirement="transactional" value="false" />
                    <fulfill requirement="resultFactory" with="com.mycompany.component.mycomponent.capi.handlerchain.ExampleResultFactory" />
                </instance>
            </fulfill>
        </instance>
    </fulfill>
</components>

Default Implementation: Class com.intershop.component.handlerchain.internal.ChainDefinitionImpl provides a default implementation of the ChainDefinition interface.

Chain Executor

The ChainExecutor executes a ChainDefinition, by executing all Chains of the ChainDefinition in the order they are added to the ChainDefinition starting from the first one by calling:

<C extends Context, R extends Result> com.intershop.component.handlerchain.capi.execute(ChainDefinition<C, R> chainDefinition, C context) : R

Execution can be started with a specific Chain too, by calling:

<C extends Context, R extends Result> com.intershop.component.handlerchain.capi.ChainExecutor::execute(ChainDefinition<C, R> chainDefinition, String subChain, C context) : R

Execution starts at the Chain with the name provided by the subChain parameter in this case. Execution of previous Chain(s) of subChain is skipped.

Note

If ChainDefinition::BehaviorOnFailure=ROLLBACK and the processing of one Handler of the Chain specified by subChain finishes with an failure then the method:

<C extends Context, R extends Result> com.intershop.component.handlerchain.capi.Chain::reverseExecute(C context) : R

is called for all preceding Chain(s) of subChain in the ChainDefinition, even if these Chain(s) have not been executed before.

Example:
// subChain = chain3
chain3.execute()
chain3.reverseExecute()
chain2.reverseExecute()
chain1.reverseExecute()

Chain

A Chain consists of one or more HandlerDefinition(s). A HandlerDefinition is added to a Chain instance either by the Component Framework, if it is specified in an instances.component file, or by adding an instance of HandlerDefinition programmatically by the following method:

Chain::addHandler(HandlerDefinition<C> registration) : void

Transactional Behavior

A Chain can span a single transaction over all their Handler(s). This means that all Handler(s) are working in the same transaction.

Behavior on Failure

During the execution of the Chain a Handler may indicate an error as result of its processing. The value of the BehaviorOnFailure attribute specified for the Chain determines how the Chain reacts in this case.

BehaviorOnFailure=STOP

The Chain stops further processing. Subsequent Chain(s) will not be executed.

Chain Transaction: Transactional changes of all Handler(s) of this Chain are rolled back.
Handler Transaction: Transactional changes of the Handler that indicated the failure are rolled back

BehaviorOnFailure=ROLLBACK

The Chain stops further processing. Subsequent Chain(s) will not be executed. The predecessor Chain(s) are reverted using the reverse functionality.

Chain Transaction: Transactional changes of all Handler(s) of this Chain are rolled back.
Handler Transaction: Transactional changes of the Handler that indicated the failure are rolled back.

Method:

com.intershop.component.handlerchain.capi.Handler<C extends Context>::reverseInvoke(C context) : HandlerResult

is called for all Handler(s) of the Chain that have been executed before the one which indicated the failure in reverse order of their previous execution (specified by the position attribute in the HandlerDefinition). Furthermore this method is called for all Handler(s) of previous Chain(s) of the ChainDefinition.

Note that in case of a chain transaction the Handler(s) do not necessarily need to rollback their transactional changes by their own in every case. The complete chain transaction will be rolled back. However, this applies only for the Handler(s) of the Chain that mark changes to the database. Other changes still need to be rolled back by the handler, e.g., the reset of an inventory via an remote inventory service, since such changes are not covered by the database rollback.

BehaviorOnFailure=CONTINUE

The Chain continues its processing. Subsequent Chain(s) will be executed.

Chain Transaction: Transactional changes of all Handler(s) of Chain are rolled back.
Handler Transaction: Transactional changes of the Handler that indicated the failure are rolled back.

Default Implementation: Class com.intershop.component.handlerchain.internal.ChainImpl provides a default implementation of the Chain interface.

Example:

Following XML content of an instances.component file defines three HandlerDefinition(s) instantiated and added to the Chain1 by the Component Framework.

Example Handler Definition (File: instances.component))

<components xmlns="http://www.intershop.de/component/2010">
    <fulfill requirement="handler" of="Chain1">
        <instance with="HandlerDefinition" name="Handler1">
            <fulfill requirement="name" value="Handler1"/>
            <fulfill requirement="position" value="1"/>
            <fulfill requirement="handler">
                <instance with="com.mycompany.component.mycomponent.capi.handler.Handler1"/>
            </fulfill>
        </instance>
    </fulfill>
    <fulfill requirement="handler" of="Chain1">
        <instance with="HandlerDefinition" name="Handler2">
            <fulfill requirement="name" value="Handler2"/>
            <fulfill requirement="position" value="3"/>
            <fulfill requirement="handler">
                <instance with="com.mycompany.component.mycomponent.capi.handler.Handler2"/>
            </fulfill>
        </instance>
    </fulfill>    
    <fulfill requirement="handler" of="Chain1">
        <instance with="HandlerDefinition" name="Handler3">
            <fulfill requirement="name" value="Handler3"/>
            <fulfill requirement="position" value="2"/>
            <fulfill requirement="handler">
                <instance with="com.mycompany.component.mycomponent.capi.handler.Handler3"/>
            </fulfill>
        </instance>
    </fulfill>
</components>

Handler Definition

A HandlerDefinition is a simple structure comprising a Handler implementation, the name of the handler in the Chain and the position of the handler in the execution order of the Chain.

Handler(s) are added to the Chain by HandlerDefinition(s) for the following reasons:

Same Handler instance can be added to the same Chain more than once.
The position of an handler in the Chain cannot be specified at the Handler instance directly.

Context

Beside the ChainDefinition an instance of the Context interface has to be provided to the ChainExecutor by the caller:

public interface ExampleContext extends Context
{
    ....
}

public class ExampleContextImpl extends ContextImpl implements ExampleContext
{
    ....
}

Sub-types of the Context interface should reflect the specific use-case by defining getter- and setter-methods for the data required by the Handler(s) of the Chain(s), e.g., Handler(s) of a Chain that creates an order from a basket require at least the basket. ChainExecutor forwards the Context to the first Chain of the ChainDefinition that is executed as well as whose successors.

Handler

The Chain itself does not provide any functionality. Functionality is provided by the Handler(s) that are added to the chain.

Chain provides the Context as parameter of the invoke(Context context) method to the Handler(s).
A Handler may change the Context by providing or changing any data, e.g. an Order.

A Handler returns its processing state that can be:

SUCCESS: There were no errors during processing of the handler. Note that there still may be warnings!
FAILURE: Processing of the handler led to a failure. Chain decides on further processing based on the value specified for BehaviorOnFailure that can be:
- STOP: Further processing of the Chain and its successors is stopped. Chain is left.
- ROLLBACK: The chain is reversed starting with the predecessor of the failing handler. The Handler which failed has to cover the rollback of the successful completed parts of his own actions by itself.
- CONTINUE: Further processing of the Chain and its successors continues. Handler(s) that are invoked afterwards may be called with another state than expected. So this behavior is suitable for chains that to not change or create any data.
STOP: Further processing of the Chain and its successors is stopped. Chain is left.

Processing state of all Handler(s) of the Chain determines the processing state of the Chain:

{SUCCESS} -> COMPLETED
{STOP}, {SUCCESS, STOP} -> STOPPED
{FAILURE}, {SUCCESS, FAILURE} -> STOPPED (BehaviorOnFailure = STOP)
{FAILURE}, {SUCCESS, FAILURE} -> COMPLETED (BehaviorOnFailure = CONTINUE)

Behavior on Error

txChain - Transaction of the chain.
txHandler - Transaction of the handler.

Scenario	Chain Transaction	Handler Transaction	Chain `BehaviorOnFailure`	Transactional Behavior	Chain Behavior	Remark
1a	Y	(Y/N)	`STOP`	`txChain.rollback`	Chain is left.	This scenario is not possible with `BehaviorOnError.CONTINUE` or `BehaviorOnError.ROLLBACK`.
2a	N	Y	`STOP`	`txHandler.rollback`	Chain is left.	Invocation of `reverseInvoke()` method of previous handlers does not make any sense, because all persistent changes are rolled back by the transaction.
2b	N	N	`STOP`		Chain is left.
3a	Y	N	`ROLLBACK`	`txChain.rollback`	`reverseInvoke()` method of all handlers is called before chain is left.	Transaction is rolled back as well as `reverseInvoke()` methods of previous handlers are invoked in this case. Note that in the case of a re-entry in the chain the changes made by previous handlers have been already committed. Example: Handlers have already created the order in the order creation chain.
3b	N	Y	`ROLLBACK`	`txHandler.rollback`	`reverseInvoke()` method of all handlers is called before chain is left.
3c	N	N	`ROLLBACK`		`reverseInvoke()` method of all handlers is called before chain is left.	Nevertheless is invocation of `reverseInvoke()` method of previous handlers necessary, because there might a previous handler changed persistent data by its own transaction.
4a	N	Y	`CONTINUE`	`txHandler.rollback`	`invoke()` method of next handlers is called.
4b	N	N	`CONTINUE`		`invoke()` method of next handlers is called.

Order Creation Handler Chains

For a list of handlers, please have a look at Cookbook - Order Creation | Recipe: List Chains and Handlers.

Name of Chain	Description	Failure Handling	Transactional
PreOrderCreationChain	This chain is executed before the actual order is created. The purpose of this chain is to check if all preconditions for an actual order are fulfilled. This includes a final basket validation, checks for approval status etc. If all preconditions are fulfilled, the basket is locked to prevent simultaneous checkout of the same basket either via REST or different browsers. The order creation chain might be left in this chain, for example for the approval workflow.	Rollback on Failure	no
OrderCreationChain	This chain creates the actual order with all needed entities, like product line items, addresses, payments etc. and also creates the document number for the order. All order related data should be written in this chain. Once the order is written to the database at the end of this chain, it should not be changed anymore except for status updates. In case of failures, the chain (and with this the database transaction) is rolled back. The result is the same state as before the order creation was started: with a valid basket and no according order.	Rollback on Failure	yes
PaymentAuthorizationOrderCreationChain	This chain takes care of necessary payment authorizations that need a redirect after checkout. If a redirect is necessary, the chain is left for that redirect. A callback from a payment authorization will jump back into this chain for further order creation handling or more redirects. If a callback returns with a failure, the order creation is rolled back, which results in a cancelled order.	Rollback on Failure	no
PendingPaymentOrderCreationChain	A chain for processing all actions that do not need to wait for a successful completion of the payment, like sending of an order confirmation mail.	Continue on Failure	no
PaymentSynchronizationOrderCreationChain	The PaymentSynchronizationChain waits for all asynchronous payment notifications. Notifications from payments start the order creation in this chain. If all notifications were successful, the order creation proceeds with the post order creation handling. If a notification is received with failures, the order creation is rolled back.	Rollback on Failure	no
PostPaymentOrderCreationChain	This chains contains all post order handling, like creation of gift certificates, all necessary promotion handling, budget handling etc. Problems and warnings in this chain will not lead to a rollback anymore.	Continue on Failure	no

The three last chains (PendingPaymentOrderCreationChain, PaymentSynchronizationOrderCreationChain, PostPaymentOrderCreationChain) are needed for the handling of asynchronous payment notifications. If no asynchronous payment is available in the shop, the PaymentSynchronizationOrderCreationChain is not necessary and the PendingPaymentOrderCreationChain could be combined with the PostPaymentOrderCreationChain.

Testing

Handler Implementations

Basic handler chain infrastructure and handler implementation classes have to be tested via JUnit mock tests.

Integration Tests

Complete order creation flows - means finally configured (wired) handler chains - have to be tested by JUnit embedded server tests.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Table of Contents

Introduction

References

Glossary

Basic Design Goals

Application Independence

Performance

Reversibility of Actions

Basic Handler Chain Framework

Big Picture

Chain Registry

Chain Definition

Chain Executor

Chain

Transactional Behavior

Behavior on Failure

BehaviorOnFailure=STOP

BehaviorOnFailure=ROLLBACK

BehaviorOnFailure=CONTINUE

Handler Definition

Context

Handler

Behavior on Error

Order Creation Handler Chains

Testing

Handler Implementations

Integration Tests