GS_03_Create_first_working_app - XLRIT/gears GitHub Wiki

You are going to develop a small web shop application in where users can buy products. So the required end result in this case would be an "ordered product". You will do the developing and I will explain.

1. Table of content

2. Specifiy a required result a process will produce

Let's start by creating a file in where you will specify the required end result.

  1. In the folder specs create a files called Order product.sn and fill it with the following content:
process 'Order product'

results in:
    "customer has ordered a product"

"customer has ordered a product" =
    one ORDER in ORDERS is created with:
        product_name = input from CUSTOMER
        quantity     = 1

Let's explain the different lines and what the effect of each line will have in the application you are developing:

Line Explanation
process 'Order product' This lines says this file specifies the required result of a process and what the name of this process is. In the app this will result in a way to start this process. E.g. by an added menu item.
results in: This line indicates the start of a list of titles of required results. See the colon (:) at the end of this line? That indicates that the next lines (the result titles) should be indented to make clear that these next lines are part of this results in: line.
"customer has ordered a product The title of one of these required results (we will add more later). As you can see titles should always between double quotes ("..."). If you do that correctly these titles should get coloured (green). This colouring is called syntax highlighting which is one of the features of the GEARS extension that you have installed previously. Do you also notice that this line is indentes with 4 spaces? It is important that all result titles have the same indentation.
"customer has ordered a product" = Each title of a required result needs to be specified in more details. This is called the definition of a required result en you recognize it because it ends with an equal sign (=)
one ORDER in ORDERS is created with: This line is the first time an actual result is specified. In this case it specifies that a (new) ORDER will be created in the collections of ORDERS. I the app this will result in a record being stored in a database when this processes is executed. Do you notice that this line is also indented? We need to do that make clear that this line is part of this result definition. Do you also notice that this line also ends with a colon (:)? That means that the next lines are part of this line and should be indented correctly to make that clear. I guess you already figured out by now that indenting is pretty important in SMART notation. And you are right, it is used to group things together. As you will find out, GEARS will complain and even prevent you from making errors in these indentations. We will try that out later.
product_name = input from CUSTOMER This line says that each ORDER will have a product_name and that this information will come from (in other words input from) a person with the role CUSTOMER. In the app this will result in a form with the field Product name on it, which can be entered only by a user that has the role CUSTOMER. It also means that if this the first input that needs to be given in this process, any user with the role CUSTOMER can start that process (and not other users). As you can see, if you are using GEARS to develop applications, those applications will be secure by default.
quantity = 1 This line says that each order will have a quantity. In other words, how many of these products should be ordered. And it is set to 1. We will change that later.
  1. Press CTRL+SHIFT+B and choose ...Generate.... Your whole screen should look a bit like this:

You should be able to see the Terminal panel which shows the output of the GEARS generation. Apparently there was an error. It says:

Generation output Explanation
Blue In which process the error was found.
Red What the error was. Apparently ORDERS is unknown to GEARS.
Orange In which file the error was found (file Order product.sn) and at which location in that file, in this case line 7 position 18, and if possible a copy past of that line with a ^ below the location.

In the beginning these errors may mean nothing to you, but during this getting started you will learn more and more about them.

3. Specify a logical data model

In this example GEARS tells us there is an error becasue GEARS does not yet know about the world of webshops and ordering products. We will have the help it understand by specifying what ORDERS means, as well as what the attributes or ORDERS, such as product_name and quantity means. This is called a Logical Data Model. Other words for that are Domain Model, or Entity Model, or Object Class Model. Take your pick but in this getting started we will stick to Logica Data Model or LDM).

To put it simple, an LDM defines the world with:

  • Entities: what types of things are important in the world of this application. If your application would be about producing cars then CARS would be important, but also ENGINES, TIRES, etc. If your application would be about friends sending messages to each other then FRIENDS, MESSAGES and GROUPS would be important. In our example ORDERS are important (and probably some other things as well, but we will come to that later). Did you notice that all these entities are in capital case? We do that to make a clear seperation between entities and their normal attributes.
  • Normal attributes: those are the normal properties that those entities have. Normal as in they will have simple values, such as a text value, a numeric value, a date/time value, or a boolean (true/false, yes/no) value. For instance CARS would have a textual attribute called color and a date attribute called produced_on. And andy of those ENGINES will have a numeric attribute weight and a textual attribute called fuel_type (e.g. petrol, electricity). For the friends app each of those FRIENDS will have a textual attribute called name and a numeric attribute called phone_number.
  • Relational attributes: some of the attributes contain other entities as values. Those are called relational attributes. For instance a CAR will have an attribute called ENGINE which of course refers to the entity ENGINES. And in the friends app the entity FRIENDS will a lot of SENT_MESSAGES that are filled with all sorts of MESSAGES that have been sent.

Let create a LDM for this application:

  1. In the specs folder, create a files called LDM.sn with the following content:
reusable definitions

ORDER in ORDERS =
    product_name : text
    quantity     : number

Let's explain the different lines and what the effect of each line will have in the application you are developing:

Line Explanation
reusable definitions This is just saying that this files contains things we want to reuse across different other specifications.
ORDER in ORDERS = This specifies the entity type name (in single) and the entity name (in plural). In the database of your application a table called GS_ORDERS will be created that will store all the orders of your application. Why the GS_ prefix you wonder? Well if you remember during Setting up your project you created a file called gears.json and it contained a line with "tableNamePrefix": "GS". It was just an abreviation for Getting Started (the name of your project) and it instructed GEARS to create tables for your entities and those tables will all start with. Well now you know what it does.
product_name : text This specifies that ORDERS wil have an attribute called product_name and it will hold a textual value.
quantity : number Similar but then an attribute called quantity and it will hold a numeric value (e.g. 1, 2, 3, etc).
  1. Press CTRL+SHIFT+B and choose ...Generate.... The output in the Terminal panel should look a bit like this:
Running GEARS Generator 1.5.4...
6834 INFO  com.xlrit.gears.generator.Driver$ - Copying C:\git\demo_cases\getting-started\resources to C:\git\demo_cases\getting-started\target\getting_started\src\main\resources
6848 INFO  com.xlrit.gears.generator.Driver$ - Copying C:\git\demo_cases\getting-started\scenarios to C:\git\demo_cases\getting-started\target\getting_started\src\test\resources\scenarios

Generated 11 files in 5,5 seconds

It reported no errors, which means all should be fine. Congratulations, you have probably created your first application using GEARS. Let's take look at the result:

4. Take a look at the resulting diagrams

GEARS has created a design for your application in the form of several diagrams. Let's take a look at those first:

  1. Press CTRL+SHIFT+B and choose ...Show diagrams.... Your internet browser should open up with one of those designs.

This may not work the first time because you have not yet told the GEARS extension where your browser is. To fix that press CTL+, and search for GEARS. You should see a setting called Gears: Browser. Change this to point to your favourite browser. For instance "C:\Program Files\Google\Chrome\Application\chrome.exe". Don't forget double quotes around this when this value contains a space.

Here is some explanation:

Diagram part Explanation
Hamburger menu (red arrow) Will simply open or close the left pane
DG Will show or hide the Dependency diagram. This shows all dependencies between the different parts of the required result that a process needs to produce. As it is seldom needed while developing applications we will not explain it during this getting started.
PD Will show or hide the Process Diagram.
Left pane Shows links to the all the diagrams in the design.
Right pane Shows the currently selected diagram. In this example the Project Diagrams are shown, which currently only contains the LDM in the form a Entity Relationship Diagram using Crows Foot Notation. The oker coloured entities (MESSAGE, USER, ..., DOCUMENT) are default entities that all GEARS applications have by default. You can use those entities but you cannot change them. The blue coloured entities (in this example only ORDER) are the ones you have specified.
  1. Click on the white circle of the entitity USER and the entity ORDER. It will show the attributes of those entities.

Did you notice all the attributes in the entity USER? All these out-of-the-box attributes can be used in the specifications and will have effect in the application you created. We'll try that out later.

Did you also notice that ORDER has 2 out-of-the-box attributes that you did not specifiy yourself? Those are created_at and modified_at which is automatically filled with the current date time of the moment that this ORDER was created/modified. GEARS has also automatically adds 2 extra relational attributes called CREATOR and MODIFIER and one technical attribute called id (that do not show in the diagram). These are relational attributes to the USER that has created/modified this ORDER and a technical identifier to uniquely identify a row in a database table. These attributes are automatically added and filled and can be used from the specifications. We will do that later.

You can also click on the lines between the entities. That will show the relational attributes (sadly in this version that is only working correctly for the first relational attribute 🙁)).

  1. Click on the blue link Order products.

This shows a process that starts with a form for the CUSTOMER to enter productname and quantity for the ORDER. In the blue box it shows what will happen after the CUSTOMER has submitten this form (basically it will create the required result and store it in the database).

5. Build and run the application

GEARS has also created all the source code for your application. This source code must be transformed to a set of zero's and ones that you can run as an application on a computer. This process is called "Build". After it is build you can run the application. We will do both in one go:

  1. Go back to VS Code and press CTRL+SHIFT+B and choose ...Run Application.... This will both "Build" your application and then run it.

You will a lot of things happening in the Terminal pane of VS Code. You don't have to read or even understand this (just yet) other then knowning this is your application starting up. But perhaps it is nice to see that FUN STARTS banner flying by. Starting up may take some time (on my laptop it takes about 20 seconds). This is because any GEARS application is already capable of doing many things, so it may take some time to get ready. No worries using the application is pretty fast.

Once you see the text Started GettingStartedApplication in ... seconds (JVM running for ...) you can start using your application.

6. Using your first application

Now it is time to try out your first application, for the very first time:

  1. Open an internet browser (e.g. Chrome) and open the URL http://localhost:8080. It should look a bit like this:

  1. Log in with user demo and password demo. And click on menu Start. It should a bit like this:

Can you remember setting create-demo-users: true in file application.yml which you setup during Set up your project. This setting is the reason why this demo user is created automatically. Of course we should never turn on this setting when this application is deployed for many to use. That is why you need remove this setting before you do that.

Note that if you click on menu Start there is nothing to start. That is because user demo does not have the role CUSTOMER.

7. Adding users to roles

  1. Add the following file to the subfolder data:
  • file name: 01_users_and_roles.sql
  • content:
INSERT INTO SYS_ROLE
(id_                      ,name_           ,description_                      ,type_     ,active_) VALUES
('customer'               ,'customer'      ,'all customers of the application','WORKFLOW',true)
;
INSERT INTO SYS_ASSIGNMENT
(user_id_                 ,role_id_) VALUES
('demo'                   ,'customer')
;
  1. Press CTRL+SHIFT+B and choose ...Load data.... In the terminal pane you should see a result containing this:
Running GEARS Runner 0.22...
Loading data files '**' from C:\git\demo_cases\getting-started\data...
- Loading 01_users_and_roles.sql

Executed 1 scenarios with 0 failures in 2,0 seconds
  1. Now go back to the internet browser where your application is showing at URL http://localhost:8080/#/gears/processes/start.
  2. Press F5 (or click the internet browsers refresh button). The result should look like this:

  1. Click on button/process Order product. The result should get a form that look like this:

  1. Simply enter the name of any product you would like to order and click Submit.

Great! you have just succesfully created an application that apparently does something. Let's investigate if it has created the desired result.

8. Check the actual created result

Most of the results are stored in a database. Let's see what was stored:

  1. Open the app DBeaver
  2. Open the database connection H2 Embedded V.2.
  3. Expand it until you see all tables. It should look like this:

If not simply click on first and if needed also Right-click on Tables and choose Refresh.

There are quite a lot of tables and many provide all sorts of functionality out of the box for any GEARS application. But you are of course interested in the tables that start with that prefix. Can you remember the (getting started) GS prefix which you specified during GS_02_Set_up_your_project?

  1. In the left pane search for the table called GS_ORDER. Right click on it and choose View table (F4).
  2. In the right pane click tab Data:

The content of the table is shown and it should look a bit like this:

ID_ CREATED_AT_ MODIFIED_AT_ PRODUCT_NAME_ QUANTITY_ CREATOR_ID_ MODIFIER_ID_
01G8NKVZS8ZK545XV7TP05WE5B 2022-07-23 15:27:39.574408 2022-07-23 15:27:39.593388 Tesla Model 3 1 demo demo

Did you notice that all attributes end with an underscore (_). This is done to give unique names to the columns in the table that do not interfere with the matching specified attribute names.

Did you also notice that GEARS has added a couple of extra columns. ID_ is a value to uniquely identify each row in a table. The columns CREATED_AT_, MODIFIED_AT_, CREATOR_ID_ and MODIFIER_ID_ match with the automatically added attributes created_at, modified_at, CREATOR and MODIFIER which I already talked about in previously in this page (under 4. Take a look at the resulting diagrams).

Congratulations, you have not only created your first functioning application, you have also just proved it has produced the required end result that you have specified. Let's tidy up and commit your first working app to the central Git repository.

9. Tidy up and commit your work to central Git repository

You've created something, and proved it works as expected. That is most often THE moment to commit your work and push it to the central Git repository. Lets do that now:

Back in VS code there are still some things up and running that (because you are done) are still there or even still running. Let's tidy those up one by one.

  1. You can kill the tasks that are still open or running by hovering over them and click on the little trash can icon. Alternatively you can right click the tasks and choose Kill.

In the left you see the Git icon with a number in it. In the example below that is 52. It says that since your last commit to the git repository 52 files have either been created or changed.

  1. Click on this Git icon. It opens the source control pane and it should look a bit like this. If it does not you may want to click on the "View as Tree" icon that should be visible where the red arrow points.

Now most of the changed files have been created by GEARS and as GEARS will do that automatically it is not really useful to commit these files to git. That is where gitignore comes in. Anything mentioned in this file will be ignored by git and will not be commited. It can contain files, folders or even patters such *.log to ignore all files that end with .log.

  1. Right click on the subfolder called target (green arrow) and choose Add to .gitignore. You should see that the files are reduced from say 52 to 7. The rest are now ignored.
  2. In the left pane hover over .gitignore and choose the Open File icon (red arrow).

As you can see the list of files that are ignored is rather big. It is much easier to ignore whole folders. Let's do that.

  1. Replace the whole content of this file with just the text target and save it (CTRL+S). The number of files that have changed should have stayed the same because now all files in the folder target are all ignored.

It is now time to commit your work and push it to the central Git repository.

  1. Enter some short summary of your work (e.g. my first project) in the Message box just above the blue Commit button.
  2. Click that Commit button. You have now created a package of work that can be pushed to the central repository. A blue Sync Changes button should appear.

The first time you commit something to Git, Git does not yet know under which name and email address it should do this commit. To add or change this you can open up a terminal (in VS Code you can do that by pressing CTRL+SHIFT+` or via menu Terminal then New Terminal) and execute the following 2 commands with your first name and last name and with your email address:

git config --global user.name "YOUR_FIRST_NAME YOUR_LAST_NAME"
git config --global user.email "YOUR_EMAIL_ADDRESS"
  1. Click that Sync Changes button.

As you guessed it, this button both pushes your changes to the central repository, but it also pulls changes that others have made to that central repository back to your local computer. This makes it a really nice way of working together on one project. If you are interested in a good approach on how to work together on one project using Git, you can read Working-together-using-git.

Maybe as a last nice thing to see is that your files are now actually available and viewable on the central Git repository (also called "the remote") via a webpage. There is a short cut to that location on the web. Just click the Open Repository on Remote icon (red arrow):

You will see the files you created from the GitLab web page. It should look a bit like this:

Once again congratulations on you first work. You created a first working application, proved it works, and commit your work to the central Git repository so you and your team can work on it together.

10. Do it yourself

You already set up a new project for your school-system. It is now time to add your first functionality to it.

10.1. Situation: a school needs a new special school system

The school needs special functionality but also normal functionality such as registering new students. Your assignment will be about that.

10.2. Assignment: parents can register their kids as a student

Add new functionality enables parents to register theirs kids as a student. A PARENT (a role that can be played by our demo user) should be able to start a process called ...? Well, that is something you should fill in And this process will produce a result being a ...? It could be a registered kid a registered student? That is also up to you. It us usually best to choose something that matches the perspective of the system, which in this case is a school system. So ask yourself: for this school system is it a new kid or a new student?

Whatever you choose, for now only the first name, last name and date of birth should be entered by the PARENT to register a new student.

Go ahead an create this first piece of functionality.