Turbo

The VLINGO XOOM adoption and project accelerator for Java and other JVM languages.

This VLINGO XOOM component helps individual developers and architects, as well as whole teams, to speedily jump-start productivity with the platform. Our JVM SDK boosts productivity in building high-scale, high-performance, Reactive microservices and well-modularized monoliths. Our Designer helps you models and deliver your project structure for each of your subsystems, such as Microservices: REST resource handlers; domain model aggregates/entities; events and state objects; Event Sourcing and CQRS command and query models; and persistence mechanisms.

XOOM Turbo is a container around the platform components, making use fast and simple.

Starting with from visual model definition, REST API, persistence, and container definitions, to generation, to immediate build and run, your services can be running within minutes.

Startup Configuration and Initialization Wiring

A very important aspect of VLINGO XOOM is that all runtime wiring is achieved at compile time, not at startup time. This leads to very fast startup times for your services and applications. This means that adding new runtime nodes to your deployed system is performed very quickly. It also means that using the platform for FaaS-based solutions is a realistic and viable option.

This is achieved in one of two ways.

  • Handwritten code including all necessary bootstrap boilerplate

  • Annotations that wire at compile-time, not runtime, and replace almost all of the handwritten boilerplate code

Although we are not fans of sprinkling Java annotations all over a codebase, we have found that supporting a few key annotations greatly reduces the amount of boilerplate code, including configuration and startup initialization, that is required. The use of annotations is completely optional. You may choose to implement all of the configuration and initialization code yourself. Yet, we think you will agree that using a few annotations in key places is more helpful than objectionable. And, of course, if you are a fan of annotations, you will find them indispensable.

We have even more good news. Most of the bootstrap, startup, configuration, and initialization code, may be generated for you—with or without annotations—when using the VLINGO XOOM Designer.

Stepwise Adoption

We have found that one of the blockers to learning reactive programming is, well, non-blocking. As a large body of programmers, the software industry has mostly supplied and socialized blocking or synchronizing languages and tooling. Because of this, developers have come to expect blocking—and for many of us that write software in teams—you've certainly inherited and contributed to blocking code in your projects. This legacy of blocking becomes continually more difficult to change. For these reasons, it comes as no surprise that a non-blocking approach will require a cooperative mind-bending effort for teams to fully adopt an asynchronous, concurrent, and parallelized programming culture.

For this reason, we've decided to introduce a familiar way to learn the different components of the VLINGO XOOM SDK—without the need to fully utilize asynchrony early on. We're keen on providing you with the stepping stones that help you and your team make the jump to asynchrony, concurrency, and parallelism, without the added burden of learning an entirely new way of writing code. We welcome you to explore our VLINGO XOOM tools so you can quickly learn the ropes, gradually adding in asynchrony as you feel more comfortable.

It is our hope that this project will help you realize our platform's overarching goals of aggressive simplicity combined with lightweight fluency, with or without adopting Domain-Driven Design. After all, the best way to learn any language is to learn both the words and the grammar as you go, achieving fluency through both rapid and gradual practice.

Messaging is at the core of VLINGO XOOM, and as such, still uses messaging in the same way that you would with our asynchronous environment, but it conceals the learning discomfort.

There's no mystery to actors and message sending. Here's a brief explanation of how actor messaging works, but with synchronous, single-threaded programming. Assume that a sending actor sends a message to a receiving actor. The receiving actor will see the message from the sending actor and react to it. After reacting to the message, the receiving actor will then return control back to the sending actor on the same thread.

Now consider that the receiving actor is a request handler that provides an HTTP response. As non-reactive blocking communication goes, all requests to the handler will be served responses on the same thread. It's easy to understand.

The only difference in this explanation above, to what you might be used to, is the idea of using actors as an abstraction instead of HTTP-based web services. Whether or not the underlying protocol, servlet, container, or driver enables reactive or blocking communication, the actor programming model itself is unchanged. An actor is an object that receives messages and sends messages in response.

Now, take a look at the VLINGO XOOM SDK to get started making strides toward full use of the full array of components.

Boot and Start Up

To begin, you need the following dependency for your builds, the first being for Maven.

<dependency>
  <groupId>io.vlingo.xoom</groupId>
  <artifactId>xoom-turbo</artifactId>
  <version>x.y.z</version>
  <scope>compile</scope>
</dependency>

The second is for Gradle. In both examples, replace x, y, and z with the major version, minor version, and patch version, respectively, for the artifact.

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

You also need the configuration defined in the properties file xoom-actors.properties that is already provided when you use Designer for generating your project. In case you prefer to create it manually, the Actors documentation will be very useful.

To boot the VLINGO XOOM platform foundation, use the Boot API. There are three ways to do so. One way is through a void main(String[] args) boot method.

Boot.main(new String[] { "xoom-boot-world-name" });

final World world = Boot.xoomBootWorld();

Of course the main() would normally be invoked by the Java runtime. This demonstrates that if any command-line arguments are received, the first argument will be used to name the World. If there are no command-line arguments, the World will be named "vlingo-xoom".

A second way to boot the platform is to use the Boot.start(String name) method.

final World world = Boot.start("xoom-boot-world-name");

The last and simpler way is to annotate a clean Java class with @Xoom annotation:

@Xoom(name="xoom-boot-world-name")
public class AppInitializer {

}

As you can see, @Xoom does not require any method implementation because the annotation itself is sufficient to boot the application. Furthermore, you can add the blocking attribute to enable/disable synchronous actor messaging.

@Xoom(name="xoom-boot-world-name", blocking=true)
public class AppInitializer {

}

Keep in mind that the default value for blocking is false and, when used, @Xoom annotation attributes always override what has been set in xoom-turbo.properties. In other words, if the Initializer class is annotated with blocking=false and BlockingMailbox is enabled in the properties file, the @Xoomattribute prevails, causing actors to communicate asynchronously.

One of the many cool things about VLINGO XOOM, whether using the XOOM Turbo container or the other component APIs directly, is that it boots within a few milliseconds. How cool is that? And you know that everybody loves cool!

Now you are ready to use the World and any living part of it to explore the marvels of the platform.

Messaging

Messaging is accomplished the same simple way that it is with our standard platform environment. There are no surprises. Consider an example with a DeliveryProtocol.

public interface DeliveryProtocol {
  void reactTo();
  void reactTo(final int x, final int y, final int z);
  void reactTo(final String text);
  Completes<List<String>> reactions();
}

This protocol provides three command messages and a forth used for querying. The actor that provides this protocol can react in three ways: using no parameters, three integer parameters, and with one text string parameter. Here is an actor that implements this protocol.

public class DeliveryProtocolActor extends Actor implements DeliveryProtocol {
  private final List<String> reactions;

  public DeliveryProtocolActor() {
    this.reactions = new ArrayList<>();
  }

  @Override
  public void reactTo() {
    final String reaction = "reacting to no parameters";
    logger().debug(reaction);
    reactions.add(reaction);
  }

  @Override
  public void reactTo(final int x, final int y, final int z) {
    final String reaction = "reacting to: x=" + x + " y=" + y + " z=" + z;
    logger().debug(reaction);
    reactions.add(reaction);
  }

  @Override
  public void reactTo(final String text) {
    final String reaction = "reacting to: text=" + text;
    logger().debug(reaction);
    reactions.add(reaction);
  }

  @Override
  public Completes<List<String>> reactions() {
    logger().debug("reactions...");
    return completes().with(Collections.unmodifiableList(reactions));
  }
}

Focus on the first three reactTo() message handlers. This actor does just a few things when it receives each message type. It formats a string to indicate what happened. It logs that message through the standard io.vlingo.xoom.actors.Logger protocol that is available to all io.vlingo.xoom.actors.Actor extenders. Each of the message handlers appends the formatted text description to a List held by its state. This state is held so that a client of this actor can query for all its reactions.

That leads to the forth and last message handler, reactions(). It answers the full List resulting from the various reactTo() messages received. Note that it doesn't just answer the raw, mutable List. Instead it provides an immutable List, so that its state cannot be tampered with by anyone on the outside. In addition, it answers the immutable List as a Completes<T> outcome.

More detail may be read about Completes<T> here. In brief it is a means for asynchronous query operations being executed on separate threads to provide eventual answers to a requester. Of course, this actor is running within a World on VLINGO XOOM, and thus is asynchronous. Still, we don't change the entire platform API to accommodate use in a blocking environment. We want you to learn in comfort, but learn something new and experience the API in a safe haven.

Here is a test that shows a usage example.

final DeliveryProtocol protocol = world.actorFor(DeliveryProtocol.class, DeliveryProtocolActor.class);

protocol.reactTo();
protocol.reactTo(1, 2, 3);
protocol.reactTo("Hello, World!");

protocol.reactions().andThenConsume(reactions -> assertEquals(3, reactions.size()));

The test gets a reference from the World through which it may send messages to the actor that supplies the DeliveryProtocol.

Blocking Mailbox

Note that the above example of the DeliveryProtocolActor uses the configured default mailbox. This is so because the code using actorFor() doesn't pass a specific mailbox name, meaning that the default mailbox is used. You can configure VLINGO XOOM to default to the BlockingMailbox, by placing the following configuration in the xoom-actors.properties; note the line containing ...defaultMailbox = true

plugin.name.blockingMailbox = true
plugin.blockingMailbox.classname = io.vlingo.xoom.turbo.scooter.plugin.mailbox.blocking.BlockingMailboxPlugin
plugin.blockingMailbox.defaultMailbox = true

The test client of DeliveryProtocol then sends messages, each of the three types of reactTo() that can be sent. Finally, it asks the actor to answer its collected reactions by way ofCompletes<List<String>>. Note that the test client receives the outcome by using the andThenConsume(function). Inside this lambda an assertion is made that the List is expected to have three elements, one for each of the command messages sent.

All of the above is executed on a single thread; the thread that the test is running on.

Actor Request-Response

Here we discuss request-response from the perspective of one actor that sends a request message to a second actor, and that second actor sends a response as a message back to the first actor. Here are the protocols, with RequestProtocol being the first.

public interface RequestProtocol extends Stoppable {
  void request(final int value, final ResponseProtocol respondTo);
}

The RequestProtocol may receive a request() and respond to the second protocol by sending it a response(). After some expected outcome of request-response, the second protocol can be queried for a total.

public interface ResponseProtocol extends Stoppable {
  Completes<Integer> total();
  void response(final int value, final RequestProtocol requestOf);
}

The implementations of these two protocols are next.

public class RequestProtocolActor extends Actor implements RequestProtocol {
  @Override
  public void request(int value, ResponseProtocol respondTo) {
    respondTo.response(value + 1, selfAs(RequestProtocol.class));
  }
}

This RequestProtocolActor responds to the received request by adding 1 to the value it receives. The response actor receives a response and tracks the total until a desired outcome.

public class ResponseProtocolActor extends Actor implements ResponseProtocol, Stoppable {
  private final RequestProtocol requester;
  private int total;

  public ResponseProtocolActor(final RequestProtocol requester) {
    this.requester = requester;
    this.total = 0;
  }

  @Override
  public void start() {
    requester.request(total, selfAs(ResponseProtocol.class));
  }

  @Override
  public void response(final int value, final RequestProtocol requestOf) {
    if (value >= 10) {
      total = value;
    } else {
      requestOf.request(value + 1, selfAs(ResponseProtocol.class));
    }
  }

  @Override
  public Completes<Integer> total() {
    return completes().with(total);
  }
}

Note that the start() life cycle message is received just following construction. This is where the response actor starts the request-response process by sending a total of 0 to the request handler actor. The request-response continues until the response actor reaches a value of 10 or greater.

The following is a test that shows an example usage.

final RequestProtocol requestOf = world.actorFor(RequestProtocol.class, RequestProtocolActor.class);
final ResponseProtocol respondTo = world.actorFor(ResponseProtocol.class, ResponseProtocolActor.class, requestOf);

respondTo.total().andThenConsume(value -> assertTrue(10 <= value));

Other Tools

Explore the other tools available as part of the high-level XOOM components.

Tool

Description

XOOM Designer

Be guided into the Reactive DOMA and DDD world by the application and microservice designer and generator for the VLINGO XOOM components.

XOOM Annotations

Using a few lines of code, activate and configure platform components.

XOOM Scooter

An API for implementing Actors and DDD entities/aggregates with persistence using a familiar blocking paradigm, supporting stepwise adoption the our full reactive toolset.

PreviousEnd-to-End TestsNextAnnotations

Last updated