These instructions show how to
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
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.
The sub-sections below illustrate how to download and import the BusLogicOXQuickStart project into your OpenXava 4.5 workspace.
Note the "Browse for Folder" screen below. That illustrates our folder setup (you can certainly use a different one):
- Expand openxava-4.5.1.zip as noted in the Prerequisites - this is the OpenXava product
- 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
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
|Create a Tomcat server and install the project, as follows. Please note: you must use the Tomcat instance bundled in OpenXava.
- Open the Servers View and Create a New Server
Type is Apache Tomcat V6.0 Server
- See first screen shot at right (click to expand)
Specify its location from your Openxava install
Add the BusLogicOXQuickStart project to the server
- See second screen shot
- Important - as noted above, use the Tomcat bundled with OpenXava - you will otherwise get missing jars
As illustrated in the diagram below, add the following to your
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
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:
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.
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:
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:
- Start the Tomcat Server
- Run the App for Purchase Orders using this url
- From Purchase Order list, click Order 3 ("Please rush") to reveal its Line Items
Click the pencil for the first LineItem (Hammer), and update it as shown at right (click the image to enlarge it):
- Observe that the balance is 85
- Change the
Qty ordered = 2
- Change the
Product = Drill
- observe that Bravo's Balance is adjusted to
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:
productPrice is derived as
@ParentCopy(product.price), and our Product (foreign key) has changed, update the productPrice
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
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)
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
The system ensures the resultant balance is within the credit limit (else an exception is thrown and the transaction is rolled back)
- 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).
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
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.
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
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 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
- 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:
- Run the Customer module
- Change a Customer's
- Click the
Customer audits tab, or view the Eclipse Console
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.