Developer training - Day one
This day covers:
Quick review of the platform
The Genesis low-code platform is the only low-code platform designed to build and run mission-critical systems for the financial markets, based on event-driven and microservice architecture.
The platform enables your application to handle events and distribute data in real time from the start by using its building blocks, such as Data Servers, Request Servers and Event Handlers. These resources are powered by Genesis Platform Abstraction Language (GPAL), which plugs into IntelliJ, allowing for code autocompletion, compilation and syntax highlighting as you code.
Genesis Low-Code Platform
At the heart of the server is the data persistence layer and the data model. You model your data by defining fields, then tables, then views.
Once you have a data model defined, you can start bringing your application to life by creating events in an Event Handler process, which have access to the data layer importing auto-generated data repositories, to handle the business logic with code written in languages such as Kotlin and/or Java.
When it comes to displaying the data, you can configure a Data Server to distribute the data to the front end. The Data Server is a GPAL component that streams the data in real time to subscribers, such as a data grid component in the front end. You can also bind a button in the UI to an event (action) defined in your Event Handler.
All of this is managed by the Genesis low-code platform. You don't need to worry about inter-process communication or even how to connect the front end to the back end, as the Platform handles a web socket connection between the browser and the data server for you. Even defining something as simple as the example below will get you a data grid showing all trades in real time:
Back end
dataServer {
query("ALL_TRADES", TRADE)
}
Front end
<zero-grid-pro rowHeight="45">
<grid-pro-genesis-datasource resourceName="ALL_TRADES" orderBy="TRADE_DATETIME" />
</zero-grid-pro>
Now let's take a closer look at the server architecture.
Server Architecture
Surrounding the core, operational tools enable you to run and monitor the application, while cluster services enable you to run across multiple nodes. Auth and permissions enable you control access and build sophisticated and granular access to data and functions.
You will get familiar with all these concepts in the next lessons.
Developing your first application
This will enable you to see the basics of the Genesis low-code platform by starting with a very simple application. It is designed simply to get from start to finish as quickly as possible. It is in five main steps:
- Create a new project.
- Define the data model.
- Add business logic.
- Prepare the server.
- Build and Deploy process.
What you will build
The very simple application you will build will look like this:
- a simple table with 5 fields
- two front-end components: one to display data and one to insert data
Once you finish this lesson, you will extend this initial simple application into a full Trades & Positions app!
With a lack of imagination we hope you will find trustworthy, we are going to call this example application alpha. You will see this reflected in the file names throughout.
1. Create a new project
To create a new project, you can use the genx CLI tool, which enables you to seed projects. Further details can be found here.
In our case, we just want to extend a blank full-stack application project, so we are using the training seed. Hopefully, you have followed the Environment set-up and done the step Start the project baseline, where you cloned the repository locally.
Here's a quick overview of the repository that you cloned:
Above, we have expanded the client folder. This contains all the UI-related projects.
The server folder follows the same structure. This contains all the server-side projects.
2. Define the data model
Now you are ready to define the fields and tables that make up your data model. This model structures information in a simple way that can be viewed by users and processed by the application.
Open IntelliJ and open the alpha project (the devtraining-seed you cloned). After importing and indexing, you should see the files and project structure ready.
Add fields
You define your fields in the file alpha-fields-dictionary.kts.
Once the project is open, there are two easy ways to find this file quickly in Intellij:
- Press the Shift key twice, then type the name of the file you are looking for.
- Press Shift + Ctrl + N, then type the name of the file you are looking for.
For our simple example, we will add five fields:
fields {
field("TRADE_ID", type = STRING)
field("QUANTITY", type = INT)
field("PRICE", type = DOUBLE)
field("SYMBOL", type = STRING)
field("DIRECTION", type = ENUM("BUY", "SELL", default = "BUY"))
}
After you have saved this file, run genesis-generated-fields as will be explained next.
generateFields
After you have saved this file, run genesis-generated-fields from the Gradle menu on the right of Intellij, this is:
genesisproduct-alpha/alpha-dictionary-cache/alpha-generated-fields/Tasks/genesis/generateFields
Alternatively, you can run the Gradle tasks from the command line.
./gradlew :genesisproduct-alpha:alpha-dictionary-cache:alpha-generated-fields:generateFields
You are editing a kts file that needs to be compiled and built to be used from other places. In this case, we want the fields to be available to the tables (and with intellisense support from the IDE).
As we go, you'll see we have different Gradle tasks, depending on the artifact we want to build.
Add a table
Now we have our fields, let's define a table in the file alpha-tables-dictionary.kts.
We are defining one single table, containing all our fields.
TRADE_ID is the primaryKey, which will be auto-generated.
tables {
table (name = "TRADE", id = 2000) {
sequence(TRADE_ID, "TR")
QUANTITY
PRICE not null
SYMBOL
DIRECTION
primaryKey {
TRADE_ID
}
}
}
After you have saved this file, run genesis-generated-dao as will be explained next.
generateDao
After you have saved this file, run genesis-generated-dao from the Gradle menu, this is:
genesisproduct-alpha/alpha-dictionary-cache/genesis-generated-dao/Tasks/genesis/generateDao
./gradlew :genesisproduct-alpha:alpha-dictionary-cache:alpha-generated-dao:generateDao
After running this, you have the DAOs (i.e. data repos) automatically generated from the tables and available to be imported in your code.
3. Add business logic
We have a table; now we want to be able to see its contents and create new entries.
Data Server
A Data Server enables data to be read in real time. You must define the Data Server in the file alpha-dataserver.kts.
dataServer {
query("ALL_TRADES", TRADE)
}
Event Handler
Next, we want to be able to insert rows into our table. For this, you need to define an Event Handler in the file alpha-eventhandler.kts.
eventHandler {
eventHandler<Trade>(name = "TRADE_INSERT") {
schemaValidation = false
onCommit { event ->
entityDb.insert(event.details)
ack()
}
}
}
The entityDb enables you to interact with the database layer. It's part of the Genesis Database API and we'll get into more details soon. For now, understand that this is the common way to access data from code. Feel free to use the intellisense of your IDE to explore the methods available from entityDb.
4. Prepare the server
So far we have created an Event Handler and Data Server - just their definitions, but there's nothing on the runtime configuration yet. Each microservice, such as Event Handler and Data Server, must run on their own process. To do that, we have to change the processes and the service definition files:
- alpha-processes.xml
- alpha-service-definitions.xml
At present, these files are empty. You need to insert the details of the Data Server and Event Handler that you have just created.
Add the following content to the alpha-processes.xml file.
<processes>
<process name="ALPHA_DATASERVER">
<groupId>ALPHA</groupId>
<start>true</start>
<options>-Xmx1024m -DXSD_VALIDATE=false</options>
<module>genesis-pal-dataserver</module>
<package>global.genesis.dataserver.pal</package>
<script>alpha-dataserver.kts</script>
<description>Displays real-time details</description>
<language>pal</language>
<loggingLevel>DEBUG,DATADUMP_ON</loggingLevel>
</process>
<process name="ALPHA_EVENT_HANDLER">
<groupId>ALPHA</groupId>
<start>true</start>
<options>-Xmx256m -DRedirectStreamsToLog=true -DXSD_VALIDATE=false</options>
<module>genesis-pal-eventhandler</module>
<package>global.genesis.eventhandler.pal</package>
<script>alpha-eventhandler.kts</script>
<description>Handles events</description>
<classpath>alpha-app*</classpath>
<language>pal</language>
</process>
</processes>
Add the following content to the alpha-service-definitions.xml file.
<configuration>
<service host="localhost" name="ALPHA_DATASERVER" port="11000"/>
<service host="localhost" name="ALPHA_EVENT_HANDLER" port="11001"/>
</configuration>
Please see here for a detailed description of the processes configuration.
5. The build and deploy process
Finally, you can build and deploy the server.
Build
In the Gradle menu on the right of IntelliJ, select:
genesisproduct-alpha
./gradlew :genesisproduct-alpha:assemble
Deploy
As soon as the Build is done, you need to deploy the application. To do that, click on the Genesis plugin in your intellij (in the panel on the right).
When you click on it for the first time, it will map all the available processes and display these in the mon panel:
To deploy your application, click on deploy Genesis:
The plugin then creates your runtime folder containing all the generated files required for your local application to run. This runtime folder is available under the server/alpha-app/build/ folder and it is called genesis-home:
Congratulations! You have built and deployed an application.
Credentials to login
By default, the following will be your login details:
- Username: JaneDee
- Password: beONneON*74 (This is encrypted in the user.csv file.)
However, after the first Build and Deploy, you need to send the login information so that you can access the application you have just created.
Create a new schema
Before you can run your application, you need to create a new schema for the database; this is where all the tables will be created. To do that,
Run remap.
Send data to Genesis
Go to server/alpha-app/src/main/genesis/data/USER.csv, right-click on this csv file and select Import CSV(s) to Genesis.
After that, you have all the data to start the application.
Details
Want to check if your data has been sent?
To check your database, Genesis Intellij plugin has the following script
Type table USER and then search 1; this will display the following:
==================================
Genesis Database Monitor
Enter 'help' for a list of commands
==================================
DbMon>table USER
DbMon:USER>search 1
==================================
USER
==================================
Field Name Value Type
===========================================================================================
TIMESTAMP 2024-03-27 11:11:43.634(n:0,s:1) NANO_TIMESTAMP
COMPANY_ID STRING
COMPANY_NAME GENESIS STRING
DOMAIN STRING
EMAIL_ADDRESS jane.dee@genesis.global STRING
FIRST_NAME Jane STRING
LAST_LOGIN 2016-04-28T00:00:00.000Z DATE
LAST_NAME Dee STRING
ONLINE false BOOLEAN
PASSWORD 1cf46a0c2148f6399159ff576768d715b5207... STRING
PASSWORD_EXPIRY_DATETIME DATETIME
STATUS ENABLED STRING
USER_NAME JaneDee STRING
-------------------------------------------------------------------------------------------
-------------------------------------------------------------------------------------------
Total Results: 1
Starting the server
Now we need to start the server. To do that, click on the start server button. This starts all the processes:
And that's all you have to do to get your server up and running.
Testing the back end
There are multiple ways you can test the back end of your application. It's important to note that most resources, such as Event Handlers and Data Servers, are exposed as HTTP endpoints automatically by the Genesis low-code platform - without any additional code. This enables you to test those resources from HTTP clients, such as Postman.
Alternatively, you can use Genesis Console, which gives you a simple way of testing components from a nice web UI.
Genesis Console
Some browsers automatically change http to https - which will cause a fail. Make sure the url starts with http before submitting. If you still have problems, open a new incognito/private browser (this avoids any cache issues).
- Enter the IP address of your server, in this case localhost port 9064, as we are using GENESIS_ROUTER locally through the Genesis plugin. So, the value to be entered here is
localhost:9064 - Log in with your user name and password as defined previously. This starts Genesis Console, and you will see a list of tabs along the top of the screen.
- Click on the RESOURCES tab.
- Filter the Resource type to show only Event Handlers.
For example:
As well as the Event Handlers that you have defined yourself, you will also see other Event Handlers that have been generated automatically by the platform: anything that is a GENESIS_CLUSTER service, for example.
If you click on any Event Handler in the list, the fields relevant to the event are displayed to the right.
Now you need to pick the Event Handler you want to test. So, let's look up EVENT_TRADE_INSERT.
- Find the Event Handler in the list, then click on the arrow beside it. On the right, this displays the relevant input fields for the event. Some are mandatory, while others are optional - depending on how the Event Handler was set up.
- Enter the details of the new trade in the fields then click on COMMIT:
If the Event Handler is working correctly, you will receive an ACK.
Checking the insertion
You can go to check the TRADE table to see if your insert is there.
-
Filter the list of services to show only Data Servers (these are the components that distribute the data).
-
Search for the relevant resource - in our case TRADE.
- Click on the arrow beside the relevant resource. You should now see the new trade in the list displayed on the right.
Exercise 1.1: Data Servers
30 mins
Look at the Data Server documentation and see if you are able to modify our Data Server defined previously:
- add a new query called "ALL_PRICES" on the TRADE table
- make ALL_PRICES display only SYMBOL and PRICE fields
- add a
whereclause so it displays only trades whose PRICE are higher than 0.0
Remember to insert a few trades using Genesis Console to test it.
Exercise 1.2: Event Handlers
20 mins
Look at the Event Handler documentation and see if you are able to modify our Event Handler defined previously:
- return
nack("Quantity must be positive")if the quantity is lower than 0.
Test it with Genesis Console.