Framework Integration - Play

The multi-table derivation / constraint transaction business logic often represents half the effort in an application.  Even our simple example resulted in 500 lines of traditional code, when you consider the dependency management (what changed?  what depends on that?) across all the Use Cases that touch the data.  And yet, the requirements can be clearly stated in 5 rules on the venerable cocktail napkin.

By contrast, here is all you do to completely replace those 500 lines of business logic code:
  1. Enable the Business Logic Engine with the configuration shown (upper right).  It is not necessary to recode the calling application, which continues to use existing Hibernate/JPA APIs.

  2. Enter your requirements as Logic Annotations in Business Logic Components (Domain Logic Classes that correspond to your Domain Objects).  This makes the venerable cocktail napkin design executable.  More complex logic can be expressed in Java or Groovy logic methods.

There is nothing omitted from this diagram - this is the sum total of all that required to address all the Use Cases listed below.  

With this logic in place, the logic engine now listens for Hibernate commit events, and processes typical transactions as follows:

  • Change Order Paid
Since customer balance depends on this, the engine adjusts it with a 1 row update (not a SQL sum).  If the resultant balance exceeds the creditLimit, the transaction is not committed.
  • Change Order Note
No Logic is dependent on this change, so logic / SQLs are pruned - a 1 row update proceeds.
  • Change product for Line Item
The Orders' amountTotal is adjusted by the new Products' amount (derived by accessing the product.price) minus the old Products' amount with a single row update.  This chains to trigger an adjustment to the customer balance, and a creditLimit check.

@Logic @Play

The gadget spec URL could not be found




Background: the automation gap


The Automation Gap


While there is automation for important parts of an application, the Transaction Logic - 40% of the app - is manually coded.  This is a problem due to:
  • Time and cost: this gap affects business agility and application TCO
  • Complexity: even the approach for manual logic is unclear: a service layer?  DAO Objects?  Hibernate events?

Existing Approaches fall short

Attempts to address the Automation Gap using existing tools appear promising, but fall short:
  • Rete engines provide valuable Decision Logic, but have well-known sum/count performance issues, resulting in a geometric number of reads

  • Process engines are excellent for work flows, but their inherently procedural nature does not enable a declarative approach

  • Hibernate attribute validations fall far short of the typical requirements for multi-attribute validation, and multi-table derivations such as sums and counts

5 Simple Rules, 500 lines of code... why??

To illustrate the cost and complexity of Transaction Logic, consider an application consisting of Customer, their Purchase Orders, the related Line Items, and Parts (Play deployed on Heroku, shown at right).


5 Simple Rules

Let's consider the Add Order Use Case.  The "Check Credit" requirement is succinctly captured in 5 simple rules:
  1. balance < limit
  2. balance = sum (unpaid order totals)
  3. total = sum (item amounts)
  4. amount = price * qtyOrdered
  5. qtyOrdered = copy(Part.price)
It seems so simple... why can't the computer just do this?

500 lines of Java code -- for related Use Cases

Use Cases

  • Add Order
  • Delete Order
  • Pay Order
  • Change Line Item Quantity
  • Change Line Item Part
  • Add Line Item
  • Delete Line Item
  • Is that all?
Like an iceberg, the screen enables a set of related Use Cases not initially visible, shown at right.  
So our simple screen is actually rather complex:
  • Error Prone Analysis: the Developer must first analyze the system to produce the list of Use Cases.  Errors here cause serious breaches in data integrity.  Can you spot the missing case?

  • Complex Design: next, the Developer determines the approach: service layer?  DAOs? Hibernate Events?

  • Large Development effort: handling all of these Use Cases, including their change detection, change propagation, and optimization requires 500 lines of code - examine them here.
Remarkably, the actual processing for each of the Use Cases can be easily inferred from a single set of rules.  For example, the second rule dictates not only that Add Order should increase the balance, but also that the balance should be reduced by Delete Order or Pay Order.

Transaction Logic: 5 simple declarative rules

By contrast, the  windows illustrate the complete logic required to implement Add Order and all the related Use Case;
  • These parallel the Domain Objects (e.g., stored in parallel packages), later used by the Transaction Logic Engine described below.  So, CustomerLogic is the business logic for the Customer domain object.

  • Logic is specified in Java (or Groovy) classes, using an annotated method for each rule (see transparent blue boxes, below).  For example, the CustomerLogic window contains the first 2 rules.

This sample problem illustrates the use and operation of business logic - examine it here.

Referring to the blue callout in the diagram, there are several important aspects worth noting, discussed below.


Automatic Invocation / Re-use - automates multiple Use Cases

Unlike procedural programming where you must explicitly call and order your logic, the rules above are automatically invoked by the Transaction Logic Engine (described below).  The engine assumes the responsibility to monitor all of your transactions, re-using the logic whenever dependent data is changed.

5 Rules = 500 lines of Java

The 5 rules entirely represent the logic that would otherwise require 500 lines of Java.
Consequently, the 5 rules above address all of the Use Cases - automatically.  This not only saves 500 lines of code, it eliminates an entire class of design errors such as neglecting logic elements of a Use Case.

Such automation is familiar.  If you declare a spreadsheet cell as the sum of a column, the spreadsheet "knows" that it should recompute the cell when any column data is altered, or when a row is added or deleted.  In ABL,  the balance = sum (unpaid ordertotals) rule automatically adjusts the balance for all Use cases that touch the dependent data - Add Order, Delete Order, Pay Order, etc.

Automatic Optimization - avoid geometric reads

In a declarative approach, you specify what you want rather than how to do it.  This enables - obligates - the engine to optimize your logic.

The rule balance = sum (unpaid ordertotals) looks very much like a SQL sum.  It is not.

Instead, the logic engine's optimizer utilizes adjustment logic, so altering an amountTotal by X simply adds X to the balance.  select sum logic for purchaseorders and items is replaced by a single row update.

Automatic Ordering - automates maintenance

Inherent in a declarative approach is that rule chaining is supported (one rule can reference the results of another), and that the system assumes the responsibility for detecting dependencies for correct ordering.  So, the derivation rules for balance and ordertotal can be specified in any order.

This is most important during maintenance: in manual code, the principal time is spent in studying the existing code to understand its dependence-based ordering.  ABL eliminates this costly (and unpleasant) "archaeology" by deducing dependencies to compute a correct order of operations.  So, you need only alter rules to meet the business requirements - dependency management / ordering is automatic.

Plug-in Architecture: no re-coding, fits in

This diagram depicts the use and operation of business logic; note that:
  1. You do not directly invoke business logic or the Transaction Logic Engine

  2. Instead, the Transaction Logic Engine listens for Hibernate events (beforeUpdate, beforeCommit, etc).  When these occur, the engine loads your logic classes, determines dependencies using byte code analysis, and executes the logic in a correct and optimized order.

Easy to get started - plug-in means no recoding

No Coding Changes

Since Hibernate/JPA APIs are unaffected, you develop client applications such as the one shown here in exactly the same manner as you are accustomed.

To use business logic, simply configure and add logic classes.
This "plug-in" approach means you don't have to alter your (or your framework's) existing code to utilize business logic.  You simply change a configuration file, and introduce logic classes - at your own pace.

Rule Extensibility

Automation often incurs costs of efficiency, or limitations.  The Transaction Logic engine is designed for extensibility:
  • In addition to using annotations to specify logic, your logic methods can use Java or Groovy logic with if/else, loops, etc as required

  • Such Java/Groovy logic can invoke Java/Groovy methods, so you can build re-usable rule type extensions
ABL includes extensions that illustrate extensibility, and automate classically complex Use Cases such as a Bill of Materials explosion, a deep copy, or the allocation of a Payment to a set of outstanding orders.

Easy to Integrate into your runtime environment

The plug-in approach means that logic follows Hibernate/JPA support for different servers (Stand alone, Web Server, App Server), databases (including App Server distributed transaction support), etc. Anything that runs with Hibernate can use the ABL engine.

Easy to Integrate into your development environment

Logic is specified in Java or Groovy, so you can use your current IDE (e.g., Eclipse) and source control procedures.  Logic provides extensive logging, and can be debugged using standard debuggers.

Secret Sauce: Declarative Encapsulation

Declarative Encapsulation

  • Declarative as in a spreadsheet
  • Encapsulated in Domain Objects for re-use

ABL derives its benefits from the following key elements:

  • Declarative: what not how means:
    • Automatic Ordering, which automates maintenance 
    • Automated Optimizations such as pruning and adjustment help achieve and maintain enterprise class performance

  • Domain Based: logic is supplied on Domain Objects (not specific services), so that the system can enforce them across all Use Cases

  • Plug-in: the plug-in architecture makes it easy to get started (no recoding), and fits into your existing runtime / development environments

Strategic Business Advantage

ABL provides strategic business advantage:
  • Agility: replacing 500 lines of Java code with 5 rules - for 40% of your system - means you can better respond to business change

  • Quality: automated re-use can reduce the common (and painful) scenario often discovered in final tests, where logic elements are not coded into some Use Cases

  • Performance: pruning and adjustment optimizations can reduce the common (and painful) scenario where systems ran fine in development for small database sizes, but require major rewrite to deal with production size data.


You can install a fully executable Play project of the demo shown above as described in the title link.  Note: this is ready to run - the domain objects are defined, the controllers are built, and the project is fully configured.  The database is embedded so requires no installation.

You can configure your own Play project as described in the title link.