JACOBDataModeling
From JACOBWiki
Contents |
Title page
jACOB™ Designer
Data modeling
Manual
[edit] Introduction
Intention
To design a jACOB™ Application needs basically three Steps:
1. Design the data model
2. Design the user interface
3. Write the business logic
This manual describes how to define the Data model in jACOB™ Designer and how to put the data based business logic to it.
[edit] Prerequisites
See the section "Installation" in the jACOB Wiki for the prerequisites.
After you have installed jACOB™ , create an empty jACOB™ application and call it "catalogue".
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™ – Blank project and continue by pressing the Next > button.
Figure 2.1. jACOB™ project structure
6. Then you will be prompted to enter a Project name.
Enter "catalogue" into the text field and confirm by pressing the button Finish.
Impact
Hereafter, the jACOB™ wizard will create the empty project "jacob.catalogue".
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 catalogue. 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 outline
[edit] Defining the data model
Data model
The base of a jACOB™ application design is the data model. The data model itself consists of:
- tables,
- table aliases,
- relations and relation sets,
- browsers and
- table hooks.
Creation of a data model
The creation of such a data model will be explained in the following sections:
- Defining tables
- Defining table aliases
- Defining relation sets
- Defining browsers
- Defining table hooks
[edit] Defining tables
Purpose
Tables contain the actual physical data. In order that a jACOB™ application can access these data the structures of the tables has to be known by the application. Therefore, the table structures have to be defined in the application design of the jACOB™ application.
Editor
Table structures are defined with the aid of the table editor. The table structure is spread over three different tabs:
- Common,
- Fields and
- Keys
Common table properties
Figure 2.4. Common properties of a table
The tab Common comprises the common properties of a table such as:
- the Table name within the jACOB™ application design;
- the Physical table name within the data source;
- a short Description of the table;
- eventually a Representative field denoting a record of the table in a human understandable manner and
- eventually a longtext History field recording the modifications on fields with an activated history flag.
Table fields
The table’s fields are listed on the tab Fields. A detailed description of this tab can be found in the section Defining table fields.
Keys and indexes
Keys and indexes defined on the table are listed on the tab Keys. A detailed description of this tab can be found in the section Defining keys and indexes.
Procedure
Proceed the following steps:
| Step | Procedure |
| 1 | Select the data source containing the table to be defined in the Application Outline view. Figure 2.5. Selecting the datasource  |
| 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 the table name into the text field and confirm your input. Hereafter, jACOB™ designer will create a table object within the data source and open the table editor in the right upper screen area. |
| 4 | Define the common properties of the table within the table editor’s Common tab. |
| 5 | Add the fields of the table as explained in Defining table fields. |
| 6 | Define the table’s keys and indexes as described in Defining keys and indexes. |
| 7 | Save your changes to the application design. To do this click on the Save icon
 in the upper left screen area. |
Impacts
The jACOB™ designer automatically creates for each new table one table alias and a browser containing the field pkey, which is the primary key of the table.
[edit] Defining table fields
Purpose
Tables consist of single fields reflecting the structure of the table. This section explains how you can add and define fields to an existing table.
Editor
Table fields are defined with the aid of the table editor’s Fields tab:
Figure 2.6. Fields of a table
The tab Common comprises the common properties of a table such as:
- the Table name within the jACOB™ application design;
- the Physical table name within the data source;
- a short Description of the table;
- eventually a Representative field denoting a record of the table in a human understandable manner and
- eventually a longtext History field recording the modifications on fields with an activated history flag.
Table fields
The table’s fields are listed on the tab Fields. A detailed description of this tab can be found in the section Defining table fields.
Keys and indexes
Keys and indexes defined on the table are listed on the tab Keys. A detailed description of this tab can be found in the section Defining keys and indexes.
Procedure
Proceed the following steps:
| Step | Procedure |
| 1 | Select the data source containing the table to be defined 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 the table name into the text field and confirm your input. Hereafter, jACOB™ designer will create a table object within the data source and open the table editor in the right upper screen area. |
| 4 | Define the common properties of the table within the table editor’s Common tab. |
| 5 | Add the fields of the table as explained in Defining table fields. |
| 6 | Define the table’s keys and indexes as described in Defining keys and indexes. |
| 7 | Save your changes to the application design. To do this click on the Save icon
 in the upper left screen area. |
Impact
For each new table the jACOB™ designer automatically creates one table alias and one browser containing the field pkey.
[edit] Defining table fields
Purpose
Tables consist of single fields reflecting the structure of the table. This section explains how you can add and define fields to an existing
Editor
Table fields are defined with the aid of the table editor’s Fields tab:
Figure 2.2. Fields of a table
The table’s fields or columns are listed in the listbox Field list in the tab’s left area. The tab’s right area displays the selected field’s Common details and field type specific details.
Common field details
The Common details are:
- the Field name within the jACOB™ application design;
- the Column name within the physical data source;
- the Label used for the field in forms;
- whether the History of the field is recorded;
- whether the field is Readonly and Required and
- the Type of the field.
Field type specific details
The field type specific details depend on the Type defined for the field. The field type specific details will be explained in the following sections:
- Defining text and longtext fields
- Defining integer and long fields
- Defining float and double fields
- Defining decimal fields
- Defining decimal fields
- Defining date, time and timestamp fields
- Defining binary and document fields
Procedure
Proceed the following steps to add a field to a table:
| Step | Procedure |
| 1 | Select the table concerned in the Application Outline view. |
| 2 | Select the tab Fields in the table editor. The jACOB™ designer has initially created the field "pkey" containing the primary key of the table. |
| 3 | Add the table fields by pressing the button Add. Define the field’s Common details. Define the field’s type specific details as explained in the next sections. |
| 4 | Save your changes to the application design. To do this click on the Save icon
 in the upper left screen area. |
[edit] Defining text and longtext fields
Purpose
Table fields of the type TEXT are compared to fields of the type LONGTEXT limited in their length. However, it is possible to search for strings in text fields but not in longtext fields.
Type specific field details
- the Search mode has to be defined;
- the Max length of the text has to be specified;
- enabling the Fix length check box implicates that the text field will be set up as CHAR field in a relational data base instead as VARCHAR field and
- activating the Case sensitive check box enables a case sensitive search.
Search mode
The search mode defines how character strings are searched in a text field during a query. The search mode can be:
- unbound, i.e. it will be searched for entries containing the search string in the appropriate text field;
- leftbound, i.e. it will be searched for entries beginning with the search string;
- rightbound, i.e. it will be searched for entries ending with the search string.
[edit] Defining integer long and boolean fields
Purpose
Table fields of the type INTEGER or LONG are both used to save whole numbers.
Type specific field details
Boolean fields
[edit] Defining float and double fields
Purpose
Table fields of type FLOAT or DOUBLE are used to save floating-point numbers.
Type specific field details
Figure 2.5. Float field details
For float and double fields it is necessary to specify the following field details:
- a Default value can be declared and
- by setting the Min value and Max value you can create ranges.
[edit] Defining decimal fields
Purpose
Table fields of the type DECIMAL are used to save real numbers with a fixed number of decimal places.
Type specific field details
Figure 2.6. Decimal field details
For decimal fields it is necessary to specify the following field details:
- the scale attribute defines the number of decimal places;
- a Default value can be declared and
- by setting the Min value and Max value you can create ranges.
[edit] Defining enum fields
Purpose
Table fields of the type ENUM are used to limit the number of permitted values to a predefined set of values, e.g. a set of colors, person types, article types etc..
Type specific field details
Figure 2.7. Enum field details
For enum fields you can specify the following field details:
- a default value for the enum field by selecting a value from the Default combo box and
- all permitted values have to be entered into the multiline text field Enum values separated from each other by carriage return-line feed.
[edit] Defining date, time and timestamp fields
Purpose
Table fields of the type DATE, TIME or TIMESTAMP are used to save data in a data and time format.
Type specific field details
Figure 2.7. Timestamp field details
Date fields and time fields have no type specific details. Country specific data and time formats are not defined here, but are retrieved from the internationalization properties configured for the jACOB™ application server.
For timestamp fields you can specify the following field details:
- the Resolution and
- with the aid of the Initialize with now checkbox you can initialize the timestamp field of a new record with the current date and time.
Resolution
The resolution of the timestamp can be specified via the Resolution parameter. It can be set to:
- Milliseconds,
- Seconds or
- Minutes.
[edit] Defining binary and document fields
Purpose
Fields of the type BINARY are used to save raw data in a binary format such as measurement readings, statistical values, etc.. In comparison to text fields binary fields may contain any kind of character even non presentable characters. However, this means that the content of binary fields cannot be directly presented at the GUI.
Fields of the type DOCUMENT are used to save any kind of documents or pictures. In comparison to binary fields the content of document fields can be directly presented at the GUI with the aid of the appropriate GUI elements.
Type specific field details
Neither binary fields nor document fields require the declaration of type specific details.
[edit] Defining keys and indexes
Purpose
Keys are required to uniquely identify data records in tables and to realize relations between tables.
Indexes allow a quick access to data tables and can enforce uniqueness on the rows in a table.
Editor
Keys and indexes on fields can be defined with the aid of the Keys tab:
Figure 2.9. Keys and indexes of a table
The table’s fields keys and indexes are listed in the listbox Keys list in the tab’s left area. The tab’s right area displays the selected key’s or index Key details.
The jACOB™ designer distinguishes between the following keys and indexes:
- primary keys,
- foreign keys,
- unique indexes and
- ordinary indexes.
Procedure
Proceed the following steps to add a keys and indexes to a table:
| Step | Procedure |
| 1 | Select the table concerned in the Application Outline view. |
| 2 | Select the tab Keys in the table editor. |
| 3 | Press the appropriate Add button. |
| 4 | Specify the Name of the key or index and select the appropriate fields via the Add... button. |
| 5 | Save your changes to the application design. To do this click on the Save icon
 in the upper left screen area. |
[edit] Defining table aliases
Purpose
Data with a similar data structure can be combined in one table. Table aliases make it possible to efficiently access single subsets fulfilling a dedicated condition. Table aliases have to be defined in the application design of the jACOB™ application.
Editor
Table aliases are defined with the aid of the table alias editor:
Figure 2.10. Table alias editor
The editor comprises the common properties of a table alias such as:
- the name of the Parent table assigned to the table alias;
- the Alias name itself;
- the Condition in SQL syntax specifying the subset of the parent table (the bulb indicates, that you get auto completion with the correct field names) and
- a commentarial Description of the table alias.
Automatically created table aliases
The jACOB™ designer automatically creates for each new table one simple table alias. These table aliases are named with the name of the appropriate table and are unconditional.
Procedure
There are two entry points for the creation of a table alias. A new table alias can be created via the parent table or via the Table aliases folder in the Application Outline view. The following procedure describes the first alternative:
| Step | Procedure |
| 1 | Select the parent table in the Application Outline view. |
| 2 | Select the menu item New table alias from the right mouse button menu. After this a dialog window will pop up asking you to specify the name of the table alias. |
| 3 | Specify a name for the new table alias and confirm your input. Hereafter, jACOB™ designer will create a table alias object within the Table aliases folder and open the table alias editor in the right upper screen area. |
| 4 | Define the common properties of the table alias. |
| 5 | Save your changes to the application design. To do this click on the Save icon
 in the upper left screen area. |
[edit] Defining relation sets
Purpose
Table aliases of one data model are normally standing in some kind of relation to each other. The single relations form one or more relation sets.
A relation set can be graphically presented as a cohesive graph where the table aliases are diagrammed as nodes and the relations as connecting lines.
Relation sets have to be defined in the application design of the jACOB™ application.
Editor
Relation sets are defined with the aid of the relation set editor:
Figure 2.11. Relation set editor
The editor primarily consists of a toolbar and a workspace. With the aid of the toolbar you can construct your relation set diagram:
- Table alias
The table aliases of the relation set are added per drag & drop to the diagram.
- Relation
Relations between two table aliases can be created with the aid of the button Relation.
- Annotation
The button Annotation lets you add annotation text to your relation set diagram.
- Select and Marquee
With the aid of the button Select you can select single objects of your diagram. The Marquee button lets you select whole areas in your diagram.
Relations via foreign keys
jACOB™ designer supports the following relation types:
- zero-to-many relations and
- one-to-many relations.
jACOB™ designer realizes a relation by the creation of a foreign key in the parent 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.
Procedure
Proceed the following steps to create a new relation set diagram:
| Step | Procedure |
| 1 | Select the folder Relation sets in the Application Outline view. |
| 2 | Create the new relation set by selecting New relation set from the right mouse button menu of Relation sets. Specify a name for your relation set and confirm. Hereupon, jACOB™ Designer creates the new relation set and opens the Relation sets editor. |
| 3 | Add the table aliases to your relation set diagram. Therefore, select the appropriate table alias in the Application Outline view. Drag the table alias to the workspace of the Relation sets editor and drop it. |
| 4 | Add the zero-to-many relations to your diagram. To do this, click first on the toolbar button Relation. Hereafter draw the relation by clicking first on table alias representing the many-side of the relation and then on the table alias representing the zero-side of the relation. If you create a second relation between two tables via different table aliases, jACOB™ designer will ask you to select a foreign key from a listbox or to create a new foreign key respectively. |
| 5 | Add the one-to-many relations to your diagram. To do this, click first on the toolbar button Relation. After this draw the relation by clicking first on the table alias representing the many-side of the relation and then on the table alias representing the one-side of the relation. jACOB™ Designer initially creates a zero-to-many relation. You will have to transform this relation to a one-to-many relation. Therefore, click first on the toolbar button Select and select the relation. Then choose One to many from the right mouse button menu. |
| 6 | Add optional annotations to your diagram. Therefore, click first on the toolbar button Annotation. After this click in the diagram at the position you want to have your annotation text. jACOB™ Designer will create a field letting you enter your comment. |
| 7 | Save your changes to the application design. To do this click on the Save icon
 in the upper left screen area. |
Impacts
As already stated above, jACOB™ Designer also automatically creates for each relation a foreign key and a foreign key column in the appropriate table.
[edit] Defining browsers
Purpose
Browsers list data records in a tabular form. The browser definition determines which table columns are displayed in which order. Thus browsers represent particular views on a table/table alias.
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.
You can define more than one browsers on one table alias. Thus you can create different views on one table alias for e.g. different forms.
Local and foreign columns
A browser can show local columns and foreign columns.
Local columns are columns of the anchor table alias, i.e. the table alias assigned to the browser.
Foreign columns are columns of a foreign table alias related to the anchor table alias.
Editor
Browsers are defined with the aid of the browser editor:
Figure 2.12. Browser editor
The editor lists the columns displayed by the browser in the listbox Column list in the editor’s left area.
By the aid of the GUI buttons in the middle area you can add and remove columns from the browser or change the order in which the columns will be displayed.
The editor’s right area shows the attributes of the column selected in the listbox. The attributes of local columns differ from the attributes of foreign columns. The column type specific attributes will be explained in the following sections:
- Defining local columns
- Defining foreign columns
Procedure
There are two entry points for the creation of a browser. A new browser can be created via the anchor table alias or via the Browsers folder in the Application Outline view. The following procedure describes the first alternative:
| Step | Procedure |
| 1 | Select the anchor table alias in the Application Outline view. |
| 2 | Create the new browser by selecting New browser from the right mouse button menu of the table alias. Specify a name for your browser and confirm. Hereupon, jACOB™ Designer creates the browser and opens the Browser editor. |
| 3 | Add the to be displayed local columns from the anchor table alias to the Column list. Therefor, press the button Add column and select a column from the dialog window. Specify the attributes as explained in Defining local columns |
| 4 | Add the to be displayed foreign columns from the foreign table alias to the Column list. Therefor, press the button Add table and select the foreign table containing the column to be displayed. Specify the attributes as explained in Defining foreign columns |
| 5 | Bring the columns into the order you want them displayed. Therefor select the appropriate column and use the buttons Up and Down to move it’s position within the listbox Column list. |
| 6 | Save your changes to the application design. To do this click on the Save icon
 in the upper left screen area. |
[edit] Defining local columns
Purpose
Local columns of a browser show fields of the anchor table.
Attributes of local columns
Figure 2.13. Local column attributes
For local columns you have to define the following attributes:
- the unique Name of the browser column,
- the Label of the browser column displayed in the browsers and
- the name of the anchor table’s Column.
[edit] Defining foreign columns
Purpose
Foreign columns of a browser show fields of a foreign table related to the anchor table alias.
For foreign columns you have to define the following attributes:
- the unique Name of the browser column;
- the Label of the browser column displayed in the browsers;
- the name of the Foreign table alias and the Display column and
- if the browser definition is used by a changeable inform browser, you will have to define the Browser to use, the Fill direction and the Relation set to use.
Fill direction
If you select a record from a browser, you can define how the backfill mechanism works.
Forward : The records that the selected record references will be displayed
Bacward: The records that the selected record is referenced by will be displayed
Both: all the referenced and referencing records are backfilled
Relation set to use
The Relation set to use determines which GUI elements would be updated, if a data set has been selected in an inform browser assigned to this browser definition.
The combo box Relation set to use lets you choose between:
- local, the system searches just the local table without any foreign constraints
- default, all existing relations (foreign constraints) are used for the search
- relation sets referencing the Foreign table alias, just the relations within that set are used.
[edit] Defining table hooks
Purpose
Table hooks contain the data specific business logic of a jACOB™ application.
Table hooks are user-defined call-back methods which are called by the jACOB™ application server while accessing the database.
They are tied to table aliases and thereby "hook" data specific business logic to table aliases.
Event handler
The table hooks of a table alias are combined in an event handler. An event handler class can be generated for each table alias.
Each generated event handler class contains the following four table hook methods:
- beforeCommitAction
- afterCommitAction
- afterNewAction
- afterDeleteAction
Initially these methods are empty. The paragraphs following will briefly present these table hook methods. For a full description please refer to the jACOB™ API documentation.
beforeCommitAction
The table hook method 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.
This method is the right place for validity checks and assigning default values to the data record.
E.g. for an order event handler you can implement the beforeCommitAction hook method so that the order status is calculated and set.
afterCommitAction
The table hook method afterCommitAction is called by the jACOB™ application server immediately after it has performed a commit on a data record.
This hook method can be used to carry out further actions that should be only performed after a successful commit.
E.g. for an order event handler you can implement the afterCommitAction hook method so that an order confirmation is sent to the customer.
afterNewAction
The table hook method afterNewAction is called by the jACOB™ application server immedialtely after a new data record has been created and initialized.
This hook method is the right place to perform further application specific initializations before the new data record will be displayed at the GUI.
E.g. for an order event handler you can implement the afterNewAction method in the way that the order’s receptionist field is initialized with the id of the person registering the order.
afterDeleteAction
The table hook method afterDeleteAction is called by the jACOB™ application server immediately after a delete operation has been invoked on a data record.
This hook method is the right place to carry out further application specific clear up actions.
E.g. for an order event handler you can implement the afterDeleteAction method in the way that all positions of the order are deleted.
Editor
The event handler class containing the table hook methods can be edited with the aid of the Java editor:
Figure 2.15. Event handler class in the Java editor
Procedure
Perform the following steps to generate an event handler for a table alias:
| Step | Procedure |
| 1 | Select the table alias in the Application Outline view. |
| 2 | Choose show code from the right mouse button menu. Hereupon, jACOB™ Designer asks whether it should create an event handler for the table alias (or opens an already existing one). |
| 3 | Confirm with OK. Thereafter, jACOB™ Designer generates the event handler class and opens it in the Java editor. |
| 4 | Implement your data specific business logic in the table hook methods given. |
