# Turbo
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](https://docs.vlingo.io/xoom-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.
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](https://docs.vlingo.io/xoom-turbo/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](https://docs.vlingo.io/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.
```markup
io.vlingo.xoom
xoom-turbo
x.y.z
compile
```
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.
```groovy
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 ](https://docs.vlingo.io/vlingo-xoom/xoom-starter)for generating your project. In case you prefer to create it manually, the [Actors documentation](https://docs.vlingo.io/vlingo-actors#using-the-vlingo-actors-properties-file) 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.
```java
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.
```java
final World world = Boot.start("xoom-boot-world-name");
```
The last and simpler way is to annotate a clean Java class with `@Xoom` annotation:
```java
@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.
```java
@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 `@Xoom`attribute 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`.
```java
public interface DeliveryProtocol {
void reactTo();
void reactTo(final int x, final int y, final int z);
void reactTo(final String text);
Completes> 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.
```java
public class DeliveryProtocolActor extends Actor implements DeliveryProtocol {
private final List 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> 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` outcome.
More detail may be read about `Completes` [here](https://docs.vlingo.io/xoom-common#completes). 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.
```java
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`
```java
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 of`Completes>`. 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.
```java
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.
```java
public interface ResponseProtocol extends Stoppable {
Completes total();
void response(final int value, final RequestProtocol requestOf);
}
```
The implementations of these two protocols are next.
```java
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.
```java
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 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.
```java
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](https://docs.vlingo.io/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](https://docs.vlingo.io/xoom-turbo/annotations) | Using a few lines of code, activate and configure platform components. |
| [XOOM Scooter](https://docs.vlingo.io/xoom-turbo/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. |