LeBAH Record Template Module

If you have ever develop a database driven application with insert, update, delete operations and records pagination, you may realize that how tedious it was, and it took you lot of development times (hours or even days of development times).

The LeBAH Framework provide a template for you to develop this type of application. I called it a template because it has a set of templates as a based for you start with.

Here, I shall guide you step by step instructions on how to develop a database driven application with the LeBAH Record Template Module.

We are using the same Eclipse Project in the LeBAH Framework Beginner Tutorial.

First, create a Source Folder called tutorial. Under this folder create a Java package called tutorial.entity and another package called tutorial.module, as shown below.

Database

Create a database name tutorial in your MySQL Server.

JAVA PERSISTENCE API

The LeBAH Record Template Module required you to have some knowledge on the Java Persistence API (JPA). Anyway, if you do not know anything about it for now, it is still OK for this tutorial. Just follow through the instructions.

For the purpose of this tutorial, you only need to create the database name tutorial, and you are not needed to create any tables, because we shall let the JPA to do this for us automatically.

The Entity

In any database application, a records is based on a database table, so now we need to create a table for this. Using the JPA, a table is represented by an entity class. An entity is just a normal Java Object (POJO) with some JPA annotations.

Let’s create an entity called Customer. Just a simple Customer class, consists of name, contact number, and a company name. And for an entity, it must have an identity field, the Id.

Below is the Customer class, with JPA annotations.

There are two JPA annotations used in the Java codes above. First is @Entity and second is @Id.

The @Entity annotation is put before the class name to identify this class is an entity, and the @Id is put before the id member variable to identify this variable as the primary key for this entity. Take note that, the id of this entity is of type Long. (Typical data types used as the identity field are usually of type Integer, Long or String).

In the Customer class above, you can see that, in the Customer constructor, the id of the of the Customer object is assigned to a Long value using UID.get() method. This means that each time a new intance of Customer class was created, it shall automatically generate it’s unique id using this method.

Persistence Configuration

In JPA, there is a configuration files called persistence.xml. You need to declare the entity here. In our Eclipse project, this file is located under the source folder called meta an then inside META-INF, as shown in the figure below:

Open the persistence.xml, and add the Customer class as JPA entity by writing <class>tutorial.entity.Customer</class>, as shown below:

The rest of the persistence.xml contains information on how you want the program to connect to the database server. You need to specify the name of the database, in our case, the name is tutorial, and then user and password being used to connect to the database server. In the example above, the user name is root with no password. As a summary, here are the properties we are using to connect to the database server as shown by the persistence.xml example above.

user = root

password =

driver = com.mysql.jdbc.Driver

url = jdbc:mysql://localhost:3306/tutorial

Note that, the value of property “ddl-generation” is “create-tables”. This shall tell JPA to automatically create tables for the listed entities.

Ok, we’ve done with the database.

The LeBAH Record Template

Now let’s begin creating our record template module.

First, let’s look into project files and it’s directory structure as been prepared by LeBAH Framework. Look at the figure below:

In the WebContent folder, there is one folder called RecordTemplate, and inside this folder there is another folder called copy_this_vm. Well…, the name of this folder already told you what you need to do.

Let’s create a new folder called customers under WebContent, and copy all files from copy_this_vm folder into the customers folder.

The Views

There are eight files (with extension .vm) that you have copied. All these eight files was prepared for you as a template, this means, you shall need to modify these files based on your requirements.

Out of all of these eight files, we shall concentrates on four files listed below:

1. row_title.vm

2. row_data.vm

3. entry_page.vm

4. search_page.cm

The four files above is just enough for the requirment in this tutorial.

1. row_title.vm and row_data.vm

These two files are related to each other. row_title.vm is the title part of the table, while row_data.vm is it’s data part.

Our records is about customers as represented by the Customer entity. Let’s look at members declared in the Customer class:

The members are name, contactNo and companyName. These are the attributes (properties) of instace from this Customer class.

Let’s open the row_title.vm:

The row_title.vm provide a template for displaying the title part for the customer records. We want to display three attributes of our Customer, so, you shall modify the above template to this:

Next, is the row_data.vm:

The $!r representing a Customer record. So, we shall modify this template corresponding to what have been done inside row_title.vm:

Next, we have two other vm files, the entry_page.vm and search_page.vm to be modified.

2. entry_page.vm

Open the file entry_page.vm. It begins with some velocity macros, which you must keep it there (meaning do not delete these macros). You may only modify the part that started with <fieldset> and ended with </fieldset> which are located at the bottom.

Shown below is the <fieldset> part of entry_page.vm before modified.

We shall be using the #input macro to display an input field for each Customer attributes.

The #input macro accepts three arguments, the first is the id of the input field, second argument is the label of the data, and the third argument is the data to display. In our requirement for this tutorial we have three attributes - the customer’s name, contact number and company name.

The modified template is as shown below:

Now we have one template left, the search_page.vm.

3. search_page.vm

The purpose of this template is to show search input fields for user to key in their search criteria. The template before modified is shown below:

Let say we want user to be able to do searching by the customer’s name and/or company name. Therefore, the modified search template for this is as below:

OK, we have done with the view templates. Next, we shall create our java class for the LeBAH Record Template Module.

The CustomerRecordModule Class

Under the package tutorial.module, create a java class called CustomerRecordModule.

Make this class to extends lebah.template.RecordTemplateModule.

Please take note that, after the superclass LebahRecordTemplateModule, there are a sharp bracket. Here, you must specify the name of the entity, the Customer.

Because the CustomerRecordModule extends to an abstract class, we need to implements some methods from it.

To do this, place your cursor on top the the light bulb with red x() on the left, and click the mouse button (left click). Eclipse shall display a popup as shown below.

Select Add unimplemented methods. Eclipse shall then, add all the required methods that need to be implemented by the CustomerRecordModule class.

There are 10 methods to be implemented. But for this tutorial, we shall only do the 6 methods listed below:

1. getPath()

2. getPersistenceClass()

3. getIdType()

4. save(Customer arg0)

5. delete(Customer arg0)

6. searchCriteria()

1. getPath()

This method must return the path name of the folder that contains all the views (that we have created before). We have already copied and modified some of the views inside the folder called customers, so this method just need to return the name of this folder.

2. getPersistenceClass()

For this method, you just return the class object of Customer.

3. getIdType()

Every entity has an id, and an id has a type. Some entity may have different type used as it’s id. For our Customer class, the id is of type Long. So, for this method we just return the Long.class.

4. save(Customer arg0)

LeBAH shall call this method whenever your program want to insert new data or update existing data. However, you do not have to specify whether the operation is insert or update, because, the framework shall determine it automatically for you.

The customer’s input data shall comes from the entry_page.vm. In the entry_page.vm, you have created three input field with name, as listed below:

· name

· contactNo

· companyName

These input fields’ names are used by the http request to retrieve the values. You shall use the get(“<field_name>”) method to get the value represented by each name.

Below are the finished codes for the method save().

5. delete(Customer arg0)

The delete method shall return either true or false, depending on criteria you decide when a user want to delete a Customer record.

For the purpose of simplicity in this tutorial, let’s just return a true. This means that, whenever user want to delete a Customer record, it will be deleted without any further checking.

6. searchCriteria()

This method shall return a Map object containing field to values of each search criteria. The search values comes from fields from the search_page.vm.

Below are the finished code for this method.

Well, you have done with the minimum requirements of the LebahRecordTemplateModule. You actually have finished creating this database driven application, with less effort in codings. Most of the tideous task of connecting and reading the database, querying the records, insert, update or delete transactions are all have been taken care of by the LeBAH Framework.

Now, let’s do the test run. Open your Internet browser and key in the URL in the address bar as below:

Click on the Add New button.

Key in the data, and click Save & Add New to save and continue to add another record. Add as many data as you want so that you can see the records pagination, and you can do the testing on the search function.

When you are done, click the Done button.

In this tutorial, you have learned on how to develop a database driven application with less coding effort, using the LeBAH Framework.

Anyway, you have only going through the very minimum requirements fo this. There’s a lot more you can do, for example, you can add your own request method in your CustomerRecordModule.

Because the LebahRecordModuleTemplate is actually extends from LebahModule, which I have introduce in the Beginner LeBAH Tutorial, you can create your own request methods, and marked it with @Command annotation.

Thank You.