Getting Started

How to start using the VLINGO XOOM platform.

The VLINGO XOOM platform SDK is distributed as a set of libraries as well as some executable components. The documentation is available online, and that's what you are reading. The following sections explain how to access both.

To get started quickly with your first example, see the Hello, World! project.

Quick Start

Simply stated, use XOOM Designer. There are more detailed how-to instructions a few chapters later. Here you are helped to get the XOOM Designer running quickly.

At this time the XOOM Designer runs locally as a Java executable process. Soon we will have the XOOM Designer running in the cloud and will thus require no local installation. Users will also benefit from our continuous delivery of new features, improvements, and any necessary fixes.

Even though installed locally, the setup is quite painless. It's explained next.

Setup

The setup process is short. Before you start, ensure that you have the following installed:

• Java 8+

• Maven 3.x.x

• Docker Desktop 18.x

Download the xoom-designer compressed distribution file via curl.

If you want to use the zip format, download it as follows:

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

If you want to use the tar format, download it as follows:

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

Extract the file content inside a parent directory that is meant to contain it. After that, set an environment variable named VLINGO_XOOM_DESIGNER_HOME indicating the absolute path of the uncompressed folder; that is, the root of the installation folder, not the parent directory where it was decompressed. Using a *nix shell, such as bash, do this:

 $ VLINGO_XOOM_DESIGNER_HOME=[installation-path]
 $ export VLINGO_XOOM_DESIGNER_HOME

You should include the previous step in your login script, such as .bash_profile, for example. This makes the XOOM Designer ready for use after logout followed by login.

On Windows you can use the System Properties > Advanced > Environment Variables... to set the property permanently. For a one-time setting before running the design tool you can use the command line:

 C:\> set VLINGO_XOOM_DESIGNER_HOME=[installation-path]

Additionally, on *nix systems, it is necessary to set read and execute access on executable shell script that is within root installation directory:

 $ chmod 755 xoom

Verify that the setup was successful by requesting the XOOM Designer version. On *nix use the xoom shell script to run the XOOM Designer:

 $ ./xoom -version
 1.7.0

On Windows do the same, which uses xoom.bat to execute the XOOM Designer software:

C:\> xoom -version

Once running, the XOOM Designer presents a web UI that guides you intuitively. If you require more details on some aspect of the Designer, see the full details in a later chapter.

Source Code and Deployable Artifacts

From the XOOM Designer you will generate your project source, including compressed Ports and Adapters architecture, domain model, and build. See the resulting source code. You will find, for example, that the Maven pom.xml already references the XOOM libraries needed to support the build and runtime execution of the microservice. The build is ready to run.

Before building and running, assuming that you are using databases/storage other than in-memory implementations, edit your xoom-turbo.properties file to support the proper database connections. Defaults are generated for databases such as Postgres and MariaDB, and others, but these might not match your local environment. Additionally, if your microservice is event driven and receives incoming event messages or produces outgoing event messages, specify the proper connection configurations for your message broker/bus in the same properties file, namelyxoom-turbo.properties.

The following example assumes that your first XOOM Designer project is a microservice that you gave the name my-xoom-microservice, which has an initial version 0.1.0.

To build and run on *nix do the following:

$ mvn clean package
...
$ java -jar target/my-xoom-microservice-0.1.0
...

To build and run on Windows do the following:

C:\> mvn clean package
...
C:\> java -jar target\my-xoom-microservice-0.1.0
...

The service is now running. You can use curl or Postman to send HTTP request messages to the service according to your REST API design.

Using Artifacts—Development Without XOOM Designer

As noted above, the XOOM Designer generates the basic build definition for a new microservice (or larger application) so that it is ready to run. The Maven pom.xml already references and includes all of the XOOM library dependencies needed in order to build and run the microservice.

If you are not starting with the advantage of using XOOM Designer to create your initial project, you will need to pick and choose the XOOM library artifacts on your own. The artifacts for the Java Development Kit are available as jar files from three primary public repositories GitHub, Sonatype, and Maven Central.

Our platform CI builds are performed on Github Actions, and GitHub is also our base artifacts repository. When we create a release we replicate the GitHub artifacts to Sonatype, which in turn automatically replicates to Maven Central.

We also support daily SNAPSHOT builds on Github. If you want to use the latest code you may reference it as artifactId-x.y.z-SNAPSHOT. You must provide Github credentials to Maven in order to pull snapshots.

See below for details.

You may use any number of build tools to retrieve the JAR files that you need for a project. We generally recommend using either Maven or Gradle. You can include the following in your Maven pom.xml file to reference the XOOM Turbo toolkit:

...
  <repositories>
    <repository>
      <id>central</id>
      <url>http://repo1.maven.org/maven2/</url>
    </repository>
  </repositories>
  <dependencies>
    <dependency>
      <groupId>io.vlingo.xoom</groupId>
      <artifactId>xoom-turbo</artifactId>
      <version>x.y.z</version>
      <scope>compile</scope>
    </dependency>
  </dependencies>
...

Depending on the selected dependency, you can get a number of separate dependencies that are resolved by a single jar file. For example, xoom-turbo references other libraries such as xoom-lattice, xoom-http, xoom-actors, and others. In other words, you need only reference xoom-turbo as a dependency and all others required will be resolved automatically.

The release and snapshot repositories are available as follows.

...
  </repositories>
      <repository>
      <id>github</id>
      <url>https://maven.pkg.github.com/vlingo/xoom-platform</url>
      <releases><enabled>true</enabled></releases>
      <snapshots><enabled>true</enabled></snapshots>
    </repository>
  </repositories>
  <pluginRepositories>
    <pluginRepository>
      <id>github</id>
      <url>https://maven.pkg.github.com/vlingo/xoom-platform</url>
      <releases><enabled>true</enabled></releases>
      <snapshots><enabled>true</enabled></snapshots>
    </pluginRepository>
  </pluginRepositories>
...
  <dependencies>
    <dependency>
      <groupId>io.vlingo.xoom</groupId>
      <artifactId>xoom-turbo</artifactId>
      <version>1.7.1-SNAPSHOT</version>
      <scope>compile</scope>
    </dependency>
  </dependencies>
...

For use with Gradle you will need something like the following. Refer to the above Maven pom.xml for the location of our snapshots.

dependencies {
    compile 'io.vlingo.xoom:xoom-turbo:x.y.z'
}

repositories {
    jcenter()
    // or
    mavenCentral()
    // ??? GitHub how-to
}

Of course the x.y.z is representative placeholder of the semantic version number of the given artifact. Both stable releases and daily snapshot builds are provided on Sonatype, and release artifacts are hosted by Maven Central. Generally the tip revision of each JAR file listed in the repository is the one that will work together with all others as a whole platform.

Full open source for the Java platform is available on https://github.com/vlingo. Our baseline JDK is 1.8, but we have successfully used on JDK 1.14. On GitHub you see each of the components that are available, and the above dependency information applies to each of the platform components, but you must supply the actual component name. We maintain version numbers consistent across the entire platform, such that if version 1.7.0 applies to xoom-turbo then it also applies to xoom-lattice and the remaining platform components. The following is an example that uses platform version 1.7.0, but the version should be adjusted to your specific dependencies.

...
  <dependencies>
    <dependency>
      <groupId>io.vlingo.xoom</groupId>
      <artifactId>xoom-turbo</artifactId>
      <version>1.7.0</version>
      <scope>compile</scope>
    </dependency>
    <dependency>
      <groupId>io.vlingo.xoom</groupId>
      <artifactId>xoom-lattice</artifactId>
      <version>1.7.0</version>
      <scope>compile</scope>
    </dependency>
    <dependency>
      <groupId>io.vlingo.xoom</groupId>
      <artifactId>xoom-http</artifactId>
      <version>1.4.3</version>
      <scope>compile</scope>
    </dependency>
    <dependency>
      <groupId>io.vlingo.xoom</groupId>
      <artifactId>xoom-symbio</artifactId>
      <version>1.7.0</version>
      <scope>compile</scope>
    </dependency>
  </dependencies>
...

Or as an alternative to including several individual components, you can use all of the above by creating a single dependency:

...
  <dependencies>
    <dependency>
      <groupId>io.vlingo.xoom</groupId>
      <artifactId>xoom-turbo</artifactId>
      <version>1.7.0</version>
      <scope>compile</scope>
    </dependency>
  </dependencies>
...

There, that was simple.

Support, Training, Consulting, and Project Development

Our VLINGO XOOM enterprise-grade developer and production support are available here.

Our team offers live, virtual training for the VLINGO XOOM platform SDK. Consulting and project development are also available through our consulting partners. When you engage with our team you receive the best possible guidance and workforce available for Reactive architecture, software development, DOMA, and Domain-Driven Design.

Documentation and Examples

You have already found our primary platform SDK documentation. You are reading it.

Our full Javadoc is available here. Individual components are accessible, such as the actors Javadoc. You can even change to the old releases by using the version dropdown. The README.md for each open source artifact also references the current API-based Javadoc. For an example see the vlingo-actors README.md.

Architecture and programming sample projects are available in source form in the vlingo-examples repo. There are several projects. Within them you will find highlights of usage for various platform components. Some are generated by XOOM Designer and some are implemented with full manually written source code. This gives you a feel for both approaches.

Public support is available. You may register for access to our public Slack workspace for both Java and .NET.

Follow us on Twitter @vlingo_io.