JACOBDesignerTutorial

From JACOBWiki

Jump to: navigation, search

Contents


jACOB™ Designer


Tutorial HappyHome

(advanced)


[edit] Objectives

In this tutorial, we're going to create a very simple business app to show you how easy it is to get started with jACOB.

[edit] Prerequisites

Depending on the jACOB™ Version you are using, preparing the prerequisites will differ.

1. Happy Home with the jACOB™ Enterprise Version (you may alternatively work the same way like described in Happy Home with Open- jACOB™ )

a) You must have the the jACOB™ Enterprise Version installed an be able to log into the Admin Application (see Installing jACOB Enterprise Edition in Apache Tomcat )

b) You must have your jACOB™ Designer installed in Eclipse (see: Install jACOB Designer)

2. Happy Home with Open-jACOB™

  • You must have your jACOB™ Designer installed in Eclipse (see: Install jACOB Designer)

[edit] Getting started

Introduction by means of an example

The development of a jACOB™ application will be explained by means of a simple example:

The real estate agency Happy Home advertises houses, apartments and lands in newspapers and in the internet. Customer requests are accepted by telephone and by e-mail. In this chapter we want to develop a jACOB™ application that processes the customer requests of Happy Home.

Process

Happy Home processes customer requests in the following way:

1. A landlord who wants to sell his house, apartment or land offers his real estate object for sale at Happy Home.

2. Another person is in search of a real estate object and finds this real estate object advertised by Happy Home interesting.

3. The interested person phones/writes an e-mail to the agency to show his/her interest and to gather further information about the real estate object.

4. The receptionist receiving the phone call/e-mail registers the person’s request.

5. In turn he/she passes an agent as contact person to the interested person.

6. The agent will get in touch with the interested person. He will give the desired information to the interested person and arrange a date for an inspection of the real estate object.

The process model

Out of this we can abstract the following process model:

Figure 2.1. Process model of the real estate agency Happy Home

Procedure

It’s time to think of a name for our example jACOB™ application. Let’s call it happyHome. In the next sections we will develop step by step this application:

1. Create a new Eclipse project for happyHome

2. Define the jACOB™ application design of happyHome

3. Build the jACOB™ application happyHome

4. Define table hooks for happyHome

5. Define GUI hooks for happyHome

6. Change the user management of happyHome

[edit]  Create a new Eclipse project for happyHome

Intention

First of all we have to create a new Eclipse project for our example jACOB™ application happyHome.

Procedure

To do this perform the following steps:

1. Open Eclipse.

2. Change to the jACOB Programming perspective by clicking the Tab jACOB Programming perspective in the upper right area.

3. Select File - New - Project... from the menu bar.

4. After this a dialog box will pop up asking you to select a project wizard.

5. Select the wizard jACOB - Empty project and continue by pressing the Next > button.

6. Then you will be prompted to enter a Project name.
Enter "happyHome" into the text field and confirm by pressing the button Finish.

Impact

Hereafter, the jACOB™ wizard will create the empty project "jacob.happyHome".

The project structure can be viewed in the Package explorer situated in the upper left screen area:

Figure 2.2. jACOB™ project structure

In the project structure we can find the file "application.jad". This file contains the jACOB™ application design of happyHome. The structure of the application design can be viewed in the Application Outline view located in the lower left area by clicking on "application.jad":

Figure 2.3. jACOB™ application design

[edit]  Depoly the jACOB™ application happyHome

Intention

We want to see that we are able to deploy and run jACOB Applications. Again, depending on the jACOB™ Version you are using, the first Deployment will differ.

Deploy HappyHome in jACOB™ Enterprise Version

You may alternatively work the same way like described in Deploy Happy Home in Open- jACOB™

Procedure

Proceed the following steps:

Step Procedure
1 Open the file "build.properties" in the Package explorer with right mouse click and selecting: open with - Texteditor

Step Procedure
2 Change the line :
jacob.url=http://localhost:8080/happyHome/
to your settings.
(usually: jacob.url=http://localhost:8080/jacob/)
3 Save the file by pressing the save icon

in the upper left screen area.

4 Select the file "build.xml" and Choose Run As - Ant Build... from the right mouse button menu.
5 Unselect the selected targets and Select the target "jacapp"
6 To build the application press "run"
7 Log into your Admin Application (the following steps are described more detailed in the Administration manual, we will just give a short description here)

8 Chose the form "Applications" from your "Engine" domain an press the Button "Upload Applications"
9 In the file Dialog select the file "happyHome-0.1.jacapp" from the directory
yourEclipseWorkspace/jacob.happyHome/dist
Press Open an in the next Dialog Box Upload.
The Message: Application successfully deployed appears, click OK.
10 Define the datasource. To keep it easy, we suggest to define a HSQL Datasource. If you prefer another Database System, see the Administration Manual.
To define the datasource, click on the Datasource row in the Assigned data sources Browser.

Step Procedure
11 Fill in the form as shown below and press save.

Step Procedure
12 Press the Reconfigure button and press Reconfigure in the following Dialog

Step Procedure
13 Press the Execute button in the following Dialog

Step Procedure
13 Go back to the Applications screen, press the Change button, change the field Status to "productive" and press save.
14 Log out of the Administration application
15 Log into your HappyHome Application with the username "admin" and no password. You should see a screen like this

Remarks

That procedure has only to be done once per Application. From now on you will deploy the changes to your Application by just pressing the icon within the jACOB Designer.

Deploy HappyHome inOpen-jACOB™

You will find a detailed description in the manual : Deploy your first Open-jACOB Application.

Procedure

Proceed the following steps:

Step Procedure
1 Select the file "build.xml" and Choose Run As - Ant Build... from the right mouse button menu.
2 Select the target "all"
3 To build the application press "run"
4 After a successful execution of the build.xml you have a valid Web Application Archive (war)
for deployment. The war file will be stored in the <MyProject>/dist directory. You have built your first jACOB application with a valid build-in database. Now you may copy the war file into the tomcat/webapps directory and start/restart the tomcat. No additional configuration is required.
5 Log into your HappyHome Application with the username "admin" and no password. You should see a screen like this
 

Remarks

That procedure has only to be done once per Application. From now on you will deploy the changes to your Application by just pressing the icon within the jACOB Designer.

Next Step

The next step will be to:

Define the jACOB™ application design of happyHome

[edit]  Define the jACOB™ application design of happyHome

Intention

In the next sections we want to develop a jACOB™ application design for our example application happyHome.

As already stated in the chapter the jACOB™ application design defines the data model, forms, domains, etc. of a jACOB™ application.

Data model

The first thing we will have to do is to define the data model. We will do this with the aid of an object relationship model.

By means of the process model illustrated in figure Process model of the real estate agency Happy Home we can easily derive the appropriate object relationship model.

Objects

We are dealing with six different objects:

  • Landlord
  • Real estate object
  • Interested person
  • Receptionist
  • Agent Request

Relationships

These objects are standing in relation to each other:

  • Landlord - Real estate object:

A landlord offers one or more real estate objects for sale. But one real estate object uniquely belongs to one landlord.

  • Interested person - Agent:

An interested person has one agent as contact person. But one agent can be in charge for one or more interested persons.

  • Interested person - Request:

An interested person can make one or more requests. But a request is uniquely assigned to one interested person.

  • Request - Real estate object:

A request is uniquely assigned to one real estate object. However, one real estate object can be the subject of one or more requests.

  • Request – Receptionist
    A request has been registered by one receptionist. But one receptionist can register multiple requests.

Object relationship model

We can illustrate these object relationships as follows:

Figure 2.4. Object relationship model of happyHome

Procedure

In the next sections we will define step by step the data model:

  • Define the tables of happyHome
  • Define the table aliases of happyHome
  • Define the relation sets of happyHome
  • Define the browsers of happyHome

After this we will:

  • Define the forms of happyHome
  • Define the domains of happyHome

[edit]  Define the tables of happyHome

Intention

In this section we want to define the data tables for our example application happyHome. We will do this with the aid of the object relationship model illustrated in figure Object relationship model of happyHome.

Tables

Defining one table for each object of the object relationship model would be the first approach. However, contemplating the object relationship model we can see that the objects Landlord, Interested person, Receptionist and Agent are all persons. Therefore, these objects can be combined in one table: individual.

The remaining objects Real estate object and Request cannot be combined in one table. Thus, we can derive the following tables from the object relationship model:

  • individual
  • realEstateObject
  • request

Now we have to consider the table structures such as columns, column types, column lengths, etc.

Table individual

An individual will be identified by an unique id.

Each individual has a first name, a surname and a composed fullname. Furthermore he/she has an address, a phone number and optionally an e-mail address.

An individual is either an internal employee of Happy Home or an external individual. If the individual is an internal employee, he/she is a receptionist, an agent or both.

An external individual is a landlord, an interested person or both. An interested person is assigned to an agent with a unique id.

This information leads to the following table structure:

[edit] Table 2.1. Table individual

Column Name Type Length Required
id LONG   X
firstName TEXT 40 X
surname TEXT 40 X
fullname TEXT 80  
address TEXT 80 X
phone TEXT 20 X
email TEXT 40  
individualType ENUM   X
receptionist INTEGER   X
agent INTEGER   X
agent_id LONG    

[edit] Table 2.2. Table realEstateObject

A real estate object will be identified by an unique id.

Each real estate object has an address and a description illustrating the object itself and its location.

A real estate object is either an apartment, a one-family house, an apartment house or a piece of land.

It can be for sale, for rent or even for both. Therefore, a real estate object has a purchase price and a rental fee.

Each real estate object is assigned to a landlord with a unique id.

This information leads to the following table structure:

Table 2.2. Table realEstateObject

Column Name Type Length Required
id LONG   X
address TEXT 80 X
description LONGTEXT   X
type ENUM   X
saleOrRent ENUM   X
purchasePrice DECIMAL    
rentalFee DECIMAL    
landlord_id LONG   X

Table request

A request will be identified by an unique id.

Each request is characterized by a short description and a long description.

A request has a registration date and is uniquely assigned to a receptionist and an interested person.

This information leads to the following table structure:

[edit] Table 2.3. Table request

Column Name Type Length Required
id LONG   X
shortDescription TEXT 80 X
longDescription LONGTEXT    
registrationDate TIMESTAMP   X
receptionist_id LONG   X
interestedPerson_id LONG   X

Define data source

Select the folder Physical Data Models in the Application Outline view.

Select the menu item New physical data model from the right mouse button menu.

After this a dialog window will pop up asking you to specify a symbolic name for the data source containing the tables.

Enter "happyHomeDataSource" into the text field and confirm your input.

Hereafter, jACOB™ designer will create the folder happyHomeDataSource within the folder Physical Data Models.

Define Tables

In the next sections we will:

  • Define the table individual
  • Define the table real estate object
  • Define the table request

[edit]  Define the table individual

Intention

Now we want to define the table for individuals as illustrated in Table individual.

The column agent_id is a foreign key field. This column will not be created in this work step but in a later work step when we will define the relationsets of happyHome. Then this column will be added automatically to the table individual as foreign key field.

Procedure

Proceed the following steps:

Step Procedure
1 Select the folder happyHomeDataSource in the Application Outline view.
2 Select the menu item New table from the right mouse button menu.
After this a dialog window will pop up asking you to specify the table name.
3 Enter "individual" into the text field and confirm your input.
Hereafter, jACOB™ designer will create the table object individual within the happyHomeDataSource and open the table editor in the right upper screen area.
The table editor displays the table structure of individual.
4 jACOB™ has already created one column object containing the primary key of the table "pkey".
5 Add the columns firstName, surname, fullname, address, phone and email by pressing the button Add.
Specify the lengths as defined in Table individual by entering the appropriate lengths into the field Max. length.
All columns but the column email and fullname are required columns. This can be defined by activating the check box Required.
The column fullname is composed by the firstName and surname and should be marked as read only. This can be done by activating the check box Readonly.
6 Add the required column individualType.
Therefor select ENUM in the field Type.
Specify "internal" and "external" in the field Enum values and "external" in the field Default.

7 Add the required columns receptionist and agent.
Therefor select Boolean in the field Type.

[edit]  Define the table real estate object

Intention

Now we want to define the table for real estate objects as illustrated in Table realEstateObject.

Like the column agent_id of the table individual the column landlord_id is a foreign key field. It will be automatically created in the work step Define the relation sets of happyHome.

Procedure

Proceed the following steps:

Step Procedure
1 Create a new table with the name "realEstateObject" in the folder happyHomeDataSource of the Application Outline view.
2 Enter the following fields:
3 Add the required columns address and description.
Therefor select TEXT and LONGTEXT respectively in the field Type.
Specify the maximum length for the column address in the field Max. length.
4 Add the required column saleOrRent.
Therefor select ENUM in the field Type.
Specify "sale", "rent" and "saleOrRent" in the field Enum values.
5 Add the columns purchasePrice and rentalFee.
Therefor select DECIMAL in the field Type.
6 Add the required column objectType.
Therefor select ENUM in the field Type.
Specify "apartment", "oneFamilyHouse", "apartmentHouse" and "land" in the field Enum values.

[edit]  Define the table request

Intention

Now we want to define the table request as illustrated in Table request.

Like the column agent_id of the table individual the columns receptionist_id and interestedPerson_id are foreign key fields. They will be automatically created in the work step Define the relation sets of happyHome.

Procedure

Proceed the following steps:

Step Procedure
1 Create a new table with the name "request" in the folder happyHomeDataSource of the Application Outline view.
2 Enter the following fields:
3 Add the required column shortDescription and the not required column longDescription.
Therefor select TEXT and LONGTEXT respectively in the field Type.
Specify the maximum length for the column shortDescription in the field Max. length.
5 Add the required column registrationDate.
Therefore select TIMESTAMP in the field Type.
Set the Resolution to minutes. The current date and time can be declared as default value by activating the check box Initialize with now.

6 Save your changes to the application design. To do this click on the Save icon

in the upper left screen area.

Figure 2.5. Tables of happyHome

The next step will be to:

Define the table aliases of happyHome

[edit]  Define the table aliases of happyHome

Intention

In this section we want to define the table aliases for our example application happyHome.

The jACOB™ designer automatically creates for each new table one table alias. These can be found in the folder Table aliases in the Application Outline view.

Figure 2.6. Initial table aliases of happyHome

Table aliases on table individual

In the section Define the tables of happyHome we were combining the objects Landlord, Interested person, Receptionist and Agent to one table: individual. Now we want to define for each object an alias on this table:

  • landlord:

Landlords are individuals where the column individualType equals "external".

  • interestedPerson:

Interested persons are also persons where the column individualType equals "external".

  • receptionist:

Receptionists are all persons where the column receptionist equals "1" and column individualType equals "internal".

  • agent:
    Agents are all persons where the column agent equals "1" and column individualType equals "internal".

Procedure

Perform the following steps to define these table aliases:

Step Procedure
1 On the folder "Table aliases" right click and select new. Select the table "individual" an press OK Enter the Alias Name "landlord. The Table alias Editor is opened.
2 Specify the Condition as " landlord.individualtype=’external’ "

3 Click on Table aliases in the Application Outline view.
Create a new table alias by selecting New table alias from the right mouse button menu.
Hereafter, a dialog window will pop up asking you to select a table.
4 Select the table individual in the dialog window.
After this, another dialog window will emerge asking you to specify a name for the new table alias.
5 Enter "interestedPerson" into the text field of the dialog window and confirm your input.
The jACOB™ designer will create the new table alias and open it in the Table alias editor.
6 Enter the Condition " interestedPerson.individualtype=’external’ ".
7 Create the table alias receptionist with the Condition "receptionist=true AND individualType=’internal’ " in the same way.
8 Create the table alias agent with the Condition "agent=true AND individualType=’internal’" in the same way.
9 Save your changes to the application design. To do this click on the Save icon

in the upper left screen area.

Now we have defined the table aliases of happy home:

Figure 2.7. Final table aliases of happyHome

Next Step

The next step will be to:

Define the relation sets of happyHome

[edit]  Define the relation sets of happyHome

Intention

In this section we want to define the relation sets for our example application happyHome.

We will do this again with the aid of our object relationship model illustrated in figure Object relationship model of happyHome. If we contemplate the object relationship model, we could combine the relations of the model to one relation set. Let’s call this relation set requestRelations.

Relation between customer and agent

In the object relationship model all relationships are illustrated as one to many relationships. jACOB™ designer realizes a one or zero to many relation by the creation of a foreign key in the table of the relation’s many-side. It will mark the foreign keys of one to many relations as required and the foreign keys of zero to many relations as not required.

When we were constructing the object relationship model we were not aware that we would combine the objects landlord, interested person, receptionist and agent to one table, the table individual. After the definition of the table aliases we can see that the relation between interested person and agent is a relation between two table aliases of one and the same table.

If we realize this relation as a one to many relation, this will mean that also each receptionist, each agent and each landlord unfortunately will have to be assigned to an agent. Implementing this relation as a zero to many relation avoids this conflict.

Procedure

Perform the following steps to define the relation set requestRelations:

Step Procedure
1 Select the folder Relation sets in the Application Outline view.
2 Create the new relation set requestRelations by selecting New relation set from the right mouse button menu of Relation sets.
Hereupon, jACOB™ Designer creates the new relation set and opens the Relation sets editor.
3 Select the table alias request in the Application Outline view and drag the table alias to the Relation sets editor. Drop request in the middle of the editor.
4 Add the other table aliases into the Relation sets editor in the same way.

5 Create the one to many relation between request and interestedPerson.
To do this, click first on the toolbar button Relation. After this draw the relation by clicking first on request (many-side of the relation) and then on interestedPerson (one-side of the relation).
jACOB™ Designer initially creates a zero-to-many relation. We will have to transform this relation to a one-to-many relation, now. To do this, click first on the toolbar button Select and select the relation. Then choose One to many from the right mouse button menu.
6 Create the relations between request and realEstateObject and between realEstateObject and landlord in the same way.
7 Create the relation between request and receptionist as described in step 5.
Due to the fact that this is the second relation between the tables request and individual, jACOB™ designer will ask you to select a foreign key. Define a new foreign key by selecting <<new>> from the menu.
8 Create the zero to many relation between interestedPerson and agent as described in step 5 (however, without the transformation).
9 Save your changes to the application design. To do this, click on the Save button

in the upper left screen area.

Impact on Relations

jACOB™ Designer automatically creates for each relation of the relation set a relation object in the background.

Impact on tables

As already stated above, jACOB™ Designer also automatically creates for each relation a foreign key and a foreign key column in the appropriate table.

In the figure below we can see the following foreign keys and foreign key columns:

Table individual:

  • agent_FKey and agent_key

Table realEstateObject:

  • landlord_FKey and landlord_key

Table request:

  • realEstateObject_FKey and realEstateObject_key
  • interestedPerson_FKey and interestedPerson_key
  • receptionist_FKey and receptionist_key

Figure 2.9. Foreign keys of happyHome

Next Step

Now we have defined the relation sets and relations of happy home.

The next step will be to:

Define the browsers of happyHome

[edit]  Define the browsers (hitlists) of happyHome

Intention

In this section we want to define the browsers for our example application happyHome.

A browser lists data records in a tabular form. The browser definition determines which table columns are displayed in which order.

Browsers will appear all along in an application in form of search browsers, inform browsers and foreign field browsers.

A browser is uniquely assigned to a table alias. Therefore, the jACOB™ designer automatically creates for each new table alias a browser. These can be found in the folder Browsers in the Application Outline view.

Figure 2.10. Browsers of happyHome

Initially, these browsers display only one column, the primary key of the appropriate table. In the following we will extend the definitions of these browsers.

Definition of browsers on the table individual

We want to give a unique look to all browsers which are assigned to a table alias on the table individual. These are the browsers:

  • agentBrowser
  • landlordBrowser
  • individualBrowser
  • receptionistBrowser

They should show the following table columns in the following order:

  • surname
  • firstName
  • address
  • phone
  • pkey

Definition of the browser on the table realEstateObject

The browser on the table realEstateObject should show the following table columns in the following order:

  • objectType
  • saleOrRent
  • purchasePrice
  • rentalFee
  • fullname of the landlord (retrieved from the related table alias landlord)
  • address
  • pkey

Definition of the browser on the table realEstateObject

The browser on the table request should show the following table columns in the following order:

  • fullname of the receptionist (retrieved from the related table alias receptionist)
  • registrationDate
  • shortDescription
  • fullname of the interested person (retrieved from the related table alias interestedPerson)
  • pkey

Procedure

Perform the following steps to obtain these browser definitions:

Step Procedure
1 Select the agentBrowser in the Application Outline view by double clicking the browser icon.
The browser definition will be opened in the Browser editor.
2 Press the button Add column and select the table column surname.
3 To position surname before id press the button Up.
4 Add and position the columns firstName, address and phone in the same way.
5 Edit the browser definitions of the landlordBrowser, individualBrowser and receptionistBrowser like the agentBrowser.
6 Edit the realEstateObjectBrowser as defined above.
However, add the table column fullname as foreign browser column.
Therefor press the button Add table instead of the button Add column and select the table alias landlord.
Set the foreign browser column Name to "browserLandlord", the Label to "Landlord", the Relationset to use to "requestRelations" and the Display column to "fullname".

7 Edit the requestBrowser as defined above.
Add the table columns fullname as foreign browser columns of the table aliases receptionist and interestedPerson respectively.
8 Save your changes to the application design. To do this click on the Save icon

in the upper left screen area.

Next Step

Now we have defined the browsers of happy home.

The next step will be to:

Define the forms of happyHome

[edit]  Define the forms of happyHome

Intention

In this section we want to define the forms for our example application happyHome.

Forms

First of all we will create a form for the registration of the employees of Happy Home, i.e. receptionists and agents.

Then we will develop a form for the registration of the real estate objects. This form will also include the registration of new landlords.

Finally we will construct a form for the registration of the requests. This form will also include the registration of new interested persons.

Define forms

In the next sections we will:

  • Define the form employee
  • Define the form realEstateObject
  • Define the form request

[edit]  Define the form employee

Now we want to define the form for the registration of Happy Home employees as illustrated below.

Figure 2.11. The form employee

Table alias employee

The form employee will contain only one group, the group Employee. In jACOB™ Designer a group is always assigned to one table alias. Happy Home employees can be receptionists, agents or both. Therefore, we will have to create the table alias employee on the table person before we can define the form employee.

Browser on employee

As already stated in the section Define the browsers of happyHome the creation of a new table alias implies also the creation of an appropriate browser. The new browser employeeBrowser initially contains only one column the primary key id.

We will define the employeeBrowser like the other browsers on the table person, i.e. employeeBrowser should contain the following columns in the following order:

  • surname
  • firstName
  • id

Procedure

Proceed the following steps:

Step Procedure
1 Create the table alias employee on the table person with the condition "personType=’internal’". The creation of table aliases is explained in the section Define the table aliases of happyHome.
2 Edit the employeeBrowser as explained in the section Define the browsers of happyHome.
3 Create a new form.
To do this, select the folder Forms in the Application Outline view and select the menu item New Form from the right mouse button menu.
Enter "employee" into the text field of the dialog window.
Hereafter, jACOB™ designer creates the form object employee within the folder Forms and opens the form in the form editor in the right upper screen area.
4 Before we can add elements to the form, we will have to draw a group into the form.
Therefor select Group from the folder DB Elements in the form editor’s toolbar.
Position the upper left corner of the group by pressing the left mouse button and draw the group by keeping the left mouse button pressed.
Then, jACOB™ Designer will ask you for the appropriate table alias. Select employee<person>.
Hereafter, jACOB™ Designer will create the group Employee. The four buttons Search, Clear, New and Update will be created automatically.
5 Add the text field for the Id into the form.
Therefor select Text from the folder DB Elements in the form editor’s toolbar.
Place the text field at the desired position in the group Employee by pressing the left mouse button.
DB text fields are always assigned to a table column. Therefore, jACOB™ Designer will ask you for the appropriate table column. Select the column id.
Hereafter, jACOB™ Designer will automatically create the appropriate label. jACOB™ Designer retrieves the string from the column object.
6 Add the text fields for the First name, Surname, Fullname, Address, Phone and Email in the same way.
The labels of the text fields can be edited in the properties editor or by clicking on the label.
7 Add the checkboxes Agent and receptionist.
Therefor select Checkbox from the folder DB Elements in the form editor’s toolbar.
Position the checkbox into the form by pressing the left mouse button.
Also DB checkboxes are always assigned to a table column. Therefore, jACOB™ Designer will ask you for the appropriate table column. Select the column agent and receptionist respectively.

GUI buttons

The jACOB™ Designer automatically creates the following GUI buttons in each group:

  • Search:

With the aid of this button you can run constrained searches on the appropriate table alias. The search condition is composed by the content of the group’s data fields. The search result will be displayed in the appropriate search browser.

  • Clear:

Pressing this button will clear the content of the group’s data fields.

  • New:

The New button enables the creation of a new record in the appropriate data table.

  • Change:

    The Change button enables the modification of an already existing data record.

[edit]  Define the form realEstateObject

Now we want to define the form for the registration of real estate objects as illustrated below. With the aid of this form we also want to register new landlords.

Figure 2.12. The form realEstateObject

Therefore, the form realEstateObject will contain two groups:

  • RealEstateObject:

The group RealEstateObject will be assigned to the table alias realEstateObject.

  • Landlord:

    This group will be assigned to the table alias landlord.

Foreign field Landlord

The group RealEstateObject will contain the text field Landlord displaying the landlord owning the real estate object. The current table realEstateObject has already the foreign key column landlord_key. We could use this column to identify the landlord of course. However, this is an id and an id doesn’t say very much to the user. Therefore, we will define the field Landlord as foreign field showing the fullname of the landlord.

Procedure

Proceed the following steps:

Step Procedure
1 Create the new form realEstateObject. How to do this is explained in step 2 of the procedure Define the form employee.
2 Add the group RealEstateObject into the form. How to do this is explained in step 3 of the procedure Define the form employee.
3 Add the text fields Id, Purchase price, Rental fee and Address into the form.
4 Insert the foreign field Landlord.
Therefor select ForeignField from the folder DB Elements in the form editor’s toolbar.
Place the foreign field in the group RealEstateObject.
DB foreign fields are always assigned to a table column of a foreign table alias. Thus, jACOB™ Designer will ask you for the appropriate table alias. Select the table alias landlord.
After this we change into the Properties view and set the foreign field’s Caption to "Landlord", the Name to "realEstateObjectLandlord", the Foreign field to display to "fullname" and the Relationset to "requestRelations".

Add the long text field Description into the form.
Therefor select Long text from the folder DB Elements in the form editor’s toolbar.
Position the long text field in the form.
DB long text fields are always assigned to a table column. Therefore, jACOB™ Designer will ask you for the appropriate table column. Select the column description.
Add the comboboxes Object type and Sale or rent into the form.
For this purpose select Combobox from the folder DB Elements in the form editor’s toolbar.
Place the comboboxe in the form.
Position the upper left corner of the long text field by pressing the left mouse button and draw the combobox by keeping the left mouse button pressed.
DB comboboxes are always assigned to a table column. Therefore, jACOB™ Designer will ask you for the appropriate table column. Select the column objectType and saleOrRent respectively.
Add the group Landlord into the form.
Construct this group in the same way as the group Employee in the employee form . However, leave away the checkboxes Agent and Receptionist.

[edit]  Define the form request

Intention

In this step we want to define the form for the registration of customer requests as illustrated below. With the aid of this form we also want to register new customers, i.e. here interested persons.

Figure 2.13. The form request

Therefore, the form request will contain three groups:

  • Request:

The group Request will be assigned to the table alias request.

  • Interested person:

This group will be assigned to the table alias interestedPerson.

  • Real estate object:

The group Real estate object will be assigned to the table alias realEstateObject. This group serves for linking an already existing real estate object to a request. Therefore, this group will contain only the Search and the Clear button.

Foreign field Receptionist

The group Request will contain the text field Receptionist displaying the receptionist who has registered the request. The current table request has already the foreign key field receptionist_FKey. We could use this field to identify the receptionist of course. However, this is an id and an id doesn’t say very much to the user. Therefore, we will define the field Receptionist as foreign field showing the fullname of the receptionist.

Foreign field Agent

The group Interested person will contain the text field Agent displaying the agent who is responsible for the person. Like the field Receptionist we will define this field as foreign field on the fullname of the agent.

Procedure

Step Procedure
1 Create the new form request. .
2 Add the group Request into the form..
3 Add the text fields Id and Short description into the form.
4 Add the long text field Long description into the form..
5 Add the timestamp field Registration date into the form.
For this purpose select Timestamp from the folder DB Elements in the form editor’s toolbar.
Position the timestamp field into the form by pressing the left mouse button.
DB timestamp fields are always assigned to a table column. Therefore, jACOB™ Designer will ask you for the appropriate table column. Select the column registrationDate.
6 Insert the foreign field Receptionist.
Change into the Properties view and set the foreign field’s Caption to "Receptionist", the Name to "requestReceptionist", the Foreign field to display to "fullname" and the Relationset to "requestRelations".
7 Add the group Interested person assigned to the table alias interestedPerson. Position this group below the group Request.
8 Construct this group in the same way as the group Employee in the employee form . However, leave away the checkboxes Agent and Receptionist. Add the foreign field Agent instead.
9 Add the group Real estate object below the group Interested person.
10 Construct this group in the same way as the group Real estate object in the realEstateObject form . However, remove the GUI buttons New and Change.

11 Save your changes to the application design. To do this click on the Save icon

in the upper left screen area.

Next Step

Now we have defined the forms of happy home:

The next step will be to:

Define the domains of happyHome

Figure 2.14. Forms of happyHome

[edit]  Define the domains of happyHome

Intention

In this section we want to define the domains of our example application happyHome.

A jACOB™ Designer domain is a folder like element grouping forms to a dedicated workspace.

Domains

In the previous section we have defined three different forms. Now we will group these forms to the following domains:

  • administration domain:
  • employee form
  • agent domain:
  • realEstateObject form
  • request form
  • registration domain:
  • request form

The domains of a jACOB™ application are located in the folder Composed Application UI of the Application Outline view.

Procedure

Perform the following steps to obtain these domains:

Step Procedure
1 Create the domain administration.
To do this, select the folder Composed Application UI in the Application Outline view and choose New Domain from the right mouse button menu.
Enter "administration" into the text field of the dialog window.
2 Add the form employee to this domain.
Therefor select the domain and choose Add Form from the right mouse button menu.
Select the form employee from the listbox of the dialog window.
3 Create the domain agent as described above.
4 Add the forms realEstateObject and request to this domain as explained above.
5 Create the domain registration containing the form request in the same way.
6 Save your changes to the application design. To do this click on the Save icon

Image:JACOBDesignerTutorial neu1 43.png in the upper left screen area.

Next Step

Now we have defined the domains of happy home:

Figure 2.15. Domains of happyHome

The jACOB™ application design is now complete. After all this we can now:

Build the jACOB™ application happyHome

[edit]   Deploy the jACOB™ application happyHome

Intention

After we did all the Design work, we want to see the result. Therefore we press the icon in the upper left screen area.

Then we log into the application and have a look at it. At this moment, we do not enter Data, since we have to create some business logic first.

Next Step

At this point you can just view the Screens, because we have some readonly required fields defined, that we have to populate first. That is done by defining Rules (Table Hooks).

[edit]   Define table hooks for happyHome

Intention

In the previous section we have built the application happy home. This application is deployable now.

The column Fullname is not editable, because we marked it as readonly. To solve this problem we will have to define so called table hooks composing the fullname by the first name and the surname of a person.

What is a table hook?

A table hook is a user-defined call-back method which is called by the jACOB™ application server while accessing the database. We can add business logic to our application by means of table hooks.

Table hooks are always assigned to a table alias.

jACOB™ offers four different table hooks to implement business logic:

beforeCommitAction

afterCommitAction

afterNewAction

afterDeleteAction

Event handler

These four table hooks are combined in an event handler. An event handler class can be generated for each table alias.

Table hook beforeCommitAction

The table hook beforeCommitAction is called by the jACOB™ application server during the save process of a data record entered into a form. This is exactly done before the database action commit is performed. We will generate an event handler and define this tableHook for our table aliases employee, landlord and interestedPerson. We will implement the composition of the fullname within these table hooks.

The table hook beforeCommitAction is also the right place for validity checks to the data record.

Table hook for table alias employee

In the table hook beforeCommitAction of the table alias employee we will first of all perform a validity check for the agent and receptionist flags. Then we will compose the fullname by the firstName and the surname. Finally we will set the personType to "internal".

This leads to the following Java code:

public void beforeCommitAction(IDataTableRecord tableRecord, IDataTransaction transaction) throws Exception
{
// Be in mind: It is not possible to modify the ’tableRecord’, if we want delete it
//
if(tableRecord.isDeleted())
return;

// enter your code here
// check agent and receptionist flags: An employee has to be either an agent or a receptionist or both
boolean isAgent =
tableRecord.getbooleanValue(Employee.agent) ;
boolean isReceptionist =
tableRecord.getbooleanValue(Employee.receptionist);

if (!isAgent && !isReceptionist)
throw new UserException(
"The employee must be an agent or a receptionist");

// compose full name
String fullname = tableRecord.getStringValue(Employee.firstname) +
" " + tableRecord.getStringValue(Employee.surname);
tableRecord.setValue(transaction, Employee.fullname, fullname);

// enforce the person to be an employee, i.e. internal flag
tableRecord.setValue(transaction, Employee.individualtype, "internal");
}

Table hooks for the table aliases landlord and interestedPerson

In the table hook beforeCommitAction of the table alias landlord we will compose the fullname and set the personType to "external".

We will define the table hook for the table alias interestedPerson in the same way.

So we will have to define the table hooks as follows:

public void beforeCommitAction(IDataTableRecord tableRecord, IDataTransaction transaction) throws Exception
{
// Be in mind: It is not possible to modify the ’tableRecord’, if we want delete it
//
if(tableRecord.isDeleted())
return;

// enter your code here
// compose full name
String fullname = tableRecord.getStringValue(InterestedPerson.firstname) +
" " + tableRecord.getStringValue(InterestedPerson.surname);
tableRecord.setValue(transaction, InterestedPerson.fullname, fullname);

// set the personType to external
tableRecord.setValue(transaction, InterestedPerson.individualtype, "external");

}

Procedure

Perform the following steps to generate the event handlers and to define the table hooks

Step Procedure
1 Select the table alias employee in the Application Outline view.
2 Choose "Show Code" from the right mouse button menu.
Hereupon, jACOB™ Designer will ask you to confirm the generation of the event handler.
After confirming jACOB™ Designer will generate the event handler class for the table alias employee and open it in the Java editor.
3 In the Java editor scroll down to the table hook beforeCommitAction and insert the code listed above.
4 Generate the event handlers and define the table hooks for the table aliases landlord and interestedPerson in the same way.
5 Save your changes to the application design. To do this click on the Save icon

in the upper left screen area to save your design and the text save icon in the upper left screen area to save your scripts.

[edit]  Define GUI hooks for happyHome

Intention

In the previous section we have added business logic to our application via table hooks. In this section we want to add more business logic to our application:

In our form realEstateObject we have the combox Sale or rent. Subject to the value selected the text fields Purchase price and Rental fee should be enabled and disabled respectively.

jACOB™ offers a mechanism to add such business logic to applications. This can be done via so called GUI hooks.

What is a GUI hook?

Similar to table hooks a GUI hook is a user-defined call-back method which is called by the jACOB™ application server. However, GUI hooks are called due to user actions at the GUI.

GUI hooks are always assigned to a GUI element.

Event handler

Like table hooks also GUI hooks are combined in an event handler. An event handler class can be generated for each GUI element.

To enable the behavior of the combox Sale or rent and the related textfields Purchase price and Rental fee described above we will have to generate an eventhandler and define a GUI hook for each of these GUI elements.

GUI hook onSelect

For the combox Sale or rent we will have to define the GUI hook onSelect. The GUI hook onSelect is called during updating a record when the user changes the selection in the combobox.

We will have to implement the following Java code:

public void onSelect(IClientContext context, IComboBox emitter) throws Exception
{
// get selected entry from combobox
String saleOrRent = emitter.getValue();

// get gui elements we want to enable/disable
IGuiElement realEstateObjectPurchasePrice = context.getGroup().findByName("realEstateObjectPurchasePrice");
IGuiElement realEstateObjectRentalFee = context.getGroup().findByName("realEstateObjectRentalFee");

// enable purchasePrice if saleOrRent mode is "sale"
// or "saleOrRent"
// note: saleOrRent might be null!
realEstateObjectPurchasePrice.setEnable(RealEstateObject.saleOrRent_ENUM._sale.equals(saleOrRent)
| RealEstateObject.saleOrRent_ENUM._saleOrRent.equals(saleOrRent));

// enable rentalFee if saleOrRent mode is "rent"
// or "saleOrRent"
// note: saleOrRent might be null!
realEstateObjectRentalFee.setEnable(RealEstateObject.saleOrRent_ENUM._rent.equals(saleOrRent)
| RealEstateObject.saleOrRent_ENUM._saleOrRent.equals(saleOrRent));
}

GUI hook onGroupStatusChanged

However, for the text fields Purchase price and Rental fee we will have to define the GUI hook onGroupStatusChanged. This GUI hook is called after the status of the group the GUI element is contained has changed. The status of a group changes due to user actions, e.g. pressing the New button or Change button.

For further explanations of onGroupStatusChanged please refer to the jACOB™ API documentation.

GUI hook for Purchase price

For the textfield Purchase price we will define this GUI hook as follows:

public void onGroupStatusChanged(IClientContext context, GroupState status, IGuiElement emitter) throws Exception
{
if (status == IGuiElement.NEW | status == IGuiElement.UPDATE)
{
// fetch saleOrRent mode from record to be edited
String saleOrRent = context.getSelectedRecord().getStringValue(RealEstateObject.saleorrent);

// enable if saleOrRent mode is "sale"
// or "saleOrRent"
// note: saleOrRent might be null!
emitter.setEnable(RealEstateObject.saleOrRent_ENUM._sale.equals(saleOrRent)
| RealEstateObject.saleOrRent_ENUM._saleOrRent.equals(saleOrRent));
}
else
{
emitter.setEnable(status == IGuiElement.SEARCH);
}

}

GUI hook for Rental fee

Perform the following steps to generate the event handlers and to define the GUI hooks:

public void onGroupStatusChanged(IClientContext context, GroupState status, IGuiElement emitter) throws Exception
{
if (status == IGuiElement.NEW |
status == IGuiElement.UPDATE)
{
// fetch saleOrRent mode from record to be edited
String saleOrRent = context.getSelectedRecord().getStringValue(RealEstateObject.saleorrent);

// enable if saleOrRent mode is "sale"
// or "saleOrRent"
// note: saleOrRent might be null!
emitter.setEnable(RealEstateObject.saleOrRent_ENUM._rent.equals(saleOrRent)
| RealEstateObject.saleOrRent_ENUM._saleOrRent.equals(saleOrRent));
}
else
{
emitter.setEnable(status == IGuiElement.SEARCH);
}
}

Procedure

Perform the following steps to generate the event handlers and to define the GUI hooks:

Step Procedure
1 Open the form realEstateObject in the form editor.
2 Create the event handler for the combobox Sale or rent.
To do this, select the combobox and choose Edit event handler from the right mouse button menu.
Hereupon, jACOB™ Designer will ask you to confirm the generation of the event handler.
After confirming jACOB™ Designer will generate and open the event handler class in the Java editor.
3 In the Java editor scroll down to the GUI hook onSelect and replace the code with the code listed above.
4 Generate the event handlers and define the GUI hooks onGroupStatusChanged for the text fields Purchase price and Rental fee in the same way.
5 Save your changes to the application design. To do this click on the Save icon

in the upper left screen area to save your design and the text save icon in the upper left screen area to save your scripts.

Impact on form

The jACOB™ Designer adds the decoration to all GUI elements where an event handler class has been generated.

Next Step

The next step will be to:

Change the Usermanagement of HappyHome.

[edit]  Change the user management of happyHome

Intention

WE deliver an empty jACOBTM Application with a pre-configured user management. Also we create on first startup a user "admin" with an empty password. In a real Project, you would change the user management to your needs. In the case of happy Home, you maybe would have adapted it to authenticate against the table "individual". In this example we wanted to keep it easy and just change the existing user management and add some roles to it.

User roles

Our current data model has two types of employees: agents and receptionists. Each of these employee types is assigned to a decisive role. Their role is reflected in the domains we have previously defined:

  • Agent:

The role of an agent is to register real estate objects and follow up customer requests. Therefore agents should only have access to the domain Agent.

  • Receptionist:

    Receptionists have the role to register customer requests. Thus, receptionists should only have access to the domain Registration.

Therefore we will have to do the following:

extend our table person by two columns. The column agent will indicate whether an employee is an Agent; The column receptionist will indicate whether an employee is a Receptionist;

User role administrator

We want to extend this data model by another employee type/role:

  • Administrator:

The role of an administrator is to administrate employees, i.e. agents, receptionists and also administrators. In doing so he/she can assign one or more user roles to an employee. Hence, administrators should only have access to the domain Administration.

Therefore we will have to do the following:

  • extend our table person by another column. The column administrator will indicate whether an employee is an administrator;
  • add checkboxes Administrator , Agent and receptionist to the form user;
  • add a table hook beforeCommitAction of the table alias
  • define the three user roles and assign them to the appropriate domains.

New structure of the table person

The outcome of this is that the table person will have the following new structure:

Table 2.4. Table person for change ot the user management

New layout of the form employee

Consequently the new layout of the form user will be as illustrated below.

Figure 2.18. The form employee enabling user management

Table hook beforeCommitAction

The table hook beforeCommitAction of the table alias person will be implemented as follows:

public void beforeCommitAction(IDataTableRecord tableRecord, IDataTransaction transaction) throws Exception
{
// Be in mind: It is not possible to modify the ’tableRecord’, if we want
// delete it
//
if (tableRecord.isDeleted())
return;

// check agent, receptionist and administrator flags
boolean isAgent = tableRecord.getbooleanValue(Person.agent);
boolean isReceptionist = tableRecord.getbooleanValue(Person.receptionist);
boolean isAdministrator = tableRecord.getbooleanValue(Person.administrator);

if (!isAgent && !isReceptionist && !isAdministrator)
throw new UserException("The employee must be an agent, receptionist or admin");
}

User and Role

The implementation of a dedicated user management implies an appropriate implementation of the jACOB™ class User and of the jACOB™ class UserFactory. Therefore we have to implement additional code to these two classes. Refer to the jACOB™ API documentation for further details.

The files "User.java" and "role.java" can be found in the project directory of happyHome under "./java/jacob/security". For simplicity reasons the following listing presents only code fragments.

In role.java we will add our additional roles

public class Role extends AbstractRole
{
static public final transient String RCS_ID = "$Id: Role.java,v 1.1 2006/10/11 11:35:52 herz Exp $";
static public final transient String RCS_REV = "$Revision: 1.1 $";

public static final Role ADMIN = new Role("admin");
public static final Role USER = new Role("user");
public static final Role AGENT = new Role("agent");
public static final Role RECEPTIONIST = new Role("receptionist");


private Role(String roleName)
{
super(roleName);
}
}

The constructor of the class User will be extended in the way that the user’s role(s) are retrieved from the columns agent, receptionist and administrator of the table person:

protected User(UserFactory factory, IDataTableRecord userRecord) throws GeneralSecurityException
{
this.factory = factory;
try
{
// set user attributes
//
this.key = userRecord.getStringValue(Person.pkey);
this.fullName = userRecord.getStringValue(Person.fullname);
this.loginId = userRecord.getStringValue(Person.loginname);
this.email = this.loginId;
this.password = userRecord.getStringValue(Person.password);

// determine user roles
//

if (loginId.equals(UserFactory.ADMIN_USER_ID) |userRecord.getbooleanValue(Person.administrator))
{
this.roles.add(Role.ADMIN);
this.mandatorId=null;
}
else
{
this.mandatorId=loginId;
}
if (userRecord.getbooleanValue(Person.agent))
{
this.roles.add(Role.AGENT);
}
if (userRecord.getbooleanValue(Person.receptionist))
{
this.roles.add(Role.RECEPTIONIST);
}
}
catch (Exception e)
{
throw new GeneralSecurityException(e.toString());
}
}

Procedure

Perform the following steps to add the user management defined above to the application:

Step Procedure
1 Extend the table person by the columns agent, receptionist and administrator as stated above.
2 Add the checkbox fields agent, receptionist and administrator to the form user.
3 Extend the table hook beforeCommitAction of the table alias person as listed above.
4 Create the role agent.
To do this select the folder User roles in the Application Outline view and choose New user role from the right mouse button menu.
Enter the name "agent" into the dialog window and confirm.
Hereupon, jACOB™ Designer will create the user role agent in the folder User roles.
5 Assign the user role of agents to the Domain "agent".
Therefor open the domain agent in the Domain editor by double clicking on the domain.
In the Domain editor tag the role agent.

6 Create and define the user roles receptionist and administrator in the same way.
7 Save your changes to the application design. To do this click on the Save icon

in the upper left screen area.

8 Implement the code of the Java classes User and Role as listed above.
The files "User.java" and "Role.java" can be found in the project directory of happyHome under "./java/jacob/security".
9 Save your changes to the application design. To do this click on the Save icon

in the upper left screen area to save your design and the text save icon in the upper left screen area to save your scripts.

Impact

Now we have changed the user management to our application happyHome. The users will have to authenticate against the application and will only be able to perform the actions associated with the user role(s).

The jACOB™ Designer decorates all domains assigned to at least one user role with a lock symbol:

Figure 2.19. Domains assigned to user roles

[edit] Final Check

Now we are in the position to test our application. Therefore we deploy our final Version by pressing the icon within the jACOB Designer.

After that we login to our Application and test the features that we have implemented:

Enter different types of individuals

Enter users with different roles

Login and –out as different users

Create RealEstateProjects and check the gui-scripts

…

Retrieved from "http://www.tarragon-software.com/wiki/index.php?title=JACOBDesignerTutorial"
Personal tools
jACOB Documentation
jACOB Administration
jACOB Application