Building Logic Tutorial - Openxava Logic Quick Start

These instructions show how to import an existing OpenXava / ABL project, so you can quickly explore the app (click the thumbnail at the right) and code.  If you have Eclipse EE installed, you should be running in under 10 minutes.

Alternatively, view the demo, or explore the Tutorial to see how it was built.


You will need Eclipse (be sure to get an EE version), or SpringSource Tool Suite (STS), as explained here.  STS is an extended version of Eclipse, which includes Groovy.  You will also need a downloaded version of openxava.

This tutorial presumes a basic understanding of Eclipse, Hibernate/JPA and Java.  It does not presume a background in STS or Openxava.

64 bit

Be sure to install the 64 bit version of Eclipse / STS, as required by OpenXava.


The sub-sections below illustrate how to download and import the BusLogicOXQuickStart project into your OpenXava 4.5 workspace.

Folder Setup

Note the "Browse for Folder" screen below.  That illustrates our folder setup (you can certainly use a different one):
    1. Expand as noted in the Prerequisites - this is the OpenXava product
    2. Inside the openxava-4.5.1/workspace folder, expand BusLogicOXQuickStart - the downloaded and expanded the BusLogicOXQuickStart zip 
To install this running Tutorial, please download and unzip these into your own folders now, and execute the steps in the following sections.

Start Eclipse in the OpenXava install workspace

Open the prepared workspace within your OpenXava installation.

In the our folder setup shown above, we'd select the openXava-4.5.1/workspace folder (or equivalent for your install locations).

Import > Existing BusLogicOXQuickStart project

Within Eclipse, File > Import > Existing Project, and select the Quick Start project as illustrated above.

In the our folder setup shown above, we'd select the BusLogicOXQuickStart folder.

Set Project > Build Automatically

If not already set.

Create Server, Add BusLogicOXQuickStart project

Create a Tomcat server and install the project, as follows. Please note: you must use the Tomcat instance bundled in OpenXava.
  1. Open the Servers View and Create a New Server
    • See first screen shot at right (click to expand)

  2. Type is Apache Tomcat V6.0 Server

  3. Specify its location from your Openxava install
    • See second screen shot
    • Important - as noted above, use the Tomcat bundled with OpenXava - you will otherwise get missing jars

  4. Add the BusLogicOXQuickStart project to the server

DataServer Configuration

As illustrated in the diagram below, add the following to your servers/context.xml:


The critical part here is the last line: mem instructs HSQL to use an in-memory database, and memdb is just an arbitrary name for that database.  The screen shot below illustrates the result, and indicates how to find the context.xml file:

You are now ready to run the demo -- but first a bit of background.

Exploring Multi-table Business Logic

You have just created an application that contains an HSQL database of CustomersPurchaseordersLineitemsProducts, and CustomerAudits.  Click the thumbnail at right to see the database structure in a new window.  We'll run the app in a few moments, but some background information will help it make more sense.

If you are familiar with OpenXava, you are aware that the JPA Domain Objects for this database - plus a few annotations - are sufficient to produce a polished application.  If you haven't seen that yet, check out this summary - it's quite remarkable.

So, as a Developer, the remaining challenge is the Business Logic.  Though often used, the term business logic is vaguely defined.  We use it to mean transactional business logic - multi-table computations, validations and actions -- see here.  These are often summarized on the infamous cocktail napkin:

Some notes...

The customer's balance represents the sum of the ready orders that are unpaid 

The multi-table derivation / constraint transaction business logic often represents half the effort in an application.  Even this 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 (add order, delete order, pay order, re-assign Line Item to new Product, etc - a series of multi-table transactions to implement).

And yet, the requirements can be clearly stated in 5 rules on the venerable cocktail napkin.  It shouldn't have to be so hard.

Executable Requirements

Just as OpenXava automates presentation with annotations, ABL automates complex multi-table business logic with annotations.  As shown below, you define a Logic Class for each Domain Object, and provide annotations (or code for more complex cases) to express your logic.  

As you can see below, these annotations correspond exactly to our cocktail napkin - executable requirements.  Except for the audit requirement (discussed below), this is the complete logic for all of the Use Cases that touch this data:

500 lines of code

These 5 simple @Logic annotations represent 500 lines of code.

The key elements are described in the following sections.

The following sections review significant aspects of logic execution.

Automatic Re-use across Use Cases

These requirements are enforced over all the Use Cases that touch this data, including:
    • Test data loading (note the Customer balances are properly initialized)
    • Adding, changing and deleting PurchaseOrders and their LineItems
    • Making an PurchaseOrder ready, or paid
    • Reassigning a PurchaseOrder to a different Customer
    • Changing LineItem quantities, or Products
    Not only does this reduce the implementation effort, it improves quality since you can't "forget" to invoke logic for a corner case (e.g., reassign PurchaseOrder increases new balance, but does not decrease old balance).

    Dependency Management - alter Item Product and Quantity

    To illustrate, execute this scenario:
    1. Start the Tomcat Server
    2. Run the App for Purchase Orders using this url
    3. From Purchase Order list, click Order 3 ("Please rush") to reveal its Line Items
      • Observe that the balance is 85
    4. Click the pencil for the first LineItem (Hammer), and update it as shown at right (click the image to enlarge it):
      • Change the Qty ordered = 2
      • Change the Product = Drill
      • Save
    5. Click Refresh
      • observe that Bravo's Balance is adjusted to 705

    Dependency Management

    Analogous to a spreadsheet, the system recomputes data when referenced attributes are changed.  

    Dependency management can chain, including across tables, thereby automating complex multi-table transactions.
    The system performed this complex, multi-table transaction by automating dependency management:
    • Analyze the transaction to check for alterations to attributes referenced by rules
      • re-execute these derivations (with important sql optimizations described below), 
      • but prune (skip) derivations where referenced attributes are not changed
    • Chain: see if any derived attributes are referenced in still other attributes - process as above
    So we can follow the chain of logic dependencies for our change to the LineItem Quantity / Product:
    1. Since LineItem.productPrice is derived as @ParentCopy(product.price), and our Product (foreign key) has changed, update the productPrice
    2. Since LineItem.amount is derived as qtyOrdered * productPrice and our productPrice has changed, this is recomputed
      • This illustrates dependency-based ordering - derivations are performed in an order reflecting their dependencies
    3. Since PurchaseOrder.amountTotal is derived as @Sum(LineItems.amountTotal) and the amountTotal has changed, this is recomputed
      • This illustrates that multi-table chaining - derivations such as sum reference data in related objects; when these are changed, the derivation is updated (more on performance in a moment)
    4. Similarly, since Customer.balance is derived as @sum(purchaseOrders.amount where paid=false and ready=true), the changed amount causes the system to adjust the balance by the change in the amount
      • This is not quite trivial - the old LineItem was for 1 Hammer @ $10, now replaced by 2 Drills @ $315 - a difference of $620 (hence the balance adjustment).
    5. The system ensures the resultant balance is within the credit limit (else an exception is thrown and the transaction is rolled back)

    Automated Dependency Management confers significant value in agility and TCO:
    • Development: the bulk of your business logic code is typically dependency management.  As illustrated by this example, the 5 annotations replace 500 lines of java code

    • Maintenance: maintenance typically is more about the archaeology of deciphering dependencies so new code can be inserted correctly.  With automated dependency management, you simply add/change your logic, relying on the automated dependency management of the Business Logic Engine to optimize and order the resultant logic.

    Logic Execution, Debugging and Performance

    Active Enforcement

    Event-based logic injection means
    • No recoding - in this tutorial, there was no need to instrument OpenXava to invoke logic

    • Active Logic Enforcement ensures re-use / integrity, since database integrity is not dependent on possibly faulty coding

    ORM Integration - Active Logic Enforcement

    The Business Logic Engine operates not by your direct call, but rather by listening for Hibernate/JPA events.  Such Active Logic Enforcement guarantees that your logic is executed, ensuring database integrity.

    Logic Debugging

    As developers, we spend a considerable amount of time staring at the screen, wondering "what is it doing?".  So we designed business logic for transparent execution:
    • Logging: the Business Logic Engine can be configured to generate log tracing for every rule that fires, with full depiction of the Domain Object attribute state, and logic chaining (nesting)

    • Debugging: for Logic Methods (introduced below), you can use your debugger to stop in rule execution, examine variables, step into/over etc.

    • Test Tools: we provide tools you can use to see all changes to your database, and verify proper changes as jUnit asserts; these can assist in Test Driven Development
    For more information, please see Logic Debugging.

    Logic Performance

    Logic Execution is optimized to prune and optimize database access.  For example, aggregate processing uses adjustment logic - 1 row updates, rather than reading all the aggregated data (particularly important for chained aggregates).

    Logic Extensibility

    Logic Annotations are very powerful.  You will find you can address most business problems in an easy and natural manner.

    But surely not all.  We have therefore designed ABL so that in addition to declarative annotations, your Logic Classes can include Logic Methods -  Java / Groovy Methods to:
      • address complex logic, including the utilization of your existing Java libraries

      • provide Extensible Logic - build new generic services
    The last concept is particularly important.  The full download includes the BusLogicExt project, a library of such extended logic.  This is provided both for your use (these represent the automations of patterns we have seen), and as an illustration of how to build your own extensions (for patterns you detect).

    Dependency Management is fully supported for Logic Method derivations, through byte code analysis to detect references.

    The screen shot below illustrates how to provide auditing logic.  You can test it with the app:
    1. Run the Customer module
    2. Change a Customer's creditLimit. save
    3. Click the Customer audits tab, or view the Eclipse Console

    Next Steps

    Intrigued?  Have questions??  Check out:
    • The Evaluation Guide, which provides a 1 page product summary, with links to the key resources for evaluation
    • The Documentation Center, which explains the logic in detail, and how it addresses complex logic.
    Val Huber,
    Sep 12, 2012, 10:42 PM