StartledFrog

Visual Programming Language project
This project aim is to create an environment to develop Web application in a graphical way.
License: Apache 2.0
Current version: 0.0.1-a

Features

• Enhanced UML class diagram to represent both database tables and entity classes;
• Dockerized MySQL 8 database (using docker-compose);
• Generated app: Java 8 using Spring Boot v.2.3.1 framework;
• Generated app: Simple CRUD RESTful API generated using Spring Data Rest;
• Generated app: Navigable API (HATEOAS) using Spring HAL Explorer.

Demo

Modelling new application with StartledFrog

In this video new service for storing medical information of the patients is modelled.

Running and using the service generated with StartledFrog

In this video it is shown:

• How to launch generated application (SpringBoot RESTful service and docker-compose container with MySQL database),
• How to use RESTful service, how modelled restrictions are implemented.

Currently obsolete

Since many used API were updated during the last several years, the project, though buildable with Maven, is not capable of creating new StartledFrog projects (application).

Prerequisites

Before launching the application, the following dependencies must be installed on your computer:

1. Java 8 JDK (you need JDK exactly, not just JRE in order to compile & run generated project);
2. Docker (with docker-compose) (to run database in generated project). On Windows the easiest way is to install Docker Desktop, on Linux make sure you have docker and docker-compose packages installed;
3. [Optional] Apache Maven (you can use either mvn when it is installed or Maven wrapper (mvnw) if you'd prefer to skip Maven installation).

Package installation

1. Download binaries from the latest release;
2. Just unzip it at the location handy for you.

Launch

Inside the release folder you unzipped earlier, run:

• On Windows -- run.bat;
• On Linux -- run.sh.

Usage

General information

Current state of an application is pretty simple. User abilities are limited to:

• New StartledFrog project creation;
• Existed StartledFrog project load;
• Configuration parameters modification (such as docker ip, database username/password for generated app, etc.) using the Configuration view;
• New Persistence Units creation on the diagram (Persistence view) and deletion as well;
• New association connections creation/deletion on the Persistence view.

Initial program screen

When the program is just launched you are welcome to either create or load an existed StartledFrog project to continue the work with it. Therefore the screen appeared consists of 2 separated section.

Create new project

To create a new project, you have to fill the next set of parameters:

• Choose the base directory to create the project directory within;
• Type the project name (will be automatically converted to capitalized camel case);
• Type the root package name (will be erased automatically if not valid);
• Type the project description (you are free to enter whatever gibberish you want, however, sometimes it still can be useful. It will appear in pom.xml of generated application project.

Load existed project

In order to load existed project you have to perform the following sequence of actioins:

1. Find the root project folder, generated by StartledFrog previously;
2. Select the file '.startled-frog' within the root folder (attention: it can be treated as a hidden file by your OS. In this case you should enable hidden files visibility to achieve the goal);
3. Press 'Load Startled Frog project' button. When it is done you will see corresponding fields filled with the parameters of the project you are about to load, such as application name and root package. You can use this to check yourself;
4. When the project is loaded, press 'Start modelling' button to hide the welcome screen and open the project one.

Project screen

Is divided to four section: main menu bar, switch-view buttons sidebar, the main view area and toolbar (can be empty). You can interact with model by means of different views: Configuration and Persistence ones (Note: Launch View is present at sidebar as well but is not implemented currently). By default Configuration view is loaded initially. At any point of time you can easily switch between views by clicking on a respective sidebar switch-view button.

Configuration view

Here you can choose whatever parameters you want for all presented fields, except 'Docker machine ip'. By default it is equal to localhost (if you are running Docker natively, i.e., without any virtual machine). Alternatively, you can specify other Docker machine ip (for example 192.168.99.100 is a default docker VM ip if you are running Docker on Windows without HyperV feature disabled)

Persistence view

Is StartledFrog's main view. It is used to draw an enhanced UML class diagram by leveraging FXDiagram framework created by Jan Koehnlein. As a result it has the following built-in features:

1. The main diagram menu opens by right mouse click. It is filled with the following actions:
   • Center selection;
   • Delete selection (or 'Del' shortcut);
   • Redo (or 'Ctrl+Shift+Z' shortcut);
   • Undo (or 'Ctrl+Z' shortcut);
   • Save diagram (or 'Ctrl+S' shortcut);
   • Select all (or 'Ctrl+A' shortcut);
   • Fit selection.
2. Zooming in and out using the scroll button;
3. Dragging canvas using the right mouse button;
4. Moving diagram elements (persistence units) by dragging them with left mouse button;
5. Adding anchor points and moving links (associations).

On 'Persistence View' you can use 'New Persistence Unit' tool to create new persistence unit (i.e. entity + db table) model on the diagram and populate it (initially only) with primitive fields you want. Each field has a unique name, one of predefined types, and a set of constraints.
Also you can link two units together using 'New association' tool. All you have to do after tool activation is to click on parent persistence unit (container) and on child persistence unit (element) sequentially. Afterwards you can setup link parameters:

Aggregation kind

Possible values: NONE, SHARED, COMPOSITE. Defines whether the link will represent one of the followings:

• plain association (= no additional restrictions);
• aggregation (= plain association restrictions + the element cannot be deleted while it is attached to the parent);
• composition (= aggregation restrictions + when the container entity is deleted, all its attached elements are deleted as well).

To-container and to-element attribute names

Can include spaces and limited set of special characters. Note that spaces will be trailed and names will be lowercased by default.

To-container and to-element attribute arities

Possible values:

• 0..1 (AT_MOST_ONE) -- referenced persistence unit instance is single and optional;
• 1 (ONE_EXACTLY) -- referenced persistence unit instance is single and mandatory;
• ***** (AT_LEAST_ZERO) -- referenced persistence unit instance is plural and optional.

To-container and to-element attribute navigability

If a referential attribute from persistence unit A to persistence unit B is navigable, then you will be able to discover linked B instances having A instance reference using REST API. In StartledFrog this property matters if specified referential attribute is NOT primary one. In this case you will be able to browse linked Bs using special /search nested resource on /Bs resources.

Primary reference direction

Helps you to specify which of the referential attributes (element-to-container or container-to-element) will be the primary one. If A has a primary reference (primary referential attribute) with name 'b', then it will be represented as As/b nested resource at generated RESTful API.

Main menu bar

Here the next useful entries are:

• File -> Save models (save both configuration and persistence models);
• File -> Generate program (generate the application source code based on the current models state).

Generated program launch

To launch generated application you should perform the following 3 steps (from the application root directory):

1. Ensure the Docker daemon is up and running;
2. Execute docker-compose up -d to launch dockerized database;
3. If you have Maven installed, run mvn spring-boot:run. Otherwise use its wrapper:
   • On Windows run mvnw spring-boot:run from the cmd shell;
   • On Linux run ./mvnw spring-boot:run from the bash.

When all 3 steps are executed successfully, you can explore generated application API browsing 'localhost:8080'.

To bring the application down, you can simply interrupt maven build with 'Ctrl+C'.
To fully remove dockerized database run docker-compose down