Lesson 3: Set up the projects and use the EGL SQL retrieve feature

Before you write your logic, create two EGL projects, as well as a Record part that is based on the database table.

About this task

An EGL application is organized in one or more projects, each of which is a physical folder in the workspace. A project contains an EGL source folder that is provided for you, and that folder contains one or more packages, which in turn contain EGL source files. This hierarchy is basic to your work in EGL: a project, then an EGL source folder, then a package with EGL source files.

The EGL source files include EGL parts, which are type definitions that you create. For example, a Service part contains logic, and a Record part can be the basis of a variable that you declare in your Service part.

Packages are important because they separate parts into different contexts, or namespaces:

A part name might be duplicated in two different packages, and any EGL source code can reference each part precisely. The main benefit of namespaces is that different teams can develop different EGL parts without causing name collisions.
Each part name in a given package is unique within that package:
- A part in one package can easily reference another part in the same package by specifying the part name. For example, here is a declaration of a record that is based on the Record part MyRecordPart:
```
myRecord MyRecordPart{};
```
- A part in one package can also reference a part in a second package by giving the package name and part name, or by a shortcut that involves importing the part.

One project can reference the parts in a second project, but only if the EGL build path of the referencing project identifies the referenced project. Again, this tutorial gives examples. However, in all cases, avoid using the same package name in different projects, as that usage can cause problems in name resolution.

Your next task in this tutorial is to create the following projects:

PaymentService: Holds an EGL Service part and related definitions
PaymentClient: Holds the Rich UI handlers and related definitions

You can include all your code in a single project, but the separation shown here lets you easily deploy the two kinds of code in different ways.

Parts in one project can use parts in a different project. EGL uses a build path to search for unresolved references. Later in this lesson, you will add the PaymentService project to the build path for the PaymentClient project.

Create the PaymentService project

Procedure

To create an EGL project to contain the service:

Change back to the EGL perspective by clicking the EGL button in the upper right of the workbench.
Click File > New > EGL Project, or click the New EGL Project icon on the menu bar.
In the New EGL Project window, enter the following information:
1. In the Project name field, type the following name:
```
PaymentService
```
2. In the EGL project types section, click General Project.
3. Click Next.
In the second EGL Project window, the defaults that EGL provides should be correct. Verify the following information:
1. The Target runtime platform is Java™.
  This setting indicates that EGL generates Java™ source code from your EGL Service part.
2. Under Build descriptor options, the Create a build descriptor radio button is selected. Build descriptors control the generation process. Because you are creating a separate project for your service, you can use the default build descriptor that EGL creates for you.
Click Finish.

Results

EGL creates a project named PaymentService. Note the folders inside the directory:

EGLSource: Put your packages and source files here.
EGLGen/JavaSource: EGL places the Java™ files it generates here.
JavaSource: Put any custom Java™ source files here. These files are not overwritten during the generation process.
JRE System Library: EGL uses this folder for JAR files that support the Java™ Runtime Environment.

The Project Explorer view shows the new project and folders.

Create the PaymentClient project

About this task

An EGL Rich UI project includes many shortcuts to speed the development of a user interface for the web.

Procedure

To create an EGL Rich UI project:

Click the New EGL Project icon on the menu bar.
In the EGL Project window, enter the following information:
1. In the Project name field, type the following name:
```
PaymentClient
```
2. Under EGL project types, click Rich UI Project.
3. Click Next.
In the second EGL Project window, the defaults that EGL provides should be correct. Verify the following information:
1. Use the default location for the project is selected.
2. The Widget libraries list contains the following projects:
  - EGL Rich UI widgets
  - EGL Dojo widgets
3. In the EGL project features group, Create an EGL deployment descriptor is selected.
Click Next.
On the build settings page, select PaymentService.

The PaymentService project is added to the build path for the project being created so that the Rich UI handler can use parts that are defined in PaymentService.
Click Finish.

Results

EGL creates a project named PaymentClient and adds support projects to the workspace for Rich UI, Dojo Widgets, and the Dojo runtime library. In addition to the directories that EGL created for the General project, a Rich UI project includes the following directory:

WebContent: Contains support files, such as cascading style sheets (CSS) and images.

When you first add a Rich UI project to your workspace, three other projects are added automatically:

com.ibm.egl.rui
com.ibm.egl.rui.dojo.runtime.local
com.ibm.egl.rui.dojo.widgets

These three projects contain widgets and other support files that you use in creating a Rich UI application.

Edit the build descriptor for the PaymentService project

About this task

The EGL build file has the extension .eglbld and contains build parts, which are XML definitions that are inputs for the EGL generator.

A build file typically includes multiple build descriptors so that you can generate EGL code in multiple ways. For example, EGL created the following build descriptors in the PaymentService.eglbld file:

PaymentServiceJavaBuildOptions
PaymentServiceDebugBuildOptions

You must change the build descriptors for the project so that the logic you write there can access a database.

To edit the build descriptor:

Procedure

In the PaymentService project, expand the EGLSource folder. Double-click the PaymentService.eglbld file.
The Build Parts editor opens.
In the Load DB options using Connection field, click the down arrow and select the Derby Database Connection.
Find the Outline view, located by default in the lower left corner of the workbench. The PaymentServiceJavaBuildOptions build descriptor should currently be highlighted. Double-click PaymentServiceDebugBuildOptions and repeat step 2 for the other build descriptor, which is used by the EGL debugger.
Save and close the build descriptor file.

Results

Use the EGL SQL retrieve feature to create a Record part

You can automatically retrieve the fields for a Record part that corresponds to the PAYMENT table in the PaymentDB database. The column names are the basis of the field names in the Record part.

About this task

Procedure

Change preferences for the SQL retrieve feature:
1. From the top menu in the workbench, click Window > Preferences > EGL > SQL.
2. In the third group of options, Case control rules for naming structure items, select Change to lower case and capitalize first letter after underscore.
  Field names will be in mixed case.
3. In the fourth group of options, Underscore control rules for naming structure items, select Remove underscores.
  Field names will not include the underscores in column names.
4. In the last group of options, make sure that Retrieve primary key information from the system catalog is selected.
  One or more fields in the Record part will correspond to key fields in the SQL table, as is useful when you rely on default EGL SQL processing.
5. Clear Prompt for SQL user ID and password when needed.
  You prevent a dialog window from opening each time you access the database.
6. Click OK.
In the Project Explorer view, right-click PaymentService and then click New > Record
In the New EGL Source Record window, enter the following information:
1. In the EGL source file name field, enter the following name:
```
ServiceRecords
```
  EGL adds the .egl file extension automatically.
2. In the Package field, enter the following name:
```
records
```
3. Click Finish.
EGL creates the records directory and the ServiceRecords.egl file and then opens the file in the EGL editor.
Replace the contents of the file by copying and pasting the following code:
```
package records;

record paymentRec type SQLRecord {tableNames = [["PAYMENT"]]}

end
```
Note:
1. Your use of a Record part that is labeled with SQLRecord means that, in the following case, the EGL generator will create code that is appropriate for SQL I/O:
  
  You code an I/O statement such as add, as in this example:
  add mySQLRecord;
  
  The record on which the I/O statement operates (in the example, mySQLRecord) is an SQL record; that is, the record is based on a Record part that is labeled with SQLRecord.
2. The SQL Record part uses several properties such as tableNames, in most cases to change the output of the EGL generator and in this way to change runtime behavior.
3. Table names are specified as two-dimensional arrays because you might have reason to specify a table label (an SQL alias), which is useful when you write custom SQL statements. Here is a tableNames property setting that includes a table label:
  tableNames=[["PAYMENT", "A"]]
4. You can avoid setting the tableNames property if you are creating a Record part that corresponds to a single database table and if that Record part has the same name as the database table. In this tutorial, the Record part has a different name, and the tableNames property is required.
Right-click anywhere in the Record statement and click SQL record > Retrieve SQL.
EGL automatically creates fields for the Record part in accordance with information that is provided by the database management system. You specified little more than the table name, and here is the result:
Change the type for amount from decimal(10,2) to money.
The change provides additional options when you drag-and-drop the Record part from the EGL data view to the Rich UI Design surface, as shown later.
Change the type for fixedPayment to boolean.
Again, the change is useful during a later drag-and-drop operation.
Save (Ctrl-S) and close the ServiceRecords.egl file.

Lesson checkpoint

About this task

In this lesson, you completed the following tasks:

Created an EGL project for developing a data-access service.
Created an EGL project for developing a Rich UI application.
Modified the build descriptors in a build file; specifically, by adding database information from a connection definition in the workbench.
Set preferences for the EGL SQL retrieve feature.
Created a Record part, retrieving most information from a database.

In the next lesson, you develop some of the Rich UI application and view your prototype code in action.