XOOM Starter

The project generator for the VLINGO/XOOM quick start components.

Introduction

starter enables project structure generation and components initialization for VLINGO/XOOM applications. The primary generation output contains:

  • vlingo-xoom initializer class

  • Maven build configuration: pom.xml

  • Default test class

The structure is represented here.

├── src
| ├── main
| | └── java
| | └──[custom-package]
| | └── Bootstrap.java
| └── test
| └── java
| └──[custom-package]
| └── BootstrapTest.java
└── pom.xml

Requirements

  • Java 8+

  • Maven 3.x.x

  • Docker Desktop 18.x

Installation

Download starter compressed distribution file via curl:

  • zip file: curl -L -O https://github.com/vlingo/vlingo-xoom-starter/raw/master/dist/starter.zip

  • tar file: curl -L -O https://github.com/vlingo/vlingo-xoom-starter/raw/master/dist/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 allow read and execute access on executable script, placed under the root folder, as following:

$ chmod 755 xoom

Ensure it's all set by verifying the vlingo-xoom-starter version:

$ ./xoom -version
1.3.0

Application Generation

In addition to the command-line interface (see below), vlingo-xoom-starter provides a web/graphical user interface for a rapid application generation. Simply open a terminal window, execute xoom gui and your preferred browser will be opened with a wizard-fashioned screen.

Filling in every wizard step. You can readily take advantage of several auto-generated resources:

  • A full maven project structure with all required vlingo-* dependencies

  • Aggregate and Domain Event classes prepared for vlingo-symbio reactive storage types

  • REST resources, CQRS projections, adapters, and data types

  • Storage type providers supporting StateStore and Journal

  • Containerization files facilitating Docker and Kubernetes deployment

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-starter folder. See a commented properties file sample below:

#Maven artifact version
version=1.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
#vlingo xoom version
vlingo.xoom.server.version=1.3.0
#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
#Aggregate names (separated by semicolon)
aggregates=AggregateName1;AggregateName2;AggregateName3
#Domain Events (each events group should be preceded by Aggregate name and separated by semicolon)
events=AggregateName1,DomainEvent1,DomainEvent2;AggregateName2,DomainEvent1,DomainEvent2;AggregateName3,DomainEvent1,DomainEvent2
#Aggregate Rest Resources
rest.resources=AggregateName1;AggregateName2;AggregateName3
#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

Executing xoom gen causes the application generation based on the settings above, which are the same available on user interface.

Docker Commands

vlingo-xoom-starter provides cool shortcuts for interacting with Docker, from the project root folder, as follows:

Command

Description

Options

xoom docker status

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

N/A

xoom docker package

Builds / update the Docker image from the application 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

Collaboration

Our team really appreciates collaboration, not only because it boosts the evolution of vlingo components but also for the fact: the more standpoints, the more complete and mature vlingo community will be. If you are looking forward to it, take a tour of our development guide.