Tutorial‎ > ‎

Building Logic Tutorial - Openxava


You can view the essentials of this tutorial in this video, or with a bit more background in this video.

This Tutorial focuses on building a complete application - user interface and business logic.  For information
You can use this Tutorial to understand how to add business logic to a Java-based Openxava web project, from scratch.  In under 20 minutes, you'll build a database, a polished 4 form application, and complex multi-table business logic addressing over a half-dozen Use Cases.

This is Part I, where we create a project with Domain Objects, sample data, and a default User Interface.  This should take approximately 5 minutes.  Completing this prepares you for Part II, where we add business logic to the project created here, and Part III illustrates UI customization. 

In a hurry?  You can install and explore the completed tutorial from here.

Version 4.5

This Tutorial works with Openxava 4.5, only.


This tutorial introduces the following key concepts: 

  • @Logic - how to define Logic Classes and Logic Annotations
  • Complex multi-table logic - how your logic addresses complex, multi-table logic
  • Automated Dependency Management - how logic dependencies are detected and automated
  • Object Declarative - how you can use Java for complexity and extensibility
  • Assured Re-use / Integrity - how the Business Logic Engine ensures your logic is re-used
  • Logic Debugging - how verify your logic is operating properly


In this Tutorial, we will build a small Customer, PurchaseOrder, LineItem and Product application from scratch.  The bottom of this page includes several zip files provided to save typing.

Our focus is on the business logic, not the User Interface, persistence or IDE.  Our business logic objectives, captured on the obligatory cocktail napkin:


The requirements are enforced over a series of Use Cases that touch this data:
  • Adding and changing new PurchaseOrder and their LineItems

  • Making an PurchaseOrder ready, or paid

  • Reassigning a PurchaseOrder to a different Customer

  • Changing LineItem quantities, or Products

We will not focus on the Data Model (which is trivial), or the User Interface.  In fact, we will utilize Openxava since it provides default services for those elements, using standard Java.


64 bit

Be sure to install the 64 bit version of Eclipse / STS, as required by OpenXava.
You will need Eclipse or SpringSource Tool Suite (STS), as explained here.  STS is an extended version of Eclipse, which includes Groovy.

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

Create Project

Execute the steps below to create a new project, its domain model, sample data, and a user interface.  This is standard Openxava functionality, preparing a basic system to which we will then add business logic.

Start Eclipse in Openxava install workspace

Open the Openxava workspace created from the Openxava installation.

Create BusLogicOX Java Project

Click New button in the upper left to create a New > Project:
  1. Select a Java project
  2. Specify the name as BusLogicOX
  3. Accept the default location (which is inside the workspace folder)

Configure for Openxava

As described in the Openxava documentation, configure your new project for Openxava as follows:
  1. In the OpenXavaTemplate project, select and (use right click) to execute the CreateNewProject.xml ant script
  2. Enter your project name (BusLogicOX)
  3. Refresh your project (right click your project > Refresh)
  4. Specify Build Automatically (Project > Build Automatically)

Create the test database

This is an hsql database of CustomersPurchaseordersLineitemsProducts, and CustomerAudits.  Click the thumbnail at right to see the database structure in a new window.

The database is represented as an in-memory hsql database.  Follow this Data Loader procedure so that our test data is re-loaded every time we run the server.  (This is useful - you can make any changes to the data for testing without affecting your next test run).

Create Domain Object (Database Entity)

We will simplify this example by using Groovy, although you can certainly use Java:
  1. Right click your project, and select New > Groovy Class (Openxava Groovy support simplifies our domain objects)
    1. In some perspectives, you may need to navigate additional menus, such as New > Other > Groovy Class
  2. Specify the Package as buslogicox.domain
  3. Specify the (class) Name as Customer
  4. Enter or paste the code shown below

package buslogicox.domain

import javax.persistence.*;
import org.openxava.annotations.*;

class Customer {

@Column(name="name", unique=true, nullable=false)
String name;


This creates a Groovy class, including the necessary annotations for JPA persistence:

Create Server, Install project

We now create a Tomcat server and install our project, as follows:
  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
  4. Add the BusLogicOX project to the server

Test run

At this point, you can test run your application to verify connectivity:
  1. Start the Tomcat server defined above
  2. Run the application in your Browser with http://localhost:8080/BusLogicOX/modules/Customer
You can enter press Add to enter some test customers, and list them as shown at right.  As noted above, this data is in-memory data so there is no danger in altering it.  When you create the rest of the domain model below, the Data Loader will properly re-create the test data each time you run the server.

Domain Driven Development

Note we defined no html files, nor written any controller code.  Openxava builds a complete user interface from the Domain Model.  As we shall shortly see, this extends to automatic construction of master detail layouts and page transitions.  A separate tutorial will illustrate mechanism by which you can enhance and customize the default application.

While this particular scenario involves creating a new model, you can also start with an existing JPA model, of course.  If you don't already have the Domain Objects, you can create them using tools such as MinuteProject, and then add logic and customize the user interface as shown in the remainder of this Tutorial.  This provides significant value in refurbishing existing projects.

Create rest of Domain model

In actual practice, you would now enter the fields and domain objects in the code editor in a similar fashion.  Since we want to focus on business logic and move past the data model, we accelerate this phase:
  1. Download and unpack the buslogicox.domain.zip file also available at the (bottom of this page), and 
  2. Paste the files into buslogicox.domain (replace the existing file).
You can re-run the application as above.   Observe that Openxava has automatically created master/detail and page transition logic.  Do not edit the data at this time, since business logic is not being enforced.  (If you do, simply overwrite your data folder with the data.zip contents).

Standard Hibernate Model, plus UI Customization Annotations

Examine the imported files.  You will find they are standard JPA Domain Objects for Customer, Purchaseorder, Lineitem, Product, and CustomerAudit.  Click the thumbnail at left for an illustration.

The only extension to these is optional - Openxava extensions for UI Customizations.  Unlike conventional approaches for UI customization that involve complex tags and markup, Openxava uses the same declarative annotation-based approach to designate tab sheets, groups, reference data (parent) display / choosing, etc.  You will see these as you run the app, and you can get a brief description here (you can do this now, or at the end of Part II).

Project Creation Complete - Part 1

You now have a simple, but complete, Openxava project, including a database schema and a web interface.

Well, maybe not that complete!  The business logic - see our cocktail napkin above - is totally missing.  Changes to the data at this point result in a loss of data integrity - customer balances and order amounts are incorrect, credit limits are not enforced, etc.

Not to fault Openxava - frameworks simply aren't built to address this element of your app.  The problem is, this is about half the app (even more as framework automation increases).

We are now ready to introduce business logic.