Customizing
In this chapter
- customize the start-up of the server application
- create, read, update and delete domain objects from code
- understand how backend and clients stay synchronized
- add your own REST endpoint
- no files to change: this chapter explains the concepts you use from the next chapter on
As mentioned for the TOP mechanism, hand-written code adaptations are necessary for a full-stack application. Here is where and how to adapt the different parts of the MontiGem-generated code.
Customizing the server application
MontiGem generates server code to run the backend. The used technology framework is Spring Boot which provides the tools for server applications, endpoints, security, and more. The generated code is adaptable by using the TOP mechanism.
Start-up
The server application is generated from the UML class diagram. However, some
custom start-up logic might require hand-written adaptations. The entry point
for adapting the application start-up is the ServerApplication class, e.g.
carrental.CarrentalServerApplication. Here you can override the init method
with the Spring Boot @PostConstruct annotation. A typical use case for this is
the creation of start-up dummy data to test your product. You already worked
with the initEntities() method while learning the
class diagram basics.
import jakarta.annotation.PostConstruct;
import java.io.IOException;
public class CarrentalServerApplication extends CarrentalServerApplicationTOP {
@PostConstruct
@Override
public void init() throws IOException {
super.init();
initEntities();
}
protected void initEntities() {
// dummy data creation
}
}
Hand-written code extensions: create, read, update, delete (CRUD)
To handle domain objects a generated singleton class Manager is used (e.g.
carrental.CarrentalManager). It offers methods to create, retrieve or delete a
domain object. For example, for a domain object Car:
CarrentalManager.getCarSure(gemId)returns the object,CarrentalManager.carOpt(gemId)returns anOptional<Car>,CarrentalManager.getCarList()returns all objects of typeCar,CarrentalManager.carBuilder()returns a builder,CarrentalManager.deleteCar(gemId)deletes the object if present.
The manager is available both in the backend and in the frontend. Both are synchronized via a WebSocket connection. Note that synchronization is ensured between all clients and also the database.
Note
Most of the Java code in MontiGem is synchronous, it executes operations sequentially. However, the Java code for the GUI which works with domain objects is translated to asynchronous TypeScript code for the app frontend. Since the frontend is a single process, making requests asynchronous ensures that the GUI stays responsive and enables user interaction while data is being transferred from the server.
Example Java:
Car c = CarrentalManager.getCarSure(4);
// work with the c object
Example TypeScript:
CarrentalManager.getCarSure(4).then((c: Car) => {
// work with the c object
});
Updating objects happens by using the setter methods of the objects. For example:
Car c = CarrentalManager.getCarSure(4);
c.setModel("DeLorean"); // update the car model
Synchronization with the manager and the server, all clients and the database happens automatically in the background. Each domain object offers methods to edit attributes and read associations.
Synchronization
The communication between server and clients is implemented using a command
pattern and WebSockets. For each action, e.g. creating or updating a domain
object, MontiGem generates a command (a Java and TypeScript class) and
corresponding (de)serializers converting objects into JSON. When executing an
action, e.g. car.setModel("DeLorean"), these commands are exchanged between
server and clients via a WebSocket endpoint and executed. The logic of a command
can be overridden in its doAction() method.
Command names
Commands generated for an attribute or an operation of a class follow the
schema <Class>_<operation>, for example Car_setModel, Customer_create
and Customer_delete. Commands generated for a method of a service class
are named after the method, for example RentCar. You will write such a
command in the next chapter.
Commands can be sent manually by calling the singleton class CommandManager,
e.g.
CommandManager.executeCommand(new Car_setModel(4, "DeLorean"));
Result types
doAction() returns a result object:
StatusResultfor actions without a return value, created withStatusResult.ok(getId())orStatusResult.error(getId()),SimpleResult<T>for actions that return one object,ListResult<T>for actions that return a list.
Synchronization example
Consider a scenario with a database, a server, and two clients (A and B). All
have loaded the same Foo object (ID: 1).
-
Initial state:
- Database:
Foo(1).bar = "initial" - Server:
Foo(1).bar = "initial" - Client A:
Foo(1).bar = "initial" - Client B:
Foo(1).bar = "initial"
- Database:
-
Action: Client A executes
foo.setBar("updated"). -
Propagation:
- Client A: sends a
Foo_setBar(1, "updated")command to the server via WebSocket. - Server: receives the command.
- Executes it: updates the in-memory object
Foo(1).bar = "updated". - Persists it: updates the database
Foo(1).bar = "updated". - Broadcasts: sends the command to all other connected clients (Client B).
- Executes it: updates the in-memory object
- Client B: receives
Foo_setBar(1, "updated").- Executes it: updates its local object
Foo(1).bar = "updated". - The UI (if bound to
foo.bar) updates automatically via the observer pattern.
- Executes it: updates its local object
- Client A: sends a
This ensures that all participants eventually hold the same state.
Watching the traffic
The backend console logs every command it receives and sends, for example
Received: {"commandId":3,"commandType":"carrental.commands.RentCar",...}.
This log is the fastest way to check whether a button in the GUI really
triggered the action you expected.
Endpoints
Synchronization happens over the command WebSocket endpoint. Spring Boot
provides utilities to add endpoints. You may need extra endpoints to handle
binary data, for example an endpoint to store a PDF file. To do so, add a new
class with the @RestController annotation:
package carrental.service;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestPart;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;
@RestController
public class PDFEndpoint {
@PostMapping(value = "/pdf")
public ResponseEntity<String> storePDF(
@RequestPart("file") MultipartFile file,
@RequestHeader("name") String name
) {
// your code
return ResponseEntity.ok("stored " + name);
}
}
The package matters
Spring only scans the packages listed in scanBasePackages of the
@SpringBootApplication annotation in CarrentalServerApplication.java.
For this project that is carrental.service plus the MontiGem runtime
packages. Put your controller in carrental.service (or a subpackage), or
add your package to scanBasePackages. A controller in another package is
never instantiated and its endpoint returns 404.