XOOM Designer

The visual model designer for DOMA, DDD, and compressed Ports and Adapters architecture providing a low-code project delivery for the VLINGO XOOM platform.

Introduction

A common reality of unfamiliarity exists for many developers either when they try to develop either Reactive applications or to implement DOMA and DDD properly, or both. Many give up on using concepts and paradigms that are proven to be a strong foundation for building modern applications and systems that are robust, modularized, scalable, and that use modern architectures. These developers tend to fall back to familiar, yet outdated, frameworks and tools.

The VLINGO XOOM platform was created to help developers who face such challenges to confidently move forward and modernize their work. One platform component that greatly accelerates developer modernization efforts is the XOOM Designer. Our Designer supports visual model definition, along with a compressed Ports and Adapters architecture that includes REST API, persistence, and container definitions. Following design, your DOMA and DDD project is generated and immediately built. Your applications and microservices can be running within minutes.

With an instantly executable applications and microservices experience, developers are in a position to quickly implement custom business logic within the pre-generated model as they take over with full life-cycle. The Designer can generate alternative models so teams can experiment with DOMA and DDD results. This is also a great way to learn Reactive architecture along with DOMA and DDD, both strategic and tactical modeling that are powered by an actor-based ecosystem.

The next section show you how to run and use the XOOM Designer in your local environment. Let's get started!

Installation

The installation process is short. Before you start, just check if you have these tools already installed:

  • Java 8+

  • Maven 3.x.x

  • Docker Desktop 18.x

Download the XOOM Designer compressed distribution file using curl.

File type: zip

$ curl -L -O https://github.com/vlingo/vlingo-xoom-starter/releases/latest/download/starter.zip

File type: tar

$ curl -L -O https://github.com/vlingo/vlingo-xoom-starter/releases/latest/download/starter.tar

Extract the file content, then set an environment variable named VLINGO_XOOM_STARTER_HOME indicating the absolute path for the uncompressed folder. Additionally, on Unix-based operating systems, it is necessary to enabled read and execute access on executable script as following:

$ chmod 755 xoom

Ensure it's all set by verifying the version (version shown is an example, not necessarily current):

$ ./xoom -version
1.4.4

Application Generation

In addition to the command-line interface (see below), XOOM Designer provides a web/graphical user interface for a rapid application generation. Simply open a terminal window and run the Starter.

$ ./xoom gui

Following this your preferred browser will open with a wizard-fashioned screen, consisting of five steps.

Context Step

The first step defines the project artifact and service packaging.

Currently Maven build is supported. You may easily convert the generated project build to Gradle by using the Gradle conversion task.

Aggregates Step

The second step is used to design feature-based slices through the architecture.

The vital parts of the architecture responsibilities are specified using a domain model focus. Define a domain model aggregate/entity type, its events emitted by each of its command message handlers, the REST API at the frontend, and how it will receive incoming events.

In a single form, define the model aggregate/entity type, state, events, and REST API for:

  • Aggregates and State: protocol name; message handler methods; state attributes/properties; emitted events

  • Domain Events: name; attributes/properties

  • REST Resources: HTTP method; URI path and path parameters; aggregate message handler method to which the resource dispatches

Following each aggregate definition, add it to the model and see it in the design view.

Track each architectural slice, including REST API, aggregate, and emitted events, on the Aggregate design view. It shows an interesting angle of your model through a design-level Event Storming perspective.

Persistence Step

The third step is used to define the persistence, and if CQRS is in use, both command and query models.

This step displays persistence preferences. Configuration selections include the storage type, CQRS usage, specific database mechanisms, and when applicable, how events are projected to the query model.

Deployment Step

The fourth step defines the deployment container types.

The project generator provides default packaging, such as Java JAR, but may also include containerization files facilitating Docker and Kubernetes deployment. Using the Deployment Step, choose among deployment types as needed.

Generation Step

The fifth and final step defines project component types, and generates the project.

Enter the project parent folder. In addition, select whether VLINGO XOOM annotations and auto-dispatch are preferred, or not. Click Finish to generate the defined service project.

Once the five definition steps are completed and the service project is generated, take full advantage of the power of the VLINGO XOOM acceleration components. Use the platform comprehensive documentation and its live and collaborative community that supports developers on their journey. Now, go have fun!

CLI

Alternatively, you can also generate applications directly from the terminal through xoom gen command. In this case, the project settings have to be informed in a properties file under the vlingo-xoom-designer folder. See a commented properties file sample below:

#Maven artifact version
version=1.0.0
#Maven project group id
group.id=com.company
#Maven artifact version
artifact.id=xoom-application
#Base package name
package=com.company.business
#Absolute path for the project parent folder
target.folder=/home/projects
#Deployment Type (NONE, DOCKER, KUBERNETES)
deployment=DOCKER
#Docker Image name, required if deployment type is KUBERNETES or DOCKER
docker.image=xoom-app
#Published Docker Image, required if deployment type is KUBERNETES
k8s.image=xoom-application
#Kubernetes POD name, required if deployment type is KUBERNETES
k8s.pod.name=xoom-application
#Storage Type (STATE_STORE or JOURNAL)
storage.type=STATE_STORE
#CQRS (true or false)
cqrs=true
#Projections Type (NONE, EVENT or OPERATION)
projections=EVENT
#Domain Model Database, required if CQRS is false (IN_MEMORY, POSTGRES, HSQLDB, MYSQL, YUGA_BYTE)
database=HSQLDB
#Command Model Database, required if CQRS is true or Storage Type is Journal (see database types above)
command.model.database=MYSQL
#Query Model Database, required if CQRS is true or Storage Type is Journal (see database types above)
query.model.database=YUGA_BYTE
#Use Xoom Annotations, when applicable
annotations=true
#Use Auto Dispatch Resources
auto.dispatch=true
#Xoom version
vlingo.xoom.version=1.4.1-SNAPSHOT

Executing xoom gen causes the application generation based on the settings above.

Containerization Commands

vlingo-xoom-designer provides cool shortcuts for interacting with Docker, Kubernetes, and Gloo. The following commands have to be run from the project root folder:

Command

Description

Options

xoom docker status

Shows the container status. Should be executed on the project root folder.

N/A

xoom docker package

Build / update the Docker image from the application's current state. Should be executed on the project root folder.

tag: relate a tag to the current image build. If not informed, the default value is latest. Example: xoom docker package --tag 1.0

xoom docker push

Publishes the image into the configured docker repository. Should be executed on the project root folder.

tag: relate the local tag to the remote tag. If not informed, the default value is latest:latest, following the pattern local-tag:remote-tag. Example: xoom docker push --tag 1.0:latest

xoom k8s push

Apply the manifest file(s) placed under deployment/k8s on Kubernetes

N/A

xoom gloo init

Install the Gloo Gateway API generating an upstream for each running service on Kubernetes.

N/A

xoom gloo suspend

Uninstall the Gloo Gateway API.

N/A

xoom gloo route

Create routes, on Gloo Gateway API, for endpoints declared in vlingo-xoom.properties

In vlingo-xoom.properties , define the options described below:

gloo.upstream: a Gloo upstream name for the app's service running on K8s. Example: gloo.upstream = default-myxoomapp-8080

gloo.resource.[resource-name]: an endpoint for an application resource identified by resource-name. Example: gloo.resource.balance = v1/balance gloo.gateway.[resource-name]: a gateway route corresponding to a mapped endpoint identified by resource-name. Example: gloo.gateway.balance= balance Note that, for each resource, a pair of gloo.resource / gloo.gateway has to be informed for properly creating a route in the Gloo Gateway API.

Collaboration

Our team really appreciates collaboration, not only because it boosts VLINGO XOOM to greater value, but also for the fact that the more viewpoints we have the more competent and mature the VLINGO XOOM community becomes. If you want to be a catalyst for moving the platform forward, take a tour of our development guide.