` expressions. The properties are now available on both sides of the test.
Again inside the `MockPersistResultInterest` create the code that handles writing to properties when it receives a notification of some persistence results. It uses a property writer to set the value atomically and inside a lock. You don't have to know the details of the implementation inside `AccessSafely`, only that thread-safe property access is handled for you.
```java
public void persistResultedIn(
final Outcome outcome,
final Object persistentObject,
final int possible,
final int actual,
final Object object) {
if (actual == 1) {
access.writeUsing("add", persistentObject);
} else if (actual > 1) {
access.writeUsing("addAll", persistentObject);
} else {
throw new IllegalArgumentException(...);
}
}
```
This ensures that a barrier/fence is placed around each data property so each property can be both written to and read from in a thread-safe manner. Here is a code snippet from the test that reads the properties to assert on its expectations.
```java
public void testThatObjectPersistsQuerys() {
final AccessSafely persistAllAccess = persistInterest.afterCompleting(1);
final Person person = new Person("Tom Jones", 85);
objectStore.persist(person, persistInterest);
final int persistSize = persistAllAccess.readFrom("size");
assertEquals(1, persistSize);
assertEquals(person, persistAllAccess.readFrom("object", 0));
...
}
```
This simple tool will prevent what may appear to be impossible data values as test outcomes.
### Routing and Routers
Routers offer a way to deliver a message to one or more other actors, according to a specified routing strategy. They allow you to decouple the source of a message from its destination and they function as a branching mechanism in the message channel between actors. Routers can be used to control and improve message throughput for a particular message protocol, to distribute workload among a pool of actors in a desirable way, or even both.
Based on it's routing strategy, a router will compute a "routing" which consists of an ordered list of one or more actors, referred to as "routees", to which a message will be dispatched for processing. The router may consider any state, including the message itself, in computing the routing.
#### Router Responsibilities
Routers have four main responsibilities:
1. Maintain the list of actors that are currently subscribed as routees
2. Support the subscribing and unsubscribing of routees
3. Computing a routing for a given message according to some routing logic
4. Dispatch messages to the actors who were selected to be members of the routing
#### Type Safety
Routers and routees are actors and, like all actors in vlingo, are type safe. Each will implement one or more messaging protocols (i.e., Java interfaces). A router and its routees must implement the same messaging protocol, though each may also implement other protocols that are not shared.
The `io.vlingo.xoom.actors.Router` and its abstract subclasses are generic types whose type parameter `` is the Java interface representing the message protocol implemented by the router and its routees:
```java
public abstract class Router
extends Actor
```
#### Provided Routers
XOOM Actors provides several kinds of routers out-of-the-box that are mainly distinguished by the routing strategy they employ:
* `io.vlingo.xoom.actors.BroadcastRouter` - dispatches every message to every routee
* `io.vlingo.xoom.actors.ContentBasedRouter` - considers the content of the message in choosing which routee to dispatch the message to
* `io.vlingo.xoom.actors.RandomRouter` - dispatches each message to a random one of the routees
* `io.vlingo.xoom.actors.RoundRobinRouter` - dispatches each message to the next routee, in turn
* `io.vlingo.xoom.actors.SmallestMailboxRouter` - dispatches each message to the routee with the least number of messages in its mailbox at the time
Each of these routers is provided as an abstract class that extends `io.vlingo.xoom.actors.Router` (which extends `io.vlingo.xoom.actors.Actor`).
It is possible, of course, to implement your own new kind of router by directly extending `io.vlingo.xoom.actors.Router`.
#### Routee Subscription
Routees must be subscribed to a router before they can be dispatched any messages. There are two approaches for subscribing routees:
* Automatically during router initialization
* Explicitly after router initialization
Automatic routee subscription is accomplished by passing a `io.vlingo.xoom.actors.RouterSpecification` with a non-zero initial pool size to your router's constructor. For more information , see the *Creating a Router: Construction and Routee Pool Initialization* section below.
Explicit routee subscription requires the router to expose the subscription (and unsubscription) protocol as a public method(s). Since all the routees must comply with the messaging protocol, create an interface providing the type safe subscription protocol, for example:
```java
public interface InvoiceSubmitterSubscription {
void subscribe(InvoiceSubmitter submitter);
void unsubscribe(InvoiceSubmitter submitter);
}
```
The router then needs to implement this interface, self-delegating to the protected `subscribe(Routee)` and `unsubscribe(Routee)` methods defined in the `io.vlingo.xoom.actors.Router` superclass:
```java
public class InvoiceSubmissionRouter extends ..... impements InvoiceSubmitterSubscription, ...{
public void subscribe(InvoiceSubmitter submitter) {
subscribe(Routee.of(submitter));
}
public void unsubscribe(InvoiceSubmitter submitter) {
unsubscribe(Routee.of(submitter));
}
}
```
#### Route Computation
The `io.vlingo.xoom.actors.Router` class provides a set of route computation methods:
```java
Routing routingFor(final T1 routable1)
Routing routingFor(final T1 routable1, final T2 routable2)
Routing routingFor(final T1 routable1, final T2 routable2, final T3 routable3)
Routing routingFor(final T1 routable1, final T2 routable2, final T3 routable3, final T4 routable4)
```
Most types of routers do not base routing decisions on the message being routed because their routing logic is more mechanical (e.g., round robin) or is based on the state of the routees (e.g., smallest mailbox).
For this reason, the default implementation of the above four route computation methods simply self-delegates to the method:
```java
protected abstract Routing
computeRouting();
```
You will find that each subclass of `io.vlingo.xoom.actors.Router` will provide a concrete implementation of this method that encodes its particular routing strategy logic.
The exception is `io.vlingo.xoom.actors.ContentBasedRouter` for which, by definition, the routing logic depends on the specific message being routed. For this reason, `ContentBasedRouter` implements `computeRouting()` to throw `java.lang.UnsupportedOperationException`. Instead, you will need to override one of the `routingFor()` methods listed above and encode your routing logic there.
#### Router Message Dispatching
As noted previously, one of the responsibilities of routers is to dispatch messages to the actors that were selected as routees. The abstract class `io.vlingo.xoom.actors.Router` provides two sets of message dispatching protocol:
* Command dispatching
* Query dispatching
The **command dispatching** protocol is used to dispatch messages that may have arguments but *do not* have a return value, for example `void submitInvoice(Invoice)`:
```java
void dispatchCommand(final BiConsumer action, final T1 routable1)
void dispatchCommand(final TriConsumer action, final T1 routable1, final T2 routable2)
void dispatchCommand(final QuadConsumer action, final T1 routable1, final T2 routable2, final T3 routable3)
void dispatchCommand(final PentaConsumer action, final T1 routable1, final T2 routable2, final T3 routable3, final T4 routable4)
```
The command dispatching methods take a Consumer (function) as the first argument, and then from 1 to 4 objects that will be the arguments to the Consumer function. These objects map to the arguments of the messaging protocol method.
The **query dispatching** protocol is used to dispatch messages that may have arguments and *do* return a value, for example `Price computePrice(ProductID, CustomerID)`:
```java
> R dispatchQuery(final BiFunction query, final T1 routable1)
> R dispatchQuery(final TriFunction query, final T1 routable1, final T2 routable2)
> R dispatchQuery(final QuadFunction query, final T1 routable1, final T2 routable2, final T3 routable3)
> R dispatchQuery(final PentaFunction query, final T1 routable1, final T2 routable2, final T3 routable3, final T4 routable4)
```
The query dispatching methods take a Function as the first argument, and then from 1 to 4 objects that will be the arguments to the Function. These objects map to the arguments of the messaging protocol method.
#### Implementing a Router in Your Application
Implementing a router in your application is straight forward. You'll need to:
* Create the message protocol that your router and routees will support as a Java interface
* Create your routee actor
* Create your router actor by extending one of the abstract subclasses of `io.vlingo.xoom.actors.Router`
*Create the Message Protocol*
As an example, let's say you are implementing an invoice submission process and there are several ERP systems to which any given invoice might need to be submitted. Your router will route each Invoice to one of several `InvoiceSubmitter` actors, each of which represents a particular ERP system. The selected routing will likely depend on information in the Invoice itself (e.g., customer ID).
To support this scenario, you might design the following protocol:
```java
public interface InvoiceSubmitter {
void submitInvoice(Invoice invoice);
}
```
*Create the Routee Actor(s)*
Now that you have the `InvoiceSubmitter` protocol defined, you can create the actor(s) to which your router will route messages. These actors will be the ones actually doing the work, in our case submitting an Invoice to a specific ERP system.
Let's assume ERP systems in your company are named after Greek mythological gods, such as Apollo and Atlas, and that for various reasons you decide to create a different actor per ERP system.
Here is the rough definition of the actor for the Apollo ERP invoice submission:
```java
public class ApolloInvoiceSubmitter extends Actor implements InvoiceSubmitter {
public void submitInvoice(Invoice invoice) {
//do some work here
}
}
```
Your actor for Atlas and other ERPs would have a similar structure but different logic in their `submitInvoice` methods.
*Create a Router: Extending a Built-in Router*
As noted above, XOOM Actors provides a number of built-in implementations of `io.vlingo.xoom.actors.Router` that you can extend.
In the example, the routing will be *content-based*, because the router will use information from the message itself (e.g., the customer ID of the Invoice) to select which ERP-specific routee to dispatch the message to. Thus, t will extend `io.vlingo.xoom.actors.ContentBasedRouter`:
```java
public class InvoiceSubmissionRouter
extends ContentBasedRouter
implements InvoiceSubmitter {
...
}
```
*Creating a Router: Construction and Routee Pool Initialization*
The `io.vlingo.xoom.actors.Router` class requires that a `io.vlingo.xoom.actors.RouterSpecification` be provided as a constructor argument and offers subclasses an opportunity to get involved in the initialization of the routee pool:
```java
public Router(final RouterSpecification specification) {
this.routees = new ArrayList>();
initRoutees(specification);
}
```
By default, the information in the `RouterSpecification` will be used to create an initial (possibly empty) pool of routee actors as child actors of the router actor. Subclasses may customize that behavior by overriding `initRoutees(RouterSpecification)`.
Often, your concrete router class can make these decisions for itself by implementing a constructor that supplies them. For example:
```java
public OrderRouterActor(final int poolSize) {
super(
new RouterSpecification(
poolSize,
Definition.has(OrderRouterWorker.class, Definition.NoParameters()),
OrderRouter.class)
);
}
```
*Creating a Router: Routing Logic*
In the [Route Computation](/xoom-actors#route-computation) section above, we learned that subclasses of `io.vlingo.xoom.actors.ContentBasedRouter` need to override one of the `routingFor()` methods inherited from `io.vlingo.xoom.actors.Router` and implement the routing logic there. The `routingFor()` method variants provide access to the message arguments so that the router can inspect that information as part of its routing logic.
In our example, the message protocol `void submitInvoice(Invoice invoice)` has a single argument, so we can override the single-argument `routingFor()` method:
```java
@override
protected Routing routingFor(final T1 routable1) {
Invoice invoice = (Invoice) routable1;
InvoiceSubmitter submitter = selectERPInvoiceSubmitter(invoice.customerID);
return Routing.with(submitter);
}
private InvoiceSubmitter selectERPInvoiceSubmitter(CustomerID customerID) {
//select one of the subscribed InvoiceSubmitter actors based on CustomerID
}
```
Note that both `InvoiceSubmissionRouter` and `ERPInvoiceSubmitter` implement the `InvoiceSubmitter` interface, thereby establishing the type safe messaging protocol that they share, which allows the router to forward messages to the routees in a type safe way.
*Creating a Router: Dispatching*
Implementing dispatching logic requires implementing the message protocol and calling one of the methods discussed in the [Router Message Dispatching](/xoom-actors#router-message-dispatching) section above.
The `InvoiceSubmitter` protocol declares the one-argument command method `void submitInvoice(Invoice)`, so we we need to provide an implementation that calls the `dispatchCommand` method inherited from `io.vlingo.xoom.actors.Router` that accommodates one argument:
```java
protected void dispatchCommand(final BiConsumer action, final T1 routable1)
```
Notice that the first argument to each `dispatchCommand` (and `dispatchQuery`) method is a function. XOOM Actors supplies variants of these dispatching methods for 1 to 4 arity functions. Any lambda expression matching the signature of the dispatching method can be passed.
Here, then, is the dispatching logic of our `InvoiceSubmissionRouter`:
```java
@Override
public void submitInvoice(final Invoice invoice) {
dispatchCommand(InvoiceSubmitter::submitInvoice, invoice);
}
```
In the implementation above, we take advantage of the fact that Java method references are shorthand for lambda expressions that call the same method - in this case the `void submitInvoice(Invoice)` method of `InvoiceSubmitter`.
*Creating a Router: Subscribing Routees*
As noted in the "*Creating a Router: Construction and Routee Pool Initialization*" section above, one easy way of subscribing routees is to pass a `RouterSpecification` with a non-zero initial pool size to your router's constructor. The actor `Definition` in the `RouterSpecification` will be used by your router to create and subscribe a number of child actors that implement your routing message protocol. This approach works well when the routees can all be instances of the same class.
Sometimes, such as in our invoice submission example, the routees need to be instances of different classes that all implement the same message protocol. In our example, the `InvoiceSubmitter` actors for the Apollo and Atlas ERPs were implemented as different classes. In such cases, actors need to be explicitly subscribed to the router. This requires the router to provide public un/subscription protocol, as described in the [Routee Subscription](/xoom-actors#routee-subscription) section above.
# HTTP (REST and RPC)
The embeddable HTTP server for Reactive REST backed by XOOM Actors and XOOM Wire.
## Reactive REST
The XOOM HTTP component supports reactive, scalable, and resilient HTTP servers and REST services running as a small, fast, embedded server*.* Thus, this component does not run standalone, but is meant to provide very lightweight and high-performing HTTP support within a application- or microservice-based runtime, such as a Bounded Context. The server supports REST and RPC dispatching to implementations of fluent APIs.
{% hint style="info" %}
It is common for developers to think of REST over HTTP in terms of CRUD because the primary methods provided by the protocol are: POST, GET, PUT, and DELETE. If taken at face value, these verbs are CRUD through and through. Yet, almost no one uses the methods to map directly from browser to a database. Most contemporary applications instead map the HTTP methods to procedures (i.e. a method on a Java or C# class) within the application. Those procedures are responsible for adapting path parameters, headers, and the request body to a form that can be consumed by the inner application components.
The procedure to which the HTTP request is mapped need not represent a CRUD operation at all. When you consider that POST, GET, PUT, DELETE, and others such as PATCH, are *message categories that map to procedures,* not only ways to perform CRUD operations on data, it makes for a lot more flexibility in how HTTP can be used.
For example, a POST method would always be used with the intention to *create* some entity resource, such as a product; that is, POST is in the procedure category of creation. Yet, there is no reason for the procedure to which that HTTP request is mapped to be named `postProduct()` or even the "obvious" `createProduct()`. Instead, the procedure could be named something more in line with the language spoken by the business, such a `catalogProduct()`. Here *catalog* is used as a verb; that is, our company is not in the business of creating new products. The products come to the company already created by a manufacturer. Our company *sells products through catalogs.* For us, products need to be *cataloged* (verb) for them to be accessible for purchase through a *catalog* (noun). With that in mind, *establishing a new kind of catalog for a kind of product* might be thought of as *defining a catalog.* Thus, the procedure would be named `defineCatalog()`.
Given this line of reasoning, the ways that HTTP methods are mapped are virtually unlimited, and all the while still honoring the REST way of doing things. The older SOAP protocol used to implement RPC-based APIs, was known to those who could cut through the jargon as "XML over HTTP." Thus, if XML over HTTP can be used to implement RPC, certainly it stands to reason that JSON over HTTP could be used in the same way.
The following sections demonstrate the flexibility of using HTTP as a means to support far more than CRUD. Avoid pedantic opinions that limit creativity. Such opinions are generally held by those who think only in terms of technology and expect the business to speak their language, which is composed mostly of CRUD and collection-oriented (add, insert, remove) terminology.
{% endhint %}
Consider the overall architecture of our HTTP server. It is highly Reactive by employing actors at every major operational junction.
REST over HTTP is quite commonly employed to support user interfaces, service integrations, and even distribution of event streams. Of course, we don't suggest that your services should be primarily REST-based, we provide our HTTP server for when REST it is useful. Even RPC can be supported. See the above information box. Since REST over HTTP is the most common contemporary use case, the documentation mostly refers to REST rather than RPC, but everything herein is equally applicable to RPC using the style discussed in the above information box.
### Use With Domain-Driven Design Context Mapping Patterns
With any use of the XOOM HTTP server, which might be with a REST flavor as more so as RPC, the use of a few Domain-Driven Design patterns are common. Among the *Context Mapping* patterns, the *Open-Host Service* and *Published Language* patterns naturally support these API styles. The *Open-Host Service* is the well defined API that is open for public use, with the possible requirement of client credentials. The *Published Language* is the REST resources or RPC response values that are provided.
## Overview
Our HTTP component can help you create REST-based services rapidly and with great simplicity. One glance at the REST request mappings to Java objects is all it takes to understand this. The following demonstrates both file-based and code-based fluent request handler mappings.
```java
action.user.register.method = POST
action.user.register.uri = /users
action.user.register.to = register(body:sample.user.UserData userData)
action.user.contact.method = PATCH
action.user.contact.uri = /users/{userId}/contact
action.user.contact.to = changeContact(String userId, body:sample.user.ContactData contactData)
```
The above declarations are made in the `vlingo-http.properties` file. The following is the resource handler implementation to match it.
```java
public class UserResource extends ResourceHandler {
public void register(final UserData userData) {
final User user =
User.from(
Name.from(userData.nameData.given, userData.nameData.family),
Contact.from(userData.contactData.emailAddress, userData.contactData.telephoneNumber));
repository.save(user);
completes().with(Response.of(Created, headers(of(Location, userLocation(user.id))), serialized(UserData.from(user))));
}
public void changeContact(final String userId, final ContactData contactData) {
final User user = repository.userOf(userId);
if (user.doesNotExist()) {
completes().with(Response.of(NotFound, userLocation(userId)));
return;
}
final User changedUser = user.withContact(new Contact(contactData.emailAddress, contactData.telephoneNumber));
repository.save(changedUser);
completes().with(Response.of(Ok, serialized(UserData.from(changedUser))));
}
}
```
By means of the `ResourceHandler` base class, there are several Request parts available: URI, headers, body, and any query parameters. You may also access the default `ContentType`, which may be overridden. See the following `queryUsers()` handler method.
```java
public Completes queryUsers() {
final String page = context().request().queryParameters().valuesOf("page");
final String contentType = context().contentType();
...
}
```
The above is from file-based request/response resource mappings defined in the properties file`vlingo-http.properties`. Yet, our versatile API also supports fluent mappings in source code.
```java
public class UserResource {
...
public Resource routes() {
return resource("User Resource",
post("/users")
.body(UserData.class)
.handle(this::register),
patch("/users/{userId}/contact")
.param(String.class)
.body(ContactData.class)
.handle(this::changeContact));
}
}
```
In the above example only the `routes()` is shown, and would replace the file-based route mappings previously shown. Also note in this example, when using the fluent routes API your resource class should not extend `ResourceHandler`. Although you may do so, at time of execution its state will be hollow because the runtime does not support `ResourceHandler`. Instead, to get similar base class state and behavior with dynamic resources created with the fluent API, use the optional `DynamicResourceHandler`.
```java
public class UserResource extends DynamicResourceHandler {
private static final AtomicInteger nextId = new AtomicInteger(0);
private final int id;
public UserResource(final Stage stage) {
super(stage);
this.id = nextId.incrementAndGet();
logger().info("UserResource: Pooled instance created: " + this.id);
}
public Completes register(final UserData data) {
final String userType = context().request().queryParameters().valuesOf("userType");
final String contentType = context().contentType();
...
}
...
@Override
public Resource routes() {
logger().info("UserResource: wiring resources for: " + this.id);
return resource("User Resource", this,
post("/users")
.body(UserData.class)
.handle(this::register),
patch("/users/{userId}/contact")
.param(String.class)
.body(ContactData.class)
.handle(this::changeContact));
}
}
```
By extending `DynamicResourceHandler` your resource may use the `Stage` managing this resource, the `Logger` and `Scheduler` of that `Stage`, and the `Context` with the current `Request`. The `Request` provides various request parts such as the URI, headers, body, and any query parameters. You may also access the default `ContentType`, which may be overridden. See the `register(UserData)` handler method for an example accessing the query parameters and `ContentType`.
{% hint style="info" %}
Query parameters may be mapped more naturally using the fluent API as seen [below](https://docs.vlingo.io/vlingo-http#query-parameters).
{% endhint %}
The concrete resource handler must provide a `Stage` to the `DynamicResourceHandler` constructor. It is assumed that the concrete resource handler's constructor will take at least the `Stage` as a parameter. The `DynamicResourceHandler` declares the `routes()` method abstract, so it must be overridden in the concrete extender. As you can see above, `routes()` returns `resource()`with an optional parameter of the `DynamicResourceHandler` as the`this` object, which is to be given the current request `Context` before each handler invocation.
In the following sections you will learn how to quickly set up and start your server with resources handlers.
## Setting Up the Server
If you will use the file-based configuration you must create `vlingo-http.properties`. Otherwise you will write source code to define the server configuration. First the file-based configuration is explained, and then the source code and fluent API approach.
### File-Based Configuration
Create the file `vlingo-http.properties` and place it into the project directory hierarchy used for resources. For Maven that would be `src/main/resources` for production and if you are defining the properties for test, it would be `src/test/resources`. In this file create the following properties. Your values may differ.
```java
#=====================================
# server
#=====================================
server.http.port = 8080
server.dispatcher.pool = 10
server.buffer.pool.size = 100
server.message.buffer.size = 65535
server.probe.interval = 10
server.probe.timeout = 2
server.processor.pool.size = 10
server.request.missing.content.timeout = 100
#=====================================
# generated resource dispatchers
#=====================================
resource.dispatcher.generated.sources.main = target/generated-sources/
resource.dispatcher.generated.sources.test = target/generated-test-sources/
resource.dispatcher.generated.classes.main = target/classes/
resource.dispatcher.generated.classes.test = target/test-classes/
```
This is the basic minimum configuration necessary to start the server. There are other properties that you will learn about later. The following summarizes these properties.
1. **`server.http.port`**: the socket port to be used by the server, which here is 8080.
2. **`server.dispatcher.pool`**: the server uses a pool of actors to dispatch incoming requests asynchronous. Here the dispatcher pool size is 10.
3. **`server.buffer.pool.size`**: used by the server to create a pool of reusable ByteBuffer instances to use for incoming requests and outgoing resources. There will be at least 100 buffers in this pool. Yet, the elastic pool design enables it to grow dynamically under heavy load and contract back down to 100 buffers as load diminishes.
4. **`server.message.buffer.size`**: used by the server when creating the buffer pool to allocate each buffer with this many bytes. Here the buffers will each be 65,535 bytes. (a) This does not limit the overall size of a given incoming message because these may be read in chunks and span multiple buffers. (b) This also does not limit the size of outgoing responses because a non-pooled buffer will be temporarily allocated to send payloads larger than this maximum. Serving larger responses should be the exception rather than common, otherwise performance will suffer. If a common occurrence consider setting this buffer limit to the largest common payload size.
5. **`server.probe.interval`**: determines the number of milliseconds between each socket channel probe to receive new connections and requests, and to send new responses. Be careful with this value as various O/S and JDKs deal differently with intervals, possibly being too fast to too slow.
6. **`server.probe.timeout`**: the amount of time in milliseconds that the socket channel probe will wait for new connections and requests, and to check for writable status used for sending responses. Be careful with this value as when there are no new requests, it causes the actor's thread to block inside the socket channel probe until this timeout is reached.
7. **`server.processor.pool.size`**: used by the server to size the pool of socket channel processors. Here the processor pool size is 10. There will be 10 total actors created and used in round-robin order as new connections are accepted, which will each read from and write to every newly accepted client socket channel connection.
8. **`server.request.missing.content.timeout`**: as previously indicated, very large incoming request messages of byte length greater than `server.message.buffer.size` will require spanning two or more total buffers. This value indicates how long the incomplete message will be retained in the server before it is considered a bad request (missing bytes). This example indicates that such an incomplete request may be retained for a maximum of 100 milliseconds in anticipation of remaining bytes being received.
9. **`resource.dispatcher.generated.sources.???`**: These four properties define where generated source code is to be saved as Java source files and where class files are save after dynamic compilation. This example uses the Maven target layout and defines both main and test areas.
In addition to this, it only makes sense to include the description of at least one resource handler (a.k.a. endpoint or controller).
```java
#=====================================
# user resources
#=====================================
resource.name.user = [register, contact, name, queryUser, queryUsers, queryUserError]
resource.user.handler = io.vlingo.xoom.http.sample.user.UserResource
resource.user.pool = 10
resource.user.disallowPathParametersWithSlash = true
action.user.register.method = POST
action.user.register.uri = /users
action.user.register.to = register(body:io.vlingo.xoom.http.sample.user.UserData userData)
action.user.contact.method = PATCH
action.user.contact.uri = /users/{userId}/contact
action.user.contact.to = changeContact(String userId, body:io.vlingo.xoom.http.sample.user.ContactData contactData)
action.user.name.method = PATCH
action.user.name.uri = /users/{userId}/name
action.user.name.to = changeName(String userId, body:io.vlingo.xoom.http.sample.user.NameData nameData)
action.user.queryUser.method = GET
action.user.queryUser.uri = /users/{userId}
action.user.queryUser.to = queryUser(String userId)
action.user.queryUsers.method = GET
action.user.queryUsers.uri = /users
action.user.queryUsers.to = queryUsers()
action.user.queryUserError.method = GET
action.user.queryUserError.uri = /user/{userId}/error
action.user.queryUserError.to = queryUserError(String userId)
```
This is a more complete resource routing definition. The properties are summarized next.
1. **`resource.name.{name}`**: The first property of any resource handler is the name, which above is `resource.name.user`. This says, here is a resource named `user`. The property's value is an array of method names that are used as individual route request handlers. Each of these names must have a corresponding set of `action.{name}...` properties, which are documented in a following numbered descriptions. If you do not list a name in this array for every route request handler, the corresponding handler action definition will not be found for the missing name.
2. All properties associated with the named resource are in the form *`resource.name.property`*, such as `resource.user.handler`.
3. **`resource.{name}.handler`**: the fully-qualified class name of the concrete `ResourceHandler` extender. The server will dispatch to actions matching the URI patterns to the methods in this `ResourceHandler`. The above example references the `UserResource`, but along with it's package name.
4. **`resource.{name}.pool`**: used to create a pool of actors for `ResourceHandler` instances of the type defined by the `resource.{name}.handler` property. Individual requests are handled in a round-robin fashion. In this example the `resource.user.pool` defines a pool size of 10. Note that this pool is created for each `server.dispatcher.pool`, meaning that there will be a total of `server.dispatcher.pool` \* `resource.name.pool` actors to handle requests to this named resource.
5. **`resource.{name}.disallowPathParametersWithSlash`**: deprecated and must always be `true`. Above is for the resource named `user`, as in `resource.user.disallow...`
6. **`action.{name}.{endpoint}.method`**: used to define the HTTP method to be used to make a matching request to the given URI. Here `{name}` and `{endpoint}` are placeholders for the actual names. In the first example above `{name}` is `user` and the `{endpoint}` method is `register`. Note that this property's value may be one of: `POST`, `GET`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `TRACE`, `OPTIONS`, or `CONNECT`.
7. **`action.{name}.{endpoint}.uri`**: used to define the URI that will map to the given endpoint. Here `{name}` and `{endpoint}` are placeholders for the actual names. In the first example above `{name}` is `user` and the `{endpoint}` method is `register`. Path parameters, if any, are surrounded by curly braces, such as in `/users/{userId}/contact`, where the parameter name is `userId`. In the actual URI, userId must be replaced with some sort of identity, such as may be mapped to a `String` value.
8. **`action.{name}.{endpoint}.to`**: used to define the method name and signature to which this route mapping will dispatch to on the given `resource.{name}.handler` class instance. Here `{name}` and `{endpoint}` are placeholders for the actual names. In the first example above `{name}` is `user` and the `{endpoint}` method is `register`. When the HTTP method is `POST` and the URI is `/users` then the match will route to the given Java method, such as `register(UserData userData)`. In the above example the `body:` keyword indicates that the `UserData` will be found in the request body. Depending on the content type, which is by default JSON, the body will be automatically deserialized into an instance of the given type, such as `UserData`. Note that when the URI contains one or more path parameters, the `{paramName}` will be mapped to the matching Java method parameter with the same name, and automatically deserialized into the given Java parameter type. In the above example the `/users/{userId}/contact` maps to the Java method parameter `String userId`.
When using the file-based configuration there is no limit to the number of path parameters. However, the greater the number of parameters the more complex the Java method will be to create and maintain.
It is quite simple to start a server from file-based configuration.
```java
final World world = World.startWithDefaults("server");
final Server server = Server.startWith(world.stage());
```
Using the above examples, this `Server` is started on port 8080 and has a single resource handler, `UserResource`. The remaining properties are applied to the server as previously explained.
{% hint style="info" %}
The `ResourceHandler` and `DynamicResourceHandler` base classes provide access to several request parts, such as headers, query parameters, and other environmental objects.
{% endhint %}
#### Provided By `ResourceHandler` and `DynamicResourceHandler`:
| **Type Accessor** | **Description** |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Context context()` | The Context type provides numerous details. This contains the Request, which in turn contains Method, URL, Version, Headers, and Body. This gives you access to all parts of the request.
|
| `ContentType contentType()` | The details about the content type of the request. (only on `ResourceHandler`) |
| `Logger logger()` | The means to log debug, error, and informational messages. |
| `Scheduler scheduler()` | Use to manage the scheduling of future tasks. |
| `Stage stage()` | The `Stage` of this request. |
### Source Code Configuration
The following provides a very simple example of source code configuration along with the XOOM HTTP fluent route mapping API. This provides the minimum code to create an endpoint that responds with `"Hello, World!"`. Both Java and Kotlin examples are available. The tutorial descriptions refer to the Java code.
Create a new project with your favorite editor/IDE and create a `Bootstrap` class with the following content.
{% tabs %}
{% tab title="Java" %}
{% code title="Bootstrap.java" %}
```java
import io.vlingo.xoom.actors.World;
import io.vlingo.xoom.common.Completes;
import io.vlingo.xoom.http.Response;
import io.vlingo.xoom.http.resource.Configuration.Sizing;
import io.vlingo.xoom.http.resource.Configuration.Timing;
import io.vlingo.xoom.http.resource.Resource;
import io.vlingo.xoom.http.resource.Resources;
import io.vlingo.xoom.http.resource.Server;
import static io.vlingo.xoom.http.resource.ResourceBuilder.get;
import static io.vlingo.xoom.http.resource.ResourceBuilder.resource;
public class Bootstrap {
private final static int PORT = 8080;
private static Bootstrap instance;
public final Server server;
public final World world;
private Bootstrap() {
this.world = World.startWithDefaults("hello world example java");
final Resources resources = Resources.are(helloWorldResource());
this.server =
Server.startWith(
world.stage(),
resources,
PORT,
Sizing.define(),
Timing.define());
}
private Resource helloWorldResource() {
return resource("Hello World",
get("/helloworld")
.handle(() -> withSuccess(of(Ok, "Hello, World!")))
);
}
public static final Bootstrap instance() {
if (instance == null) {
instance = new Bootstrap();
}
return instance;
}
public static void main(final String[] args) throws Exception {
System.out.println("=========================================");
System.out.println("service: started at http://localhost:" + Bootstrap.PORT);
System.out.println("try: curl http://localhost:" + Bootstrap.PORT + "/helloworld");
System.out.println("=========================================");
Bootstrap.instance();
}
}
```
{% endcode %}
{% endtab %}
{% tab title="Kotlin" %}
{% code title="Bootstrap.kt" %}
```kotlin
import io.vlingo.actors.World
import io.vlingo.common.Completes.withSuccess
import io.vlingo.http.Response.of
import io.vlingo.http.Response.Status.Ok
import io.vlingo.http.resource.Configuration.Sizing
import io.vlingo.http.resource.Configuration.Timing
import io.vlingo.http.resource.Resource
import io.vlingo.http.resource.ResourceBuilder.get
import io.vlingo.http.resource.ResourceBuilder.resource
import io.vlingo.http.resource.Resources
import io.vlingo.http.resource.Server
class Bootstrap {
private val world = World.startWithDefaults("hello world example kotlin")
private val server: Server
init {
val resources = Resources.are(helloWorldResource())
server = Server.startWith(world.stage(),
resources,
PORT,
Sizing.define(),
Timing.define())
}
private fun helloWorldResource(): Resource<*> {
return resource("hello world resource",
get("/helloworld")
.handle { withSuccess(of(Ok, "Hello World")) })
}
companion object {
const val PORT = 8080
}
}
fun main(args: Array) {
println("=========================================")
println("service: started at http://localhost:" + Bootstrap.PORT)
println("check out http://localhost:" + Bootstrap.PORT + "/helloworld")
println("=========================================")
Bootstrap()
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
Compile and run the server by means of the Java `main()` method. Check the results by running the following command-line.
```bash
> curl http://localhost:8080/helloworld
```
The `curl` command should print the following text into the terminal window: `Hello, World!`
{% hint style="info" %}
The `Server` logs informational output by means of the `World` standard `Logger` configuration.
{% endhint %}
The `Resources`(23) is the set of HTTP endpoints, which in this case is only one. The `Server` instance (25) is where the `Resources` are held and used to match and dispatch on requests. To start a `Server` you simply provide a `Stage` and the `Resources`. When created, the `Server` starts listening on port 8080 for HTTP requests.
`Sizing` (30) is the configuration parameter with the *processor pool size, dispatcher pool size, max buffer pool size,* and *max message size*. `Timing` (31) is the configuration with the *probe interval* and *timeout* parameters. For now, we use the default configuration.
{% hint style="warning" %}
The next sections use the previous code as starting point.
{% endhint %}
### Configuring Special Features
There are some additional features available through configuration: static file resources, server-sent events, and feed resources.
#### Static File Resources
Static file resources are ordinary content in disk files, such as HTML, images, and video. To serve static file resources use the `vlingo-http.properties` file-based configuration.
```
#=====================================
# static file resources
#=====================================
static.files.resource.pool = 5
static.files.resource.root = /siteroot/content
static.files.resource.subpaths = [/, /css, /js, /views]
```
This configuration auto-creates `io.vlingo.xoom.http.resource.StaticFilesResource` that serves files from the resource root `/siteroot/content` directory structure. Any request URI that begins with the `static.files.resource.subpaths` list will be served.
| Virtual URI | Physical URI |
| --------------- | -------------------------------- |
| `/{file}` | `/siteroot/content/{file}` |
| `/css/{file}` | `/siteroot/content/css/{file}` |
| `/js/{file}` | `/siteroot/content/js/{file}` |
| `/views/{file}` | `/siteroot/content/views/{file}` |
#### Server-Sent Events (SSE)
You may create a pre-packaged SSE resource using the following configuration.
```
#=====================================
# server-sent events
#=====================================
sse.stream.name.all = /eventstreams/all
sse.stream.all.feed.class = io.vlingo.xoom.http.sample.user.AllSseFeedActor
sse.stream.all.feed.payload = 50
sse.stream.all.feed.interval = 1000
sse.stream.all.feed.default.id = -1
sse.stream.all.pool = 10
```
This enables clients to register for a long-lasting stream of events from the server. The URI used by clients is the value of `sse.stream.name.{name}`. In the above example the name is `all` and the URL is `/eventstreams/all`.
The `sse.stream.all.feed.class` is provided by the custom service/application, and in this case is `io.vlingo.xoom.http.sample.user.AllSseFeedActor`. The fully-qualified class name must be given. There may be up to 50 events in a single feed (one send to a client) with an interval of 1,000 milliseconds between feeds. If the client does not provide an id for the starting event, the `default.id` is used. In this case it is -1. There will be 10 total feed instances created in the pool.
A client makes a request to subscribe, such as the following.
```java
Client client = Client.using(Configuration.defaultedKeepAliveExceptFor(...), ...);
Request subscribe =
Request
.method(Method.GET)
.uri("/eventstreams/all")
.and(RequestHeader.host("StreamsRUs.co"))
.and(RequestHeader.accept("text/event-stream;charset=utf-8"));
client
.requestWith(subscribe)
.andThenConsume(response -> {
switch (response.status) {
case Ok:
processEvents(response);
break;
default:
logger().error("Unexpected: " + response.status);
break;
}
})
.repeat();
```
In the above example the asynchronous `io.vlingo.xoom.http.resource.Client` will continue to receive responses as feeds occur because it is configured for *keep-alive* mode and tells the `Completes` to `repeat()` after every feed is received.
The following is a skeleton of class `AllSseFeedActor`.
```java
public class AllSseFeedActor extends Actor implements SseFeed {
public AllSseFeedActor(final String streamName, final int feedPayload, final String feedDefaultId) {
...
}
@Override
public void to(final Collection subscribers) {
...
}
}
```
In the above example the custom feed actor is class `AllSseFeedActor`, which must extend `Actor` and implement `io.vlingo.xoom.http.resource.sse.SseFeed`. See the `io.vlingo.xoom.http.resource.sse.SseStreamResource` that manages the feed generation process, using the custom `SseFeed` actor when needed.
The feed must follow the [SSE standard definition](https://www.w3.org/TR/eventsource/). The following is one example, but not the only possibility.
```java
event: SecurityTokenIssued
data: {"username": "jclifford", "token": "je;se9727anndnds!@"}
event: SecurityTokenIssued
data: {"username": "l.mary", "token": "l9928**)^^322nand$"}
event: SecurityTokenIssued
data: {"username": "camerontyrone", "token": "pdpjehrhfks'//&dh+a"}
```
There is a complete example in the [`xoom-http-frontservice`](https://github.com/vlingo/xoom-examples/tree/master/xoom-http-frontservice) and [`xoom-http-backservice`](https://github.com/vlingo/xoom-examples/tree/master/xoom-http-backservice) in the Github repository [vlingo/xoom-examples](https://github.com/vlingo/xoom-examples).
#### Feed Resources
There is another kind of feed resource, one that is not a SSE stream, but has similar characteristics. It is a stream of any kind and defines its own response body payload. You might think of such as Atom feeds, or similar.
```
#=====================================
# feed resources
#=====================================
feed.resource.name.events = /feeds/events
feed.resource.events.producer.class = io.vlingo.xoom.http.resource.feed.EventsFeedProducerActor
feed.resource.events.elements = 20
feed.resource.events.pool = 10
```
The feed has a name, in this case `feed.resource.name.events`, which is the URI `/feeds/events`. Clients may request a feed region by providing an id. The `...elements` property indicates the maximum number of 20 elements may be in a given feed. There will be 10 total feed instances created in the pool.
```java
public class EventsFeedProducerActor extends Actor implements FeedProducer {
...
@Override
public void produceFeedFor(final FeedProductRequest request) {
...
}
}
```
In the above example the custom feed actor is class `EventsFeedProducerActor`, which must extend `Actor` and implement `io.vlingo.xoom.http.resource.feed.FeedProducer`. The format of the feed itself is not standardized, but may be JSON, XML, or otherwise follow the Atom standard. The `EventsFeedProducerActor` itself may be backed by the XOOM Lattice exchange feed type, which may stream from a XOOM Symbio `Journal`, or any kind of `EntryReader` for the storage types `ObjectStore` and `StateStore`.
```java
package io.vlingo.xoom.lattice.exchange.feed.Feed;
import io.vlingo.xoom.actors.Actor;
import io.vlingo.xoom.actors.Stage;
import io.vlingo.xoom.symbio.Entry;
import io.vlingo.xoom.symbio.Source;
import io.vlingo.xoom.symbio.store.EntryReader;
/**
* Provides support utilities for {@code Feed} and related types.
* Every {@code Feed} has an {@code exchangeName}.
*/
public interface Feed {
/** The default number of messages per feed. */
static final int DefaultMessagesPerFeedItem = 20;
/**
* Answer a new {@code Feed} with the given properties.
* @param stage the Stage used to create my Feeder
* @param exchangeName the String name of my exchange
* @param feederType the Actor type of my Feeder
* @param entryReaderType the EntryReader that my Feeder uses
* @return Feed
*/
static Feed defaultFeedWith(final Stage stage, final String exchangeName, final Class feederType, final EntryReader entryReaderType) {
return new DefaultFeed(stage, exchangeName, feederType, entryReaderType);
}
...
}
```
The above `DefaultFeed` is a factory for actor-based `Feeder` types. Invoking the `Feed::feeder()` will return a new actor-based `Feeder` of `feederType` with the given `entryReaderType`.
There is a default `Feeder` , the `TextEntryReaderFeeder`, that can consume text entries from any XOOM Symbio `EntryReader` implementation and produce simple feeds.
```java
package io.vlingo.xoom.lattice.exchange.feed;
import java.util.ArrayList;
import java.util.List;
import io.vlingo.xoom.actors.Actor;
import io.vlingo.xoom.symbio.BaseEntry.TextEntry;
import io.vlingo.xoom.symbio.store.EntryReader;
/**
* The {@code Feeder} serving {@code TextEntry} instances.
*/
public class TextEntryReaderFeeder extends Actor implements Feeder {
private final EntryReader entryReader;
private final Feed feed;
/**
* Construct my default state.
* @param feed the Feed that I serve
* @param entryReader the {@code EntryReader} from which content is read
*/
public TextEntryReaderFeeder(final Feed feed, final EntryReader entryReader) {
this.feed = feed;
this.entryReader = entryReader;
}
/**
* @see io.vlingo.xoom.lattice.exchange.feed.Feeder#feedItemTo(io.vlingo.lattice.exchange.feed.FeedItemId, io.vlingo.lattice.exchange.feed.FeedConsumer)
*/
@Override
public void feedItemTo(final FeedItemId feedItemId, final FeedConsumer feedInterest) {
final long feedId = feedItemId.toLong();
final long id = (feedId - 1L) * feed.messagesPerFeedItem() + 1;
entryReader
.readNext(String.valueOf(id), feed.messagesPerFeedItem())
.andThen(entries -> {
feedInterest.consumeFeedItem(toFeedItem(feedItemId, entries));
return entries;
});
}
/**
* Answer a new {@code FeedItem} from converted {@code entries}.
* @param feedItemId the FeedItemId of the current item
* @param entries the List to convert
* @return FeedItem
*/
private FeedItem toFeedItem(final FeedItemId feedItemId, final List entries) {
final List messages = new ArrayList<>(entries.size());
for (final TextEntry entry : entries) {
final FeedMessageBody body = FeedMessageBody.with(entry.entryData());
final FeedMessage message = FeedMessage.with(entry.id(), body, entry.typeName(), entry.typeVersion());
messages.add(message);
}
if (feed.messagesPerFeedItem() == entries.size()) {
return FeedItem.archivedFeedItemWith(feedItemId, feedItemId.next(), feedItemId.previous(), messages);
} else {
return FeedItem.currentFeedWith(feedItemId, feedItemId.previous(), messages);
}
}
}
```
It should be clear how you can stitch together a number of feeds to provide HTTP feeds of event streams: `Response <- http-Feed <- lattice-Feed <- symbio-EntryReader`
### Request and Response Filters
You can register filters with the `Server` for both requests and responses. The following is an example of how to start the Server with any number and type of filters:
```java
Filters filters =
Filters.are(
Arrays.asList(new DateRequestFilter()),
Arrays.asList(new DateResponseFilter()));
Server server =
Server.startWith(
world.stage(),
resources,
filters,
PORT,
Sizing.define(),
Timing.define());
```
The following is an example of a `RequestFilter` that is used to ensure that every request has a `Date` header:
```java
public class DateHeaderFilter extends RequestFilter {
@Override
public Tuple2 filter(final Request request) {
if (request.headerValueOr(RequestHeader.Date, null) == null) {
request.header(RequestHeader.Date, Instant.now().toString());
}
return Tuple2.from(request, true);
}
}
```
The return type of `Tuple2` provides both the `Request` results of the filter and a `Boolean` to indicate whether the filter chain should continue (`true`) or short circuit (`false`).
The following `ResponseFilter` does the same as the previous, but for responses:
```java
public class DateHeaderFilter extends ResponseFilter {
@Override
public Tuple2 filter(final Response response) {
if (response.headerValueOr(ResponseHeader.Date, null) == null) {
response.header(ResponseHeader.Date, Instant.now().toString());
}
return Tuple2.from(response, true);
}
}
```
The return type is the same as for the `RequestFilter` and has the same meaning.
There is a special `ResponseFilter` that supports CORS request-response from cross-origin clients:
```java
final CORSResponseFilter filter = new CORSResponseFilter();
final List headers =
Arrays.asList(
ResponseHeader.of(ResponseHeader.AccessControlAllowOrigin, "*"),
ResponseHeader.of(ResponseHeader.AccessControlAllowHeaders, "Content-Type, Content-Length"),
ResponseHeader.of(ResponseHeader.AccessControlAllowMethods, "POST,GET"));
filter.originHeadersFor(headerAcceptOriginAny, headers);
final Filters filters = Filters.are(Filters.noRequestFilters(), Arrays.asList(filter));
Server server =
Server.startWith(
world.stage(),
resources,
filters,
PORT,
Sizing.define(),
Timing.define());
```
Register the kinds of access control headers that are supported by the receiving application. There must always be an `Access-Control-Allow-Origin` header, which is used to match that sent by the client agent. The matching string may be `"*"` for any origin or some well-know URI of a acceptable application. Other headers are as follows, and each has a corresponding constant in class `ResponseHeader`:
| Header | Constant in Class `ResponseHeader` |
| ---------------------------------- | ---------------------------------- |
| `Access-Control-Allow-Origin` | `AccessControlAllowOrigin` |
| `Access-Control-Allow-Credentials` | `AccessControlAllowCredentials` |
| `Access-Control-Expose-Headers` | `AccessControlExposeHeaders` |
| `Access-Control-Max-Age` | `AccessControlMaxAge` |
| `Access-Control-Allow-Methods` | `AccessControlAllowMethods` |
| `Access-Control-Allow-Headers` | `AccessControlAllowHeaders` |
## Reactive Client
As noted earlier, XOOM HTTP provides a special `Client` used for making HTTP requests and reacting to responses as they happen. Being reactive, this `Client` is a non-blocking tool. The above example showed how to use a reactive pipeline to both request and reactive to the eventual response. Here is a similar example that could be used for `GET` requests and responses:
```java
import io.vlingo.xoom.http.resource.Client;
...
Catalog catalog = Catalog.of(CatalogType.SummerOffers);
Client client = Client.using(configuration, clientConsumerType, poolSize);
client
.requestWith(
Request
.method(Method.GET)
.uri("/offers/summer-4528")
.and(RequestHeader.host("chocolaterocks.io"))
.and(RequestHeader.accept("application/json")))
.andThenConsume(response -> {
switch (response.status) {
case Ok:
catalog.offer(offerFrom(response));
break;
default:
logger().error("Unexpected: " + response.status);
break;
}
})
.close();
...
```
Assume that the `catalog` object is backed by an actor. In this example the `close()` occurs just after the `offer()` message is sent to the `catalog`. The `Client` could have remained open if it was configured for keep-alive mode, and if it had used `repeat()` as the final pipeline expression (demonstrated [previously](#server-sent-events-sse)).
The `Client` provides a factory with the means to configure the resulting `Client` object along with one of three client types by means of the `ClientConsumerType`.
The `Configuration` has a number of factories that arrange for defaults to be set, and one that accepts all possible configuration parameters:
| Factory | Description |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| defaultedExceptFor(
Stage,
ResponseConsumer)
| The Stage is used to access standard platform resources, such as the Scheduler. The ResponseConsumer provides the the actor-backed protocol for the "consumer of unknown responses."
The remaining attributes will use defaults, which means keep-alive is false.
The remaining attributes will use defaults, which means keep-alive is false.
|
| defaultedExceptFor(
Stage
Address,
ResponseConsumer)
| The same as above, but with the Address of the host server (host name and port).
The remaining attributes will use defaults, which means keep-alive is false.
|
| defaultedExceptFor(
Stage
Address,
ResponseConsumer,
int writeBufferSize,
int readBufferSize)
| The same as above, but provides the size (length) of write and read ByteBuffer instances, respectively, created to be used by the channel. The default for both is 10,240 bytes.
The remaining attributes will use defaults, which means keep-alive is false.
|
| defaultedKeepAliveExceptFor(
Stage
Address,
ResponseConsumer)
| The same as above, but requests that the the connection channel be kept alive (keep-alive is true) until it is explicitly closed by the caller.
When keep-alive is used, it is possible and practical to reuse Completes\ that is the return value of Client requestWith(...). To accomplish this, use the repeat() as the final expression of the completes pipeline.
The remaining attributes will use defaults.
|
| has(
Stage
Address,
ResponseConsumer,
boolean keepAlive,
long probeInterval,
int writeBufferSize,
int readBufferPoolSize,
int readBufferSize)
| Creates the Configuration with all explicit parameters for full attribute setting. All of the parameters are explain above except for probeInterval and readBufferPoolSize.
The probeInterval is the frequency in milliseconds that the channel is read. We recommend that you use the default of 10. You can experiment with different intervals, but if problems occur it is probably too frequent or too seldom.
The readBufferPoolSize is the number of read ByteBuffer instances allocated in a pool, with each used to read different channels asynchronously. The default is 10. If the number of pooled buffers are exhausted, the pool will automatically grow to handle a greater number of simultaneous requests. Any extra temporary buffers are discarded as load diminishes.
|
The `ClientConsumerType` is an `enum` that enables the following dispatcher types:
| Type | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Correlating` | Used to create a Client that interacts with the HTTP server using the extended header X-Correlation-ID. Each request is sent with a unique identity (UUID) header value and the server is expected to include the same header and value in its response. The unique identity can be provided as a pre-set X-Correlation-ID header by the using(...) caller, or the header will be created by the internal requester.
When used, it is often advantageous that the Client be created with the keep-alive configuration. Keep-alive mode ensures that the underlying connection remains open and is thus reusable for many request-response pairs. Even so, a keep-alive Client is not required.
When the response is received and parsed, it is provided through the platform standard Completes\ object.
|
| `LoadBalancing` | Used to create a Client that makes requests using a load-balanced dispatch across some number of channel actors.
The Client.using() parameter poolSize is used to create the number of round-robin dispatchers. The load-balancing is based on the dispatcher with the least number of requests currently in its mailbox.
When the response is received and parsed, it is provided through the platform standard Completes\ that is the return value when calling the Client requestWith().
|
| `RoundRobin` | Used to create a Client that makes requests using a round-robin dispatch across some number of channel actors.
The Client.using() parameter poolSize is used to create the number of round-robin dispatchers.
When the response is received and parsed, it is provided through the platform standard Completes\ that is the return value when calling the Client requestWith().
|
Determine which kind of `Client` to create for various request-response situations.
## Defining Dynamic Resources
XOOM HTTP provides a fluent API to define HTTP endpoints and corresponding Java handler methods. These kinds of resources are different than those loaded from the file `vlingo-http.properties`. You had a brief introduction to the handler methods at the outset of this chapter. Here you will see them in more detail.
The following is the `ResourceBuilder` used to fluently create route mappings.
```java
ResourceBuilder.resource(final String name, final RequestHandler... requestHandlers)
```
You give the `Resource` a name and a varargs list of `RequestHandler` definitions. This method returns a `Resource`. The `Server` needs a set of `Resource` instances to match and route HTTP requests to handlers that respond. Each of the RequestHandler instances are mapped by means of declaring HTTP methods, as next discussed.
### HTTP Methods
The fluent API supports the following HTTP methods.
* `ResourceBuilder.post(final String uri)`
* `ResourceBuilder.get(final String uri)`
* `ResourceBuilder.put(final String uri)`
* `ResourceBuilder.patch(final String uri)`
* `ResourceBuilder.delete(final String uri)`
* `ResourceBuilder.head(final String uri)`
* `ResourceBuilder.options(final String uri)`
* `ResourceBuilder.trace(final String uri)`
* `ResourceBuilder.connect(final String uri)`
All of the above methods answer a new resource handler instance, whether or not it extends the base class `DynamicRequestHandler`. We recommend using static imports for the most fluent use of the API.
```java
import static io.vlingo.xoom.common.serialization.JsonSerialization.serialized;
import static io.vlingo.xoom.http.Response.Status.Created;
import static io.vlingo.xoom.http.Response.Status.NotFound;
import static io.vlingo.xoom.http.Response.Status.Ok;
import static io.vlingo.xoom.http.ResponseHeader.Location;
import static io.vlingo.xoom.http.ResponseHeader.headers;
import static io.vlingo.xoom.http.ResponseHeader.of;
import static io.vlingo.xoom.http.resource.ResourceBuilder.get;
import static io.vlingo.xoom.http.resource.ResourceBuilder.patch;
import static io.vlingo.xoom.http.resource.ResourceBuilder.post;
import static io.vlingo.xoom.http.resource.ResourceBuilder.resource;
```
The above shows other common static imports besides those needed for fluent resource wiring.
### Request Handler
The request handler enforces type safety on the handler function method definition through the declaration of expected parameters. There are several mapping options, so consider each.
#### Path Parameters
Map path parameters by identifying them in the URI as a `{variable}` and then indicate the type in the `path()` method to be used by your handler.
{% tabs %}
{% tab title="Java" %}
```java
get("/user/{userId}")
.path(String.class)
.handler((userId) -> /* */);
```
{% endtab %}
{% tab title="Kotlin" %}
{% endtab %}
{% endtabs %}
Here the `userId` will be mapped to a `String` because the method `path(String.class)` specifies that type. You can specify parameter mappings to any of the following types.
* `String`
* `Long`
* `Integer`
* `Float`
* `Double`
* `Boolean`
* `Short`
* `Character`
{% hint style="danger" %}
The `path()` method must be used before any other route mapping method, otherwise an exception will be thrown when the `Server` starts.
{% endhint %}
{% hint style="warning" %}
When using `path()` be sure you have the same path variable in the URI between brackets `{}` as the `path()` methods reference.
{% endhint %}
#### Body Parameter
The `body()` method maps the HTTP body into the type you specify.
{% tabs %}
{% tab title="Java" %}
```java
post("/user")
.body(NameData.class)
.handler((nameData) -> /* */);
```
{% endtab %}
{% tab title="Kotlin" %}
```java
```
{% endtab %}
{% endtabs %}
#### Query Parameters
You may use query parameters in the expected way. For example, page=5 is a query parameter in this curl command.
```bash
> curl http://localhost:8080/user?page=5
```
You may map this specific query parameter fluently in three different ways.
{% tabs %}
{% tab title="Java" %}
```java
get("/user")
.query("page")
.handler((page) -> /* */);
get("/user")
.query("page", Integer.class)
.handler((page) -> /* */);
get("/user")
.query("page", Integer.class, 0 /* default value */)
.handler((page) -> /* */);
```
{% endtab %}
{% tab title="Kotlin" %}
```java
get("/user")
.query("page")
.handler((page) -> /* */);
```
{% endtab %}
{% endtabs %}
By default, the type of all query parameters is `String`. When the query parameter isn't present, the value is `null`. It's good practice to always specify a default value for query parameters to avoid unexpected behavior.
#### Request Headers
You may access request headers as expected.
{% tabs %}
{% tab title="Java" %}
```java
get("/user")
.header("Location")
.handler((location) -> /* */);
```
{% endtab %}
{% tab title="Kotlin" %}
{% endtab %}
{% endtabs %}
#### Combining Them All
The following is an example showing all of the above parameter options.
{% tabs %}
{% tab title="Java" %}
```java
post("/user/{userId}")
.param(String.class)
.body(UserData.class)
.header("Location")
.handler((userId, userData, location) -> {
// Perform some action
return Completes.withSuccess(Response.of(Ok, serialized(userData)));
});
```
{% endtab %}
{% tab title="Kotlin" %}
{% endtab %}
{% endtabs %}
{% hint style="info" %}
The order of the parameters matters. Try changing the order of body and header. You will see that the type of the `userData` parameter becomes a header type and `location` now has the `UserData` type.
{% endhint %}
Check the [`xoom-http-frontservice`](https://github.com/vlingo/xoom-examples/tree/master/xoom-http-frontservice) for a more complete working example.
## Content Negotiation
To support media/content negotiation request handlers use the `ObjectResponse` return type. The `?` is replaced with your actual representation data type, such as `PersonData` or `EmployeeData`, or whatever; the type that is represented to clients.
The `from(...)` method enables building an `ObjectResponse` with a response status, headers, and a concrete represented content type. This response is serialized according to the accept headers of the request via the `MediaTypeMapper`, or `JSON` if a given `MediaTypeMapper` is not supplied. If there is no match on the specific media type, the client receives the appropriate HTTP status code.
Once serialized by the supplied `MediaTypeMapper` , the final `Response` is generated and the appropriate `Content-Type` header is automatically inserted into the `Response`, along with any other headers provided by the handler method. The following is a basic example of how to create a handler that returns `MyType` as the `ObjectResponse` type.
```java
// GET /resources/mytype
ObjectResponse provideMyType() {
return ObjectResponse.from(Status.ok, new MyType("some value"));
}
```
The previous `Mapper` type has been deprecated, which affects places where the existing `Mapper` is being used as an input parameter to the `RequestHandler` methods. The older `Mapper` is undesirable because it ignores the accept header and may create confusion—the deprecation note speaks to that.
## Resource Handler Methods
There are a few things to keep in mind when designing a request handler method on a resource.
Resource methods must return one of two types. It may be `Completes` or `Completes`. The use of the `Completes` enables the server to operate asynchronously by postponing responses until all necessary processing has completed.
If there are a number of asynchronous steps required to carry out a request to the ultimate response, the steps should be managed through a `Completes` pipeline.
```java
public class UserResource {
private final AddressFactory addressFactory;
private final Stage stage;
public UserResource(final World world) {
this.addressFactory = world.addressFactory();
this.stage = world.stage();
}
...
public Completes changeContact(final String userId, final ContactData contactData) {
return stage.actorOf(User.class, addressFactory.from(userId))
.andThenTo(user -> user.withContact(new Contact(contactData.emailAddress, contactData.telephoneNumber)))
.andThenTo(userState -> Completes.withSuccess(Response.of(Ok, serialized(UserData.from(userState)))))
.otherwise(noUser -> Response.of(NotFound, userLocation(userId)));
}
...
public Resource routes() {
return resource("User Resource",
...
patch("/users/{userId}/contact")
.param(String.class)
.body(ContactData.class)
.handle(this::changeContact),
...
);
}
}
```
Recall that `andThenTo()` is used to send an asynchronous message to an actor with an eventual outcome via `Completes`, and `otherwise()` handles an error outcome, while exceptions are handled by `recoverFrom()`. If you must simply map the outcome value to a new value and possibly a new type, you need only use `andThen()`. You can read more details about `Completes` [here](/xoom-common#completes).
Due to the fact that any given handler instance will be reused many times, handler methods must be side-effect free. That is, they must not mutate the state of the handler instance. In the above example you can see that all `UserResource` state is final and the `changeContact()` method is side-effect free. Handler methods are themselves pure functions, but do not require components that they use to be pure functions. In other words, the `User` domain object actor may be mutable.
## Known Limitations
We know of a few limitations.
* Using the fluent API, we currently support up to six handler function arguments. If you need more than six, please open an issue [here](https://github.com/vlingo/vlingo-http/issues).
* ~~There is currently a~~ [~~problem~~](https://github.com/vlingo/vlingo-wire/issues/28) ~~with some Linux servers and the JDK implementation of non-blocking socket channel reads.~~ (Was fixed.)
Would you like to contribute to XOOM HTTP? See the [vlingo/xoom-http](https://github.com/vlingo/xoom-http) repository and review any outstanding issues. We are happy to help you with the simple on-boarding steps.
# Lattice
The VLINGO XOOM platform toolset providing compute grid, actor caching, object spaces, cross-node cluster messaging, publish-subscribe, CQRS, and Event Sourcing support.
## Feature Overview
The XOOM Lattice component provides tooling for reactive Domain-Driven Design projects that are highly concurrent. The tools of the component include compute grid, actor caching, spaces, cross-node cluster messaging, publish-subscribe, CQRS, and Event Sourcing support.
| Feature | Description |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [CQRS](/xoom-lattice/cqrs) | Understanding the Command-Query Responsibility Segregation pattern. |
| [Object, Stateful, and Sourced Entities with CQRS](/xoom-lattice/entity-cqrs) | Supports three styles of persistence, including Object, Stateful, and Sourced.
Command-Query Responsibility Segregation uses two models per Bounded Context (application or service), the Command Model and the Query Model, otherwise known as the Read Model and the Write Model, respectively.
|
| [Grid](/xoom-lattice/grid) | Provides an API for distributed computations and data processing across multiple nodes in a cluster. Supports distributed parallel processing by sending computational execution requests to actors on any node in a cluster with the potential to receive results in return. |
| [Exchange](/xoom-lattice/exchange) | Provides an abstraction over Publish-Subscribe messaging exchanges or topics. This is a means to publish messages to exchanges/topics inside or outside your current application/service, and to subscribe to such messages. Provides translators from internal to external message types, and from external to internal message types. |
| [Processes](/xoom-lattice/processes) | Long-running processes that manage complex, coarse-grained, business transactions, must be managed through every step until completion. These tools assist in managing such processes whether by means of object persistence, stateful command models, or sourced with commands. |
| [Projections](https://docs.vlingo.io/vlingo-lattice/projections) | How to project state, Domain Events, and other Source types into a CQRS Query Model. |
| [Routers](/xoom-lattice/routers) | Use message-driven command routing to handlers that are responsible for modifying the domain model, which may be segregated as a Command Model. |
## Types
The following types are defined in the XOOM Lattice component and commonly used with domain-driven designed services.
| Type | Descriptio |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DomainEvent` | A abstract type used to model a record of fact about an important business occurrence in the domain model |
| `IdentifiedDomainEvent` | A abstract type used to model a record of fact about an important business occurrence in the domain model and that has an identity associated with it, which can be used for correlation |
| `EventSourced` | An abstract type used to create an Event Sourced entity that is backed by a persistent Journal |
| `Command` | An abstract type used to model a record of an imperative directive to carry out a business operation |
| `CommandSourced` | An abstract type used to create an Command Sourced entity |
| `ObjectEntity` | An abstract type used to model an entity that is backed by object-relational persistence |
| `StatefulEntity` | An abstract type used to model an entity that is backed by Key-Value persistence |
| `Process` | An interface implemented by a component that orchestrates the steps necessary to complete a composite task |
| `Projection` | An interface implemented by a component that serves to project Command Model state onto the Query Model |
| `Projectable` | An interface used to abstract the Command Model data projected onto the Query Model |
| `Exchange` | An abstraction over Publish-Subscribe messaging exchanges and topics |
| `CommandRouter` | A means of asynchronous message-driven command routing to handlers that are responsible for modifying the domain model |
These types are discussed in detail throughout the subsections of this chapter.
# CQRS
Understanding Command-Query Responsibility Segregation
Software developers commonly face a design challenge because of the way users view data. The data of effective user interface views tends to be in quantities, shapes, and sizes that are different from the way users modify data. Using a traditional domain model that provides both mutation and query operations together results in the following problems, because the data users view cannot be retrieved as optimally as is generally possible for mutation.
The system state that the user wants to view tends to be rich and cuts across at least several logical entity/aggregate types. The state that the user wants to mutate tends to be concentrated on one one aggregates or a few entities. The strengths of CQRS are in enabling developers to design for state mutation separately from state queries. The state mutation operations are optimized for creates and updates. The operations and data used for querying are optimized for how the user tends to view the system state. Both of these sets of operations and states can be designed and scaled separately. In brief, the stated software design challenges can be addressed and related problems overcome with the use of CQRS.
## CQRS and Architecture
One of the primary misunderstandings even among those who claim to know CQRS well, is thinking that CQRS is a system-level or top-level architecture, as in an architectural style. It’s possible that some think this simply because they don’t understand what constitutes a top-level architecture, or architectural style. An architectural style describes the pattern that is followed by an entire application or service, and not just some small portion of the the overall application or service. For example, there are Layers architecture and Ports and Adapters architecture.
Ports and Adapters is an architecture that has an impact on the way an application or service as a whole works. When the Ports and Adapters architecture is used, everything within the application or service reflects some well-defined part of the definition of Ports and Adapters. Although Ports and Adapters highlights the adapters for incoming stimulus, the architecture also defines the inside with the application interfaces. Additionally, the application inside may be further divided into application services and a domain model.
CQRS is not intended to be and architectural style since it doesn’t by definition have an impact on the overall application or service. Instead, CQRS is an architecture pattern; one that has some substantial influence on the inner workings of the application or service, but not every part of it. With that in mind, consider what CQRS actually means.
## Meaning
The CQRS architecture pattern is based on the CQS software principle defined by Bertrand Meyer, creator of the Eiffel programming language. To understand CQRS it helps to first understand CQS. It’s fitting then to provide a few definitions.
CQS, or Command-Query Separation states that a software interface abstraction is designed with two types of methods. One method type is known as a Command method, and the other method type is known as a Query method. A Command method modifies or mutates the state underneath the interface, but does not answer any portion of that state. A Query method answers the current state beneath the interface, but must not modify that state before answering it. In particular note that CQS mandates the definition of the methods of a single interface abstraction. In the literature CQS is not considered a pattern, but a principle. I don’t want to split hairs over this, because you might argue that CQS is a design pattern, but it’s difficult to find official definitions to support that argument.
```java
package com.ecommrus.catalog.model;
public interface Product {
void changeSku(final SKU sku);
SKU querySku();
void rename(final String name);
String queryName();
void summarize(final String summary);
String querySummary();
void describe(final String description);
String queryDescription();
...
}
```
Although there is more detail to the `Product` interface, what is shown is enough to make the essential point about CQRS. This interface combines both commands and queries. The `changeSku()` and `rename()` are command methods, which are used to modify the `sku` and `name`, respectively. The `querySku()` and `queryName()` are used to read the current state of the Product `sku` and `name`, respectively.
This seems to be designed appropriately. The problem is that when the user needs to view the `Product` they also need to view the `Pricing`, `Availability`, `SimilarProducts`, `ProductReviews`, and possibly other information that is loosely associated with a given `Product`. Considering that there is a minimum of five objects that must be retrieved for that user view, it will certainly be quite difficult and inefficient to query each piece of data separately.
With motivations to optimize for the above use case, we decide to design our Command Model and our Query Model separately. Thus, the `Product` in the Command Model is refactored as follows, with command operations only.
CQRS, or **Command-Query Responsibility Segregation**, is similar to CQS because it focuses on separating Command methods and Query methods, but it does so to an even greater degree. This is a good time to highlight the terms responsibility and segregation. The term responsibility conveys the idea that Commands are not only a type of method, but a type of software responsibility. The same goes for Queries. The term segregation emphasizes that the two responsibilities, Commands and Queries, are segregated from each other using separate interfaces. Thus, where there is one `Product` interface in the above example, there are now two interfaces.
To optimize for the above use case, we decide to design the Command Model and the Query Model separately. Thus, the `Product` in the Command Model is refactored as follows, with command operations only.
```java
package com.ecommrus.catalog.command;
public interface Product {
void changeSku(final SKU sku);
void rename(final String name);
void summarize(final String summary);
void describe(final String description);
...
}
```
The Query Model is even in a separate module/package.
```java
package com.ecommrus.catalog.query;
public class ProductQueries {
Collection queryAll();
ProductData queryProductOf(final SKU sku);
}
public class ProductData {
public final String sku;
public final String name;
public final String summary;
public final String description;
...
public final AvailabilityData availability;
public final PricingData pricing;
public final ProductReviewsData productReviews;
public final SimilarProductsData similarProducts;
}
```
It seems important to note that the above segregated interfaces emphasize why CQRS is not an architectural style, but an architecture pattern. Since `Product` is likely not the only business concept in the application or service, there could be several other business model concepts defined. These are concepts that are more closely associated with the interior of the application or service, generally know as the domain model.
It's not an oversimplification to say that CQRS is just that simple.
## Command Model and Query Model
Considering a traditional domain model, there is just one model that defines the application’s or service’s state. Defining our business concepts using the CQS principle, there is still just one root object constituting a `Product`.
When using CQRS it is typical to use not one, but two, models, those being a Command Model and a Query Model. This is part of the segregation, but in addition to the interfaces there are the software models of the segregated states. There are the segregated states used by the Commands, and segregated states used by the Queries. This is at least a logically segregation because there is nothing to prevent the implementation from persisting the Command states and Query states together. Still, it is easier to reason about two state models rather than one.
When methods on the `Product` interface are executed, the Command Model state is mutated. When methods on the `ProductQueries` interface are executed, the Query Model state is queried. That makes sense, except for how the Query Model state comes about. That is illustrated by the following diagram.
The [Query Model is built up by projecting on to it](/xoom-lattice/projections) the changes made to the Command Model. As the user submits Command operations, the outcome of the Command Model mutations are used by software components to projection appropriate updates onto the Query Model. The user views the system state by way of the use-case-optimized Query Model.
In the above diagram, the Command Model mutations are captured by Domain Events, which are also used to project updates onto the Query Model. It is not necessary to use Domain Events for this. The entire state of a Command Model object that is mutated may be projected instead. If this approach is used, it’s helpful to indicate to the projection components what the actual Command operation was that caused the state to mutate. This enables the projection components to have both a rich set of data to project, but with full knowledge of the actual state that changed.
# Object, Stateful, and Sourced Entities With CQRS
Understanding reactive Object, Stateful, Sourced, and CQRS actor-based persistence.
[*Command-Query Responsibility Segregation*](/xoom-lattice/cqrs) uses two models per Bounded Context (application or service). These are the *Command Model* and the *Query Model,* otherwise known as the *Read Model* and the *Write Model,* respectively.
{% hint style="info" %}
The *Command Model* is often referred to as the "Write Model" and the *Query Model* as the "Read Model." These AKAs are quite inaccurate because you actually read from and write to both models. We prefer the names *Command Model* and *Query Model* because these names adhere to the pattern name, CQRS, and express the purpose of each of the two models.
{% endhint %}
The XOOM Lattice tools support three styles of persistence, including object, flat state, and sourced. The object style of persistence is more commonly known as Object-Relational Mapping (ORM), although a very low-impact mapping approach is also provided. The flat state style uses a Key-Value persistence, which is often suitable for both the CQRS Command Model and Query Model. The sourced style provides the persistence of a series of facts, known as Domain Events, that when applied or folded into a single object, combine to form a state. This is know as Event Sourcing, but may also be used with Commands to support Command Sourcing, and even other sources such as [process messages](/xoom-lattice/processes).
## Understanding Entity Actor Lifecycles
Let's start out by contrasting the lifecycles of Plain Old Java Objects (POJOs) with Actor-based entities.
In a typical object-based application or service that uses POJOs, the lifecycle of entities is different from that of actor-based entities. Here we can assume that Entity and Aggregate as defined within Domain-Driven Design are interchangeable; that is, what follows deals with both concepts.
### POJO Lifecycles
The following describes the typical lifecycle of a POJO Entity:
* Non-existing Entity states are newly constructed and then persisted to storage
* Preexisting Entity states are reconstituted from storage, modified, and then persisted back to the same storage (updated).
* Across a single JVM or a multi-JVM cluster, there may be any number of duplicated Entity instances. This implies that any of the duplicate instances may simultaneously have different operations performed by different users. In such cases the database must provide optimistic concurrency and detect concurrency violations via state versions.
* The object reference is released after Entity persistence and the instance garbage collected.
### Actor-Entity Lifecycles
The following describes the typical lifecycle of an actor-based Entity.
Note that this applies across various types of Entities supported by XOOM Lattice, including `Sourced`, `StatefulEntity`, and `ObjectEntity`:
* Non-existing states are newly persisted, and the guaranteed persistent state is then set back onto the actor state.
* Preexisting states are possibly already in memory; if not in memory, states are reconstituted from storage; proposed changes are then persisted back to the same storage; following persistence, the state is then set back onto the actor state.
* Across a single JVM or a multi-JVM cluster, there is one uniquely identified Entity instance, and all requests for creation/modification will be focused on that single instance, wherever it may be.
* The actor is retained in memory until memory constraints call for some actors to be evicted. A least-recently-used algorithm determines which specific actor instances must be evicted, and those actors are stopped. The evictions make room for other currently "hot" actors.
### Commands, Domain Events, and Identified Domain Events
Lattice defines abstract base types: `Command`, `DomainEvent`, `IdentifiedDomainEvent`. These provide for modeling specific types as follows:
| Type | Description |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Command` | An abstract type used to model the imperative intent directive to carry out a business operation. Alternatively a command can be a method declaration rather than an object/record |
| `DomainEvent` | A abstract type used to model a record of fact about an important business occurrence in the domain model |
| `IdentifiedDomainEvent` | A abstract type used to model a record of fact about an important business occurrence in the domain model and that has an identity associated with it, which can be used for correlation |
These types, and especially `DomainEvent` and `IdentifiedDomainEvent` will be extended in order to create concrete types used in each domain model. In the examples that follow two domain events are used, `CartCreated` and `ProductPlacedInCart`. These could be modeled as either `DomainEvent`, or `IdentifiedDomainEvent` if there is a need to correlate multiple domain events to a kind of long-running process, also known as a Saga.
### Entity Construction Details
Regarding the creation of the various Entity types, including `Sourced`,`EventSourced`, and `CommandSourced`, there are design decisions that determine some minor constraints.
In the following discussions we refer to `apply()` methods. These are provided by the aforementioned Entity abstract types: `StatefulEntity`, `ObjectEntity`, `Sourced`,`EventSourced`, `CommandSourced`, etc. These methods are responsible for managing the atomic persistence of Entity state and `Source` instances, such as concrete extensions of `DomainEvent`. These are also responsible for setting the guaranteed persistent state back onto the Entity. These `apply()` methods are explained in more detail below, but you must be aware of their existence here.
Generally speaking, it is very difficult to support the use of `apply()` methods from inside Entity constructors. Thus, we do not currently support using an `apply()` method from a Entity constructor. Next it is explained why this is the case. A `Product` protocol is used as the concrete Entity type and `EventSourced` as the abstract base Entity, although it could be any of the abstract base types.
1. All Entity abstract base types provide constructors that take either zero parameters or one parameter, that being the Entity unique identity.
2. If the zero-argument constructor is used, the actor's address is used as the unique identity. This works out especially well for [Grid-based actors](/xoom-lattice/grid) because the address is based on a universally unique identity (our recommended approach).
3. The `Product` constructor may take one or more parameters used for identity, but the abstract base constructor accepts only zero or a single parameter, but only one identity may be passed to the base constructor. When supplying the constructor with multiple identity parts, these can be turned into a single composite identity using the `streamNameFrom(...)` of `Sourced` (e.g. `EventSourced`, `CommandSourced`, and `Process`) and the `idFrom(...)` for `StatefulEntity` and `ObjectEntity`.
4. After the Entity constructor has completed, the actor will receive it's first message, known as `start()`. It is when handling this `start()` message that the abstract base Entity attempts to restore its state from persistence. If persistent state is not available, the Entity has its initial default state. If persistent state is available, the Entity is initialized with it. For `Sourced` entities the initial state will be applied using one or more sources, such as `DomainEvent` types, in its stream. This emphasizes that if the concrete Entity type overrides the `start()` message, it must ensure that the base `start()` is always handled with `super.start()`. Also the concrete Entity type must assume that the initial state in not available until after the base `start()` handler is run. In fact, the concrete Entity type will never see a recovered initial state because the base `start()` handles recovery using asynchronous messaging to and from the storage actor.
Consider also that any constructor is not a good expression of behavior for the Ubiquitous Language. Even when designing with POJOs it's generally desirable to hide the constructor behind an expressive Factory Method, such as:
```java
Product product = Product.receiveInto(warehouse);
```
Look at the `vlingo-iddd-collaboration` example to [see examples](https://github.com/vlingo/vlingo-examples/blob/8fbc432545555641efab01d790183c6580a985c9/vlingo-iddd-collaboration/src/main/java/com/saasovation/collaboration/model/forum/Forum.java#L24) of how this may be accomplish in the `Forum` protocol Factory Method. Additionally, `ForumEntity` starts a new `Discussion` in its `discussFor()` [message handler](https://github.com/vlingo/vlingo-examples/blob/8fbc432545555641efab01d790183c6580a985c9/vlingo-iddd-collaboration/src/main/java/com/saasovation/collaboration/model/forum/ForumEntity.java#L57). Likewise, the `DiscussionEntity` creates a new `Post` in its `postFor()` [message handler](https://github.com/vlingo/vlingo-examples/blob/8fbc432545555641efab01d790183c6580a985c9/vlingo-iddd-collaboration/src/main/java/com/saasovation/collaboration/model/forum/DiscussionEntity.java#L39).
## Entity Storage Mechanisms
The following explains the storage options available for each Entity type: `ObjectEntity`, `StatefulEntity`, as well as `EventSourced` and `CommandSourced`.
{% hint style="info" %}
Note that when an Entity's applied state and/or events are persisted, [actor message stowage](/xoom-actors#stowage) is used for non-blocking operational pauses until the persistence success or failure is confirmed.
{% endhint %}
### Object-Relational Mapping
An `ObjectEntity` concrete extension is stored using Object-Relational Mapping (ORM). There is already much literature available on ORM so we won't spend much time explaining it here. The basic idea is that a software object may be mapped into the row of a relational database table. Each of the object's attributes are mapped to a column in that row. There are, of course, more elaborate mapping relationships that can be employed, such as for one-to-many, many-to-one, and many-to-many object compositions. Yet, the mappings still come down to tables, rows, and columns holding object state.
The [XOOM Symbio](/xoom-symbio) components provide various JDBC implementations for ORM using the `ObjectStore`, including Java Persistence Architecture (JPA). The JPA options include EclipseLink, OpenJPA, and Hibernate. Another JDBC implementation of XOOM Symbio supports Jdbi, which is a very lightweight toolkit for mapping objects. As long as your entity designs are small, using Jdbi may be all you need and will be a welcome alternative to JPA and other traditional ORM tools.
The following table shows the databases current supporting ORM.
| Database | Use |
| ------------------ | ---------- |
| Apache Geode | Production |
| HSQLDB (in-memory) | Testing |
| In-Memory | Testing |
| MariaDB | Production |
| MySQL | Production |
| PostgreSQL | Production |
| YugaByte | Production |
Below you will see [how to use Object-Relational Mapping in your entities](/xoom-lattice/entity-cqrs#objectentity-example).
### Stateful
A `StatefulEntity` concrete extension is stored using a key-value database. The [XOOM Symbio](/xoom-symbio#what-is-symbio) components provide simple key-value persistence that works over several different database products. The storage type is know as the `StateStore`. In addition to all supported relational (JDBC) databases, there is also support for Amazon DynamoDB and Apache Geode.
| Database | Use |
| ------------------ | ---------- |
| DynamoDB | Production |
| Apache Geode | Production |
| HSQLDB (in-memory) | Testing |
| In-Memory | Testing |
| MariaDB | Production |
| MySQL | Production |
| PostgreSQL | Production |
| YugaByte | Production |
Below you will see [how to use stateful entities](/xoom-lattice/entity-cqrs#statefulentity-example).
### Sourced
The states of `EventSourced` and `CommandSourced` entities are not stored as whole objects. Instead, every such entity maintains a stream of records, each representing a partial state. The individual records of partial state are stored in a `Journal`, and collectively combine to create its state. The word "source" conveys the idea of an official origin, which in this case is a record of partial state. The record may be a fact, such as is captured by a `DomainEvent`. The record may instead be an imperative directive to carry out an operations, known as a `Command`. Persisting one or more `DomainEvent` instances to represent an aggregate's state is known as Event Sourcing. A similar approach in save the `Command` states, such as is generally the case with a [Process](/xoom-lattice/processes) (Manager), is known as Command Sourcing.
A sourced entity is one that owns an ordered collection of records that each indicate a discreet change that was made to the state of that entity. This ordered collection may be likened to an accounting ledger, with one row per change to an account. The changes in a ledger are either debits or credits to the account. Starting from a balance of zero, a credit must be added to the ledger to provide the first available funds. From there the next entry may be another credit, or a debit. Over time there are a number of entries which can be used to derive the account's balance. Starting from the first entry in the ledger, add credits and subtract debits in the order in which they occurred. After applying the addition or subtraction of the last entry in the ledger you know the account's balance.
Now consider that you have a similar ledger, but made up of a sequence of `DomainEvent` instances. Starting with the first `DomainEvent` apply its attributes to the state of the entity that owns the `DomainEvent`. Do the same for every subsequent `DomainEvent` until there are no more. At the end you know the current state of the entity.
The sequence in which the discreet records were produced is strictly maintained because both the records and the order in which they occurred are required to reproduce the accurate and valid state of the entity.
Continuing with the above e-commerce example, the following may be the ordered collection of events for a shopping cart.
| Index | Event Type |
| ----- | -------------------------------------------------- |
| 1 | `com.ecommrus.model.cart.CartCreated` |
| 2 | `com.ecommrus.model.cart.ProductPlacedInCart` |
| 3 | `com.ecommrus.model.cart.ProductQuantityIncreased` |
| 4 | `com.ecommrus.model.cart.ProductPlacedInCart` |
| 5 | `com.ecommrus.model.cart.ProductRemovedFromCart` |
The *Index* column indicates the order in which the event occurred on the given `Cart` entity. The *Event Type* column contains the name of the `DomainEvent` that occurred in the given order. Note that this table does not show the event data along side the type; the actual `Journal` would include the data. Here's what the events indicate.
1. The shopping cart was created on behalf of a user.
2. The user placed a given product into the cart.
3. The user increased the quantity that they require for the product from #2.
4. The user placed an additional product into the cart.
5. The user removed one of their two products from the cart. To know which of the two products was removed, the data of the event must be examined for the product id.
As noted previously the sequence of records may be specializations of `DomainEvent` and `Command`, but are more commonly of type `DomainEvent`. Thus, an entity that is sourced by a sequence of `DomainEvent` instances is Event Sourced. Assuming that the sequence of entries in the collection are DomainEvent types, this collection is known as the entity's *event stream.*
Each entity's event stream is persisted into a `Journal`. This `Journal` is responsible for maintaining two kinds of streams. One kind of stream is the individual stream of each entity. If you have 1 million Event Sourced entity instances in your Bounded Context then the `Journal` will have 1 million individual streams. The second kind of stream is the totally ordered entries of all entities in the entire Bounded Context. That is, as each entity appends new entries into its own stream, those entries are also indexed in a totally ordered stream of all entries. Thus, if each entity has an average of five entries in its individual stream, the totally ordered stream of all entries is 5 million total.
The `Journal` is append only. Once an entry has been appended it may not be (physically) deleted/removed. Further, every discreet entry is immutable.
The following table shows the databases current supporting `Journal`.
| Database | Use |
| ------------------ | ------------ |
| FoundationDB | Experimental |
| HSQLDB (in-memory) | Testing |
| In-Memory | Testing |
| MariaDB | Production |
| MySQL | Production |
| PostgreSQL | Production |
| YugaByte | Experimental |
Below you will see [how to use event sourced and command sourced entities](/xoom-lattice/entity-cqrs#eventsourced).
## Entity Types
`ObjectEntity`, `StatefulEntity`, and `EventSourced` are abstract base classes used in developing DDD models. The `ObjectEntity` supports various forms of relational database mapping, including ORM as in JPA and Hibernate, and Jdbi (a very thin wrapper around JDBC that maps with less pain). You can read more about those [above](/xoom-lattice/entity-cqrs#object-relational-mapping) and [here](/xoom-symbio/object-storage). The `StatefulEntity` doesn't provide mapping, only a key-value store with the aggregate state as a CLOB/BLOB value. This enables using many different kinds of NoSql storage. The `EventSourced` supports Event Sourcing. Consider this simple usage example.
{% hint style="info" %}
Note that when an Entity's applied state and/or events are persisted, [actor message stowage](/xoom-actors#stowage) is used for non-blocking operational pauses until the persistence success or failure is confirmed.
{% endhint %}
### `ObjectEntity` Example
An actor that serves as a domain model entity may be designed extending the `ObjectEntity` type. The `ObjectEntity` should implement a protocol that defines the behavior available through message sending and delivery. Its state is stored in an `ObjectStore`.
Here is a `CartEntity` that extends `ObjectEntity` and implements the `Cart` protocol.
```java
import io.vlingo.xoom.lattice.model.object.ObjectEntity;
public class CartEntity extends ObjectEntity implements Cart {
private CartState cartState;
...
public CartEntity(String cartId, String userId) {
super(idFrom(":", cartId, userId));
this.cartState = CartState.initial(cartId, userId);
}
}
```
An `ObjectEntity` should receive its unique identity by means of its constructor, making the identity available during its initialization. If the entity is preexisting, the identity is used during actor startup to reconstitute its state from the `ObjectStore`.
The following shows how a command message is handled and the state and event is persisted using a `ObjectStore` via the `ObjectEntity`.
```java
import io.vlingo.xoom.lattice.model.object.ObjectEntity;
public class CartEntity extends ObjectEntity implements Cart {
private CartState cartState;
...
public void placeProductInCart(Product product) {
val productPlacedInCart =
ProductPlacedInCart.with(product.sku, product.description, product.price);
apply(cartState.withSelected(product), productPlacedInCart);
}
...
}
```
The `ObjectEntity` provides a means to `apply()` a new state and concrete `DomainEvent` instances. In the above example a new `CartState` instance and a `ProductPlacedInCart` are applied together. The `apply()` causes four processing steps.
1. The `CartEntity` message processing is temporarily suspended until the following step 2 and step 3 are completed.
2. The new `CartState` and the `ProductPlacedInCart` event are asynchronously and atomically persisted to the backing `ObjectStore`.
3. The persistence is confirmed. At that time the overridden `stateObject(CartState)` method is called to replace the current `cartState` with the new value. You can see this overridden method in the below code snippet displaying the overridden protected methods.
4. The `CartEntity` message processing is restored, allowing subsequent messages, such as commands, to be handled.
{% hint style="info" %}
The `ObjectEntity` concrete type may not process its next messages until the current state transition and any events are fully applied. The same entity's state must not transition until the new state's persistence is confirmed.
The above steps 1-4 are processed asynchronously; that is, the entity does not block a thread while these steps are carried out.
{% endhint %}
In the following case the command message handler is augmented to answer an eventually available, guaranteed stored state of the entity. The message handler method would need to change as follows.
```java
import io.vlingo.xoom.lattice.model.object.ObjectEntity;
public class CartEntity extends ObjectEntity implements Cart {
private CartState cartState;
...
public Completes placeProductInCart(Product product) {
val productPlacedInCart =
ProductPlacedInCart.with(product.sku, product.description, product.price);
return apply(
cartState.withSelected(product),
productPlacedInCart,
() -> cartState);
}
...
}
```
In the above example, notice that the protocol has been changed to support a `Completes` return value, specifically `Completes`. The `Completes` protocol is [explained here](/xoom-common#completes). The `apply(...)` method now provides a return value, and it also takes a parameter to supply the final `cartState` value as the contents of the `Completes`. The `apply()` causes five processing steps.
1. The `CartEntity` message processing is temporarily suspended until steps 2 and 3 are completed.
2. The new `CartState` and the `ProductPlacedInCart` event are asynchronously and atomically persisted to the backing `ObjectStore`.
3. When the persistence is confirmed, the overridden `stateObject(CartState)` method is called to replace the current `cartState` with the new value. You can see this overridden method in the below code snippet displaying the overridden protected methods.
4. The `CartEntity` message processing is restored, allowing subsequent messages, such as commands, to be handled.
5. The newly stored `cartState` instance that was replaced by the `stateObject()` method (next example) is used to complete the `Completes` outcome value.
Every concrete `ObjectEntity` must override a few methods.
```java
import io.vlingo.xoom.lattice.model.object.ObjectEntity;
public class CartEntity extends ObjectEntity implements Cart {
private CartState cartState;
...
@Override
protected CartState stateObject() {
return cartState;
}
@Override
protected void stateObject(final CartState stateObject) {
this.cartState = stateObject;
}
@Override
protected Class stateObjectType() {
return CartState.class;
}
@Override
protected Tuple2>> whenNewState() {
// answer a Tuple2 if the context is an intial state; otherwise null
if (cartState.isInitial()) {
return Tuple2.of(cartState, Arrays.asList(new CartCreated(...)));
}
return null;
}
}
```
These methods support the `ObjectEntity` abstract base in interacting with the `ObjectStore` in behalf of the concrete `CartEntity`.
* The `stateObject()` answers the `CartEntity` current `CartState` value.
* The `stateObject(CartState)` provides a new state to replace the previous state. This is called following the restoration of the `CartState` from persistence when the `CartEntity` is being (re)started from an existing state, and following the persistence of a new state and zero or more events.
* The `stateObjectType()` answers the Class\ of the specific entity, which in this case is `CartState.class`.
* The `whenNewState()` is an optional override if it is desired to provide an initial state to be persisted only when the Entity has been newly created. In this example, when the `cartState` is considered initial, the `whenNewState()` answers a `Tuple2` of a `CartState` and a `List>`. If the `cartState` has already transitioned past its initial state, answer `null` and state restoration from the `ObjectStore` is attempted instead.
Read the [API documentation](https://javadoc.io/doc/io.vlingo/vlingo-lattice/latest/io/vlingo/lattice/model/object/ObjectEntity.html) for more details.
#### `ObjectTypeRegistry`
In order to introduce your concrete entity types to the underlying `ObjectStore` persistence mechanism that is used by the `ObjectEntity` abstract base, you must register each one with the `ObjectTypeRegistry`.
```java
import io.vlingo.xoom.lattice.model.object.ObjectTypeRegistry;
import io.vlingo.xoom.symbio.store.object.StateObjectMapper;
ObjectTypeRegistry registry = new ObjectTypeRegistry(world);
StateObjectMapper cartStateMapper =
StateObjectMapper.with(
CartState.class,
JdbiPersistMapper.with(
insertQuery,
updateQuery,
SqlStatement::bindFields),
new CartStateMapper());
String cartQuery = "SELECT FROM TBL_CARTS ...";
Info cartInfo =
new Info(
objectStore,
CartState.class,
"Cart-Database",
MapQueryExpression.using(
Cart.class,
cartQuery,
MapQueryExpression.map("cartId", "")),
cartStateMapper);
registry.register(cartInfo);
```
The above code registers a mapper for the `Cart` and `CartState` using a Jdbi mapping.
1. The `ObjectTypeRegistry` is created within the `World` that is used by the service.
2. The `StateObjectMapper` is created for the `CartState`.
3. An `ObjectTypeRegistry.Info` instance is created, which holds the components necessary to persist and query a `CartState` via the `Cart` implementor `CartEntity`. The `Info` holds: (a) the `ObjectStore` that persists `CartState`, (b) the type that is persisted, in this case`CartState.class`, (c) an identifying name given to the store, (d) a `QueryExpression`, in this case a `MapQueryExpression`, that uses the `cartQuery` that takes as a parameter `cartId`, and (e) the previously created `StateObjectMapper` for `CartState` instances.
4. The `ObjectTypeRegistry` is then used to register the `Info`, enabling these to be supportable by the XOOM Lattice `ObjectEntity`.
You must register such an `ObjectTypeRegistry.Info` for every model type and state type, as was done above for `Cart` and `CartState`, respectively.
### `StatefulEntity` Example
An actor that serves as a domain model entity may be designed extending the `StatefulEntity` type. The `StatefulEntity` should implement a protocol that defines the behavior available through message sending and delivery.
Here is a `CartEntity` that extends `StatefulEntity` and implements the `Cart` protocol.
```java
import io.vlingo.xoom.lattice.model.object.ObjectEntity;
public class CartEntity extends StatefulEntity implements Cart {
private CartState cartState;
...
public CartEntity(String cartId, String userId) {
super(":", cartId, userId);
this.cartState = CartState.initial(cartId, userId);
}
}
```
A `StatefulEntity` should receive its unique identity by means of its constructor, making the identity available during its initialization. If the entity is preexisting, the identity is used during actor startup to reconstitute its state from the `StateStore`.
The following shows how a command is handled by a `StatefulEntity` to persist the new state and any events using the underlying `StateStore`. Notice that the interface for applying the state and event are identical to the `ObjectEntity` interface.
```java
import io.vlingo.xoom.lattice.model.stateful.StatefulEntity;
public class CartEntity extends StatefulEntity implements Cart {
private CartState cartState;
...
public void placeProductInCart(Product product) {
val productPlacedInCart =
ProductPlacedInCart.with(product.sku, product.description, product.price);
apply(cartState.withSelected(product), productPlacedInCart);
}
...
}
```
The `StatefulEntity` provides a means to `apply()` a new state and concrete `DomainEvent` instances. In the above example a new `CartState` instance and a `ProductPlacedInCart` are applied together. The `apply()` causes four processing steps.
1. The `CartEntity` message processing is temporarily suspended until steps 2 and 3 are completed.
2. The new `CartState` and the `ProductPlacedInCart` event are asynchronously and atomically persisted to the backing `StateStore`.
3. When the persistence is confirmed, the overridden `state(CartState)` method is called to replace the current `cartState` with the new value. You can see this overridden method in the following code snippet.
4. The `CartEntity` message processing is restored, allowing subsequent messages, such as commands, to be handled.
{% hint style="info" %}
The `StatefulEntity` concrete type may not process its next messages until the current state transition and any events are fully applied. The same entity's stated must not transition until the new state's persistence is confirmed.
The above steps 1-4 are processed asynchronously; that is, the entity does not block a thread while these steps are carried out.
{% endhint %}
In the following case the command message handler is augmented to answer an eventually available, guaranteed stored state of the entity. The message handler method would need to change as follows.
```java
import io.vlingo.xoom.lattice.model.stateful.StatefulEntity;
public class CartEntity extends StatefulEntity implements Cart {
private CartState cartState;
...
public Completes placeProductInCart(Product product) {
val productPlacedInCart =
ProductPlacedInCart.with(product.sku, product.description, product.price);
return apply(
cartState.withSelected(product),
productPlacedInCart,
() -> cartState);
}
...
}
```
In the above example, notice that the protocol has be changed to support a `Completes` return value, specifically `Completes`. The `Completes` protocol is [explained here](/xoom-common#completes). The `apply(...)` method now provides a return value, and it also takes a parameter to supply the final `cartState` value as the contents of the `Completes`. The `apply()` causes five processing steps.
1. The `CartEntity` message processing is temporarily suspended until steps 2 and 3 are completed.
2. The new `CartState` and the `ProductPlacedInCart` event are asynchronously and atomically persisted to the backing `ObjectStore`.
3. When the persistence is confirmed, the overridden `stateObject(CartState)` method is called to replace the current `cartState` with the new value. You can see this overridden method in the below code snippet displaying the overridden protected methods.
4. The `CartEntity` message processing is restored, allowing subsequent messages, such as commands, to be handled.
5. The newly stored `cartState` instance that was replaced by the `stateObject()` method (next example) is used to complete the `Completes` outcome value.
Every concrete `StatefulEntity` must override a few methods.
```java
import io.vlingo.xoom.lattice.model.DomainEvent;
import io.vlingo.xoom.lattice.model.stateful.StatefulEntity;
public class CartEntity extends StatefulEntity implements Cart {
private CartState cartState;
...
@Override
protected void state(final CartState state) {
this.cartState = state;
}
@Override
protected Class stateType() {
return CartState.class;
}
@Override
protected Tuple3>> whenNewState() {
// answer a Tuple2 if the context is an intial state; otherwise null
if (cartState.isInitial()) {
return Tuple3.of(cartState, Arrays.asList(new CartCreated(...)), "created");
}
return null;
}
}
```
These methods support the `StatefulEntity` abstract base in interacting with the `StateStore` in behalf of the concrete `CartEntity`.
* The `id()` answers the `String` unique identity of the `CartEntity`.
* The `state(CartState)` provides a new state to replace the previous state. This is called following the restoration of the `CartState` from persistence when the `CartEntity` is being (re)started from an existing state, and following the persistence of a new state and zero or more events.
* The `stateType()` answers the concrete state type, such as the `Class`.
* The `whenNewState()` is an optional override if it is desired to provide an initial state to be persisted, but only when the Entity has been newly created. The `whenNewState()` is called each time the `CartEntity` actor is started. On the initial start just following the first ever construction of the entity, this method offers the opportunity to provide the initial state to be applied. The offer may be ignored by not overriding this method, as the default answers `null`. If this method is called at any other time other than the first ever construction of the entity, it must answer `null`. In this example, when the `cartState` is considered initial, the `whenNewState()` answers a `Tuple3` of a `CartState`, a `List>`, and the `"created"` operation which caused it. If the `cartState` has already transitioned past its initial state, answer `null` and state restoration from the `ObjectStore` is attempted instead.
Read the [API documentation](https://javadoc.io/doc/io.vlingo/vlingo-lattice/latest/io/vlingo/lattice/model/stateful/StatefulEntity.html) for more details.
#### `StatefulTypeRegistry`
In order to introduce your concrete entity types to the underlying `StateStore` persistence mechanism that is used by the `StatefulEntity` abstract base, you must register each one with the `StatefulTypeRegistry`.
```java
import io.vlingo.xoom.lattice.model.stateful.StatefulTypeRegistry;
import io.vlingo.xoom.symbio.store.state.dynamodb.DynamoDBStateActor;
import io.vlingo.xoom.symbio.store.state.StateStore;
StateStore store = world.actorFor(StateStore.class, DynamoDBStateActor.class, dispatcher);
registry = new StatefulTypeRegistry(world);
registry.register(new Info<>(store, CartState.class, CartState.class.getSimpleName()));
```
You must register such an `StateTypeRegistry.Info` for every state type, as was done above for `CartState`.
### `EventSourced` Example
An actor that serves as a domain model entity may be designed as an extension to the `EventSourced` type. The `EventSourced` should implement a protocol that defines the behavior available through message sending and delivery.
Here is a `CartEntity` that extends `EventSourced` and implements the `Cart` protocol.
```java
import io.vlingo.xoom.lattice.model.object.ObjectEntity;
public class CartEntity extends EventSourced implements Cart {
private CartState cartState;
...
public CartEntity(String cartId, String userId) {
super(); // use the actor address as unique identity
this.cartState = CartState.initial(cartId, userId);
}
}
```
An `EventSourced` may receive its unique identity by means of its constructor, or it may provide no identity, in which case the actor's address will be used. Either way, this makes the identity available during the entity's initialization. If the entity is preexisting, the identity is used during actor startup to reconstitute its state from the `Journal`.
The following shows how a command is handled by an `EventSourced` to persist events using the underlying `Journal`. Notice that the interface for applying the event(s) is different from the `ObjectEntity` and `StatefulEntity`.
```java
import io.vlingo.xoom.lattice.model.sourcing.EventSourced;
public class CartEntity extends EventSourced implements Cart {
private CartState cartState;
...
public void placeProductInCart(Product product) {
val productPlacedInCart =
ProductPlacedInCart.with(product.sku, product.description, product.price);
apply(productPlacedInCart);
}
...
}
```
In the case of `EventSourced` the state is not automatically persisted because it is not generally needed. The events themselves represent the state of the cart, as [explained above](/xoom-lattice/entity-cqrs#sourced). You'll next see how the state is persisted if the conditions exist to justify that.
The unique identity of the entity is set in the base constructor in the `streamName` immutable variable.
```java
protected final String streamName;
```
In the case of `Sourced` entities, such as `EventSourced`, the implementor will be asked if they would like to include a snapshot of the state at any given point of `apply()`. The concrete `EventSourced`, in this case `CartEntity`, may do so using the following override.
```java
@Override
protected CartSate snapshot() {
return cartState;
}
```
Notice, however, that this example unconditionally provides the `CartState` instance as a snapshot in all cases. This is generally not desirable because it is probably not necessary. In fact snapshots are generally only useful when a given entity may have many, many events associated with it. In such cases it is best to use a heuristic metric to determine when a snapshot is necessary, where the metric is based on some point where the performance of entity reconstitution starts to degrade with many events.
For example, say that you have an entity that could have thousands of items in it. This might be a large order being populated with a many products from a warehouse. To solve the overhead of loading all events from the `Journal`, you may decide to take a snapshot at every 250th event.
```java
@Override
protected OrderState snapshot() {
return currentVersion() % 250 == 0 state : null;
}
```
The `currentVersion()` provides a 1-based version or sequence number of the next event to be appended to the `Journal`; that is, the first of potentially multiple events currently being applied. In the above example the snapshot of the `OrderState` will only be provided every 250th event. Otherwise `null` is answered to prevent a snapshot from being persisted along with the event(s).
{% hint style="info" %}
If any given command message handler produces multiple events, it is possible for the above calculation to be inexact.
{% endhint %}
If using snapshots, the following method must be overridden in order to apply the most recent snapshot to the entity's state when the entity is being reconstituted.
```java
...
protected void restoreSnapshot(final OrderState snapshot, final int currentVersion) {
this.state = snapshot;
}
...
```
Another useful tool is `asList()`, which places multiple events into a `List` that may be passed to the respective `apply()` methods. For example, it's possible that a shopping cart is created by the user selecting the currently viewed product into a new cart.
```java
public void createCartWithFirstProduct(...) {
apply(asList(new CartCreated(...), new ProductPlacedInCart(...)));
}
```
The `EventSourced` provides a means to `apply()` one or more concrete `DomainEvent` instances. In the above example a new `CartCreated` and `ProductPlacedInCart` are applied together. The `apply()` causes five processing steps.
1. The `CartEntity` message processing is temporarily suspended until steps 2 and 3 are completed.
2. The `snapshot()` is used to determine whether or not a snapshot instance should be persisted with the events. If not, the `snapshot()` will answer `null`. The default is to never provide snapshots.
3. The new `CartCreated` and `ProductPlacedInCart` events are asynchronously and atomically appended to the backing `Journal`.
4. When the persistence is confirmed, a registered event-specific method is called, once for each applied event, to transition the current `cartState` with based on the new event value. You can see examples in the below code snippet.
5. The `CartEntity` message processing is restored, allowing subsequent messages, such as commands, to be handled.
{% hint style="info" %}
The `EventSourced` concrete type may not process its next messages until the events are fully applied. The same entity's stated must not transition until the state's storage is confirmed.
The above steps 3 and 4 are processed asynchronously; that is, the entity does not block a thread while these steps are carried out.
{% endhint %}
Every concrete `EventSourced` must register an event-specific method transition from the current state to a new state for each newly applied event.
```java
import io.vlingo.xoom.lattice.model.sourcing.EventSourced;
public class CartEntity extends EventSourced implements Cart {
private CartState cartState;
...
static {
registerConsumer(CartEntity.class, CartCreated.class, CartEntity::applyCartCreated);
registerConsumer(CartEntity.class, ProductPlacedInCart.class, CartEntity::applyProductPlacedInCart);
...
}
private void applyCartCreated(CartCreated event) {
cartState = CartState.initial(event.cartId, event.userId);
}
private void applyProductPlacedInCart(ProductPlacedInCart event) {
Product product = new Product(event.productId, event.quantity, event.price);
cartState = cartState.withProduct(product);
}
...
}
```
Following the confirmation of the `CartCreated` event being stored, the `EventSourced` base class calls `applyCartCreated()` with the `CartCreated` instance. This gives the `CartEntity` the opportunity to transition the `CartState` to the new value, which in this case is its initial value.
Following the confirmation of the `ProductPlacedInCart` event being stored, the `EventSourced` base class calls `applyProductPlacedInCart()` with the new `ProductPlacedInCart` instance. This gives the `CartEntity` the opportunity to transition the `CartState` to the new value to include the newly placed product.
Read the [API documentation](https://javadoc.io/doc/io.vlingo/vlingo-lattice/latest/io/vlingo/lattice/model/sourcing/Sourced.html) for more details on all possible overrides. Note that all of the above applies also to the `CommandSourced`, with the same [API documentation](https://javadoc.io/doc/io.vlingo/vlingo-lattice/latest/io/vlingo/lattice/model/sourcing/EventSourced.html).
#### `SourcedTypeRegistry`
In order to introduce your concrete entity types to the underlying `Journal` persistence mechanism that is used by the `EventSourced` abstract base, you must register each one with the `SourcedTypeRegistry`.
```java
import io.vlingo.xoom.lattice.model.sourcing.SourcedTypeRegistry.Info;
import io.vlingo.xoom.symbio.store.common.jdbc.Configuration;
import io.vlingo.xoom.symbio.store.journal.Journal;
...
journal = world.actorFor(Journal.class, JDBCJournalActor.class, configuration);
registry = new SourcedTypeRegistry(world);
Info info = new Info(journal, CartEntity.class, CartEntity.class.getSimpleName());
registry.register(info);
```
You must register such an `SourcedTypeRegistry.Info` for every state type, as was done above for `CartState`.
### Summary
In all cases, the new state and/or events are persisted asynchronously and safely replaced on the entity instance when reconstituted. The `apply()` handles all that for you, but without involving the aggregate designer in persistence, and minus technical naming. There are no race conditions or conflicting operation results, or failed persistence due to a database consistency violation.
## Modeling State
In all of the above entity examples there is a single state object held by each of the entity types, the `CartState` type. This approach has several advantages.
* There is only one variable to manage for all state, including one or more identities and all state that may transition over time.
* Less state objects to manage requires less ongoing cognition.
* The state is immutable, which makes the state simpler to maintain and reason about.
* The state has a side-effect-free, intention-revealing interface, resulting in states transitioning by being fully replaced.
* The state transitions one operation at a time, with each transition clearly focused on a single reason for replacement.
Such a state object may be designed as follows.
```java
public final class CartState {
public final String cartId;
public final List products;
public final String userId;
public static CartState initial(String cartId, String userId) {
new CartState(cartId, userId);
}
public CartState withProduct(Product product) {
new CartState(cartId, userId, place(product));
}
private CartState(String cartId, String userId) {
this(cartId, userId, new ArrayList<>(0));
}
private CartState(String cartId, String userId, List products) {
this.cartId = cartId;
this.userId = userId;
this.products = products;
}
private List place(Product product) {
List products = new ArrayList(products);
products.add(product);
return Collections.unmodifiableList(products);
}
}
```
Note that the instance variables are all declared `public final`, making accessor methods unnecessary because clients may directly access the immutable variables. A functional style of programming is employed, which is named referential transparency. That is, the value outcome of a function may be replaced by the value itself. The benefit is the reduction of the cognitive overhead of the interface. Yet, this means that you must take care to design naturally mutable objects, such as `List`, as immutable. The above example employs `Collections.unmodifiableList()` to make the `products` immutable so that client access may not directly change the list without the `CartState` knowledge.
You may easily add support for other concepts in the state type, such as collections of `Coupon` or `DiscountCode` instances, depending on you Ubiquitous Language. All such additions would focus on only the changes necessary to support the `CartEntity` commands.
## Querying a StateStore
XOOM Lattice provides a specialized query component for querying a `StateStore` asynchronously. It is the abstract base class `StateStoreQueryActor`.
```java
import io.vlingo.xoom.lattice.query.StateStoreQueryActor;
public class ProductQueriesActor extends StateStoreQueryActor implements ProductQueries {
public ProductQueriesActor(final StateStore stateStore) {
super(stateStore);
}
// implement ProductQueries
public Completes productCategoryOf(final String category) {
return queryStateFor(category, ProductCategoryView.class);
}
public Completes productOf(final String productId) {
return queryStateFor(productId, ProductView.class);
}
}
```
Use the `StateStoreQueryActor` to quickly implement queries of various kinds on the `StateStore` .
## `StateAdapter` and `StateAdapterProvider`
All store types, `ObjectStore`, `StateStore`, and `Journal`, serialize state objects to `State` instances. Some stores must serialize state objects in order to persist them, while others do not. In the case of `StateStore` and `Journal`, the states are indeed serialized for the sake of persistence. On the other hand, the `ObjectStore` will always map state to a row and columns, and thus does not use a serialized `State` to persist. Even so, `ObjectStore` will still always serialize the state to a `State` for the purpose of post persistence processing. Therefore, every state type must use a `StateAdapter`.
```java
import io.vlingo.xoom.common.serialization.JsonSerialization;
import io.vlingo.xoom.symbio.BaseEntry.TextEntry;
import io.vlingo.xoom.symbio.StateAdapter;
import io.vlingo.xoom.symbio.Metadata;
public class CartStateAdapter implements StateAdapter {
@Override
public int typeVersion() {
return 1;
}
@Override
public CartState fromRawState(final TextState raw) {
return JsonSerialization.deserialized(raw.data, CartState.class);
}
@Override
public ST fromRawState(final TextState raw, final Class stateType) {
return JsonSerialization.deserialized(raw.data, stateType);
}
@Override
public TextState toRawState(CartState state, int stateVersion, Metadata metadata) {
final String serialization = JsonSerialization.serialized(state);
return new TextState(state.id, CartState.class, typeVersion(), serialization, stateVersion, metadata);
}
@Override
public TextState toRawState(final String id, final CartState state, final int stateVersion, final Metadata metadata) {
final String serialization = JsonSerialization.serialized(state);
return new TextState(id, CartState.class, typeVersion(), serialization, stateVersion, metadata);
}
}
```
{% hint style="info" %}
Initially it is not necessary to create a `StateAdapter` during early development if you are using the text edition of a given store, such as `ObjectStore`, `StateStore`, or `Journal`. Instead you may benefit from the `DefaultTextStateAdapter`. This default adapter is used when no adapter is registered for a given state type.\
\
However, when state types change, you must definitely implement adapters for the changing types. In this case the adapters play an important role of upgrading, referred to as upcasting, the persisted `State` to the new version of the state type.
See: `io.vlingo.xoom.symbio.DefaultTextStateAdapter`
{% endhint %}
To make the adapters available to stores, use the `StateAdapterProvider`.
```java
import io.vlingo.xoom.symbio.StateAdapterProvider;
StateAdapterProvider stateAdapterProvider =
StateAdapterProvider.instance(world);
stateAdapterProvider.registerAdapter(
CartState.class, new CartStateAdapter());
```
## `EntryAdapter` and `EntryAdapterProvider`
When using domain events, `Source` types, such as concrete `DomainEvent` types, may be persisted to a store database. Such `DomainEvent` instances, such as `CartCreated` and `ProductAddedToCart`, must be serialized to a form that can be inserted into the underlying database as an instances of `Entry`. Two types of `Entry` are supported, `TextEntry` and `BinaryEntry`. The `TextEntry` is backed by a `String`, which is appropriate for serializing with JSON. The `BinaryEntry` is backed by a `byte[]`, which may be used to hold the result of binary serialization (e.g. Protobuf and Avro).
{% hint style="info" %}
It is strongly advised to never use Java default serialization. If you are unaware why, search for `"problems with Java serialization"`.
{% endhint %}
Adapters are created by implementing `EntryAdapter`. These adapt `Source` instances to `Entry` instances, and `Entry` instances to `Source` instances. For example, `CartCreated` instances may be adapted to `TextEntry` instances, and the same `TextEntry` instances adapted back to the corresponding `CartCreated` instances. Such an adapter would be named `CartCreatedAdapter`.
```java
import io.vlingo.xoom.common.serialization.JsonSerialization;
import io.vlingo.xoom.symbio.BaseEntry.TextEntry;
import io.vlingo.xoom.symbio.EntryAdapter;
import io.vlingo.xoom.symbio.Metadata;
public final class CartCreatedAdapter implements EntryAdapter {
@Override
public CartCreated fromEntry(TextEntry entry) {
return JsonSerialization.deserialized(entry.entryData(), CartCreated.class);
}
@Override
public TextEntry toEntry(CartCreated source, Metadata metadata) {
String serialization = JsonSerialization.serialized(source);
return new TextEntry(CartCreated.class, 1, serialization, metadata);
}
@Override
public TextEntry toEntry(CartCreated source, String id, Metadata metadata) {
String serialization = JsonSerialization.serialized(source);
return new TextEntry(id, CartCreated.class, 1, serialization, metadata);
}
@Override
public TextEntry toEntry(CartCreated source, int version, String id, Metadata metadata) {
final String serialization = JsonSerialization.serialized(source);
return new TextEntry(id, CartCreated.class, 1, serialization, version, metadata);
}
}
```
The `EntryAdapter` provides three overloaded methods for adapting from a `Source` to an `Entry`, and one for adapting from `Entry` to `Source`. In the above example the `Source` type `CartCreated` is adapted to a `TextEntry` using JSON, and the persisted `TextEntry` back to a `CartCreated`.
{% hint style="info" %}
Initially it is not necessary to create an `EntryAdapter` during early development if you are using the text edition of a given store, such as `ObjectStore`, `StateStore`, or `Journal`. Instead you may benefit from the `DefaultTextEntryAdapter`. This default adapter is used when no adapter is registered for a given `Source` type.\
\
However, when `Source` types change, you must definitely implement adapters for the changing types. In this case the adapters play an important role of upgrading, referred to as upcasting, the persisted `Entry` to the new version of the `Source`type.
See: `io.vlingo.xoom.symbio.DefaultTextEntryAdapter`
{% endhint %}
To make the adapters available to stores, use the `EntryAdapterProvider`.
```java
import io.vlingo.xoom.symbio.EntryAdapterProvider;
EntryAdapterProvider entryAdapterProvider =
EntryAdapterProvider.instance(world);
entryAdapterProvider.registerAdapter(
CartCreated.class, new CartCreatedAdapter());
entryAdapterProvider.registerAdapter(
ProductAddedToCart.class, new ProductPlacedInCartAdapter());
...
```
# Grid
Use XOOM LATTICE as a distributed data and compute grid where actors can send messages to other actors across a cluster of a few or many nodes.
This **XOOM LATTICE** component provides an API for distributed computations and data processing across multiple nodes in a cluster. It supports distributed parallel processing by sending computational execution requests to actors on any node in a [**XOOM CLUSTER**](/xoom-cluster) with the potential to receive results in return, if the protocol specifies a completable future outcome. This as well as elastic resiliency are embodied in the **XOOM LATTICE Grid**.
## Using the Grid
The **XOOM LATTICE Grid** is a distributed compute construct that is implemented as a **XOOM ACTORS** [`Stage`](/xoom-actors#a-stage-for-actors). The `Grid` API is the same as you would expect from any `Stage` with one exception: the `Actor` implementations that should be started on a `Grid` must have a grid-compatible `Address`. There are no other requirements, such as implementing a special interface or extending an abstract base class.
To start the `Grid` use one of the static `Grid.start(...)` methods. You may then start any actor that has a grid-compatible `Address` as you would normally do on a `Stage`.
```java
final Grid grid = Grid.start("product-service", "product-grid");
final Product product = grid.actorFor(Product.class, ProductEntity.class);
```
In the above example the `ProductEntity` actor instance is assigned a grid-compatible `Address`, and is therefore reachable by any message sender on the `Grid`.
### Using Models On the Grid
All **XOOM LATTICE** base [model types](/xoom-lattice/entity-cqrs) are compatible with the grid without any changes. The following are the types.
```java
// model entities
import io.vlingo.lattice.model.sourcing.EventSourced;
import io.vlingo.lattice.model.sourcing.CommandSourced;
import io.vlingo.lattice.model.object.ObjectEntity;
import io.vlingo.lattice.model.stateful.StatefulEntity;
// model processes (a.k.a. sagas)
import io.vlingo.lattice.model.process.ObjectProcess;
import io.vlingo.lattice.model.process.SourcedProcess;
import io.vlingo.lattice.model.process.StatefulProcess;
```
Use all of these base types as you would if not using the grid.
### Grid Actor Distribution
Each node in the grid has a representative abstraction name `GridNode`. Each `GridNode` in the cluster has a copy of a *hash ring* data structure. Without going into details on how a hash ring works, it is used to determine where in the cluster a given actor is to be distributed and subsequently found within the grid. An actor's node location is determined by where the hash of its `Address` distributes on the hash ring data structure. For example, if there are three nodes in the cluster, each actor `Address` must hash into one of the three nodes. This means that a given actor purposely has a single instance in a single grid node in the cluster; that is, that one actor instance is pinned to a given node.
When a message is sent to a grid-compatible actor, the grid node of the message sender looks up in the hash ring for the node on which that actor is located. The message is then serialized and sent over the network to that node. The receiving grid node searches up the actor locally and delivers the message through the actor's mailbox.
There is, of course, an optimization if the message is sent to an actor that is on the same node as the sender. Such a condition delivers the message directly through the target actor's mailbox without any network overhead.
### Scenarios
There are several grid operational scenarios to be aware of. Although service and application developers will not need to do anything special when creating actors in the grid and sending messages from many client actors to many target actors, it is useful to understand the common scenarios.
{% hint style="info" %}
Some of the support for the following scenarios is strictly handled by the cluster. In such cases the local grid node is involved only to update its knowledge of the current cluster conditions. Such include updating its hash ring and providing the service/application with a status that indicates that this node is considered healthy and operational.
{% endhint %}
#### Actor-To-Actor Message
An actor on a given grid node sends a message to an actor on a grid node somewhere in the cluster. The sender has a protocol reference to the target actor and sends a message via a protocol method invocation. The target actor's grid-compatible `Address` is used to look up the grid node on which it is pinned. The message is serialized, sent across a network socket channel to the node of the target actor, deserialized, and delivered to the actor via its mailbox.
It is possible/likely that some sender actors will be on the same node as the target actor. In that case, the message send is optimized and delivered directly to the actor's mailbox.
#### Node Experiences a Network Partition
A node that experiences a network partition will fail to receive continuous health updates from other nodes that can no longer see it. The partitioned node will be considered lost from the other nodes that can't see it, and that node will in short time understand that it has lost the cluster quorum with the other cluster nodes (as per the **XOOM CLUSTER** [specification](/xoom-cluster#cluster-health-quorum-and-leadership)). This partitioned node then enters into an idle state. When the node understands that it is in an idle state it will provide this information to the clients running in the local node.
In some network partition cases any N nodes out of M total may see each other, and yet there must be P nodes excluded from the cluster. In the case of a three-node cluster, N=2, M=3, and P=1.
One of the N nodes will be elected leader of the quorum. Any node in the set of P that is not seen by the leader will be prevented from entering the cluster. Should any partitioned node within the set of P claim to be leader among the N and/or P nodes that it can see (it has the highest value node id among any other nodes it can see), the nodes that receive its declaration of leadership will reject that claim. In turn any of the rejecting nodes will inform the failed leadership-declaring node (within P) of the real leader (within N) that it recognizes. This is strictly handled by the cluster and involves the grid only to provide information that it is not in the cluster quorum.
#### Node Leaves
A node that is downed within the cluster has left it, which will be communicated to all remaining nodes.
The actors that were distributed to the node that left must continue to operate within the grid on the nodes still in the cluster quorum. Thus, the actors that would otherwise be lost can be recovered onto a different node. Consider the following types of recovery.
* Actors with ephemeral or transient state, and model actors that have persistent state, will be recovered on a different node according to the adjusted hash ring. This will not actually occur until a message is sent to any such actor.
* Actors that have non-transient state but that are not persistent model actor types cannot be fully recovered on other nodes with the state they previously held on the downed node. One way to ensure that the actor state can be maintained is to place in a **XOOM LATTICE** **Space***.* A Space is a distributed, in-memory, key-value store. As long as the cluster nodes remain running on which a given Space key-value is persistent in memory, any actor using that Space key-value can restore from that state as needed.
#### Node Joins
A node that newly joins a cluster will cause the hash ring to adjust to that node, meaning that the actors that were on any preexisting nodes may be repartitioned on to one or more other nodes. In other words, a node joining the cluster changes the hashing results because there are now more nodes than previously available.
This repartitioning could be quite expensive if the actors were to be immediately relocated. Instead what happens is the same that occurs when a cluster node leaves. The recovery onto a different node will occur only when a message is sent to any such relocated actor.
The implementation of the typical scenario is: when the cluster node updates its hash ring to include the newly joined node, it scans its internal directory for actors whose Address indicates that they no longer belong, and evicts those actors. The actors evicted from that node will not be repartitioned until receiving their next message. Any messages for the evicted actors that are received latently are relayed to the node that now contains the given actors.
There are a few challenges to this typical scenario.
* An evicted actor with messages still in its mailbox must be given the opportunity to process those messages. Thus, before evicting such an actor, its remaining mailbox messages must be sent to the grid node that is now responsible for it.
* It is possible that when multiple nodes are joining within a short time frame, or one or more nodes leave the cluster near the same time as one or more joining, there may be some shuffling of actors until the repartitioning settles. The best that a given evicting node can do is relay received messages to actors that it is no longer responsible for to the node it currently understands to be the one hosting such actors. This will cause some additional latency.
There is no way to avoid these challenges, because there is no way for a given node to predict that something about the cluster will change just following its update of its own hash ring.
{% hint style="info" %}
In distributed computing, there is no now.
{% endhint %}
Yet, these challenges do emphasize that the eviction process must be asynchronous to the ongoing receipt of cluster health and actor targeted messages. That enables the node to immediately update its hash ring to its current understanding of possible ongoing cluster changes. As a result, the asynchronous eviction process has the opportunity to check for a possible refreshed hash ring as it decides whether or not to evict a given actor, and if evicted, which node should receive it's messages—at least as of that very instant in time.
### Dealing with Grid Heap Pressure (Memory Highwater Mark)
If you are using the XOOM Lattice Grid you likely will need assistance from the actor infrastructure to deal with heap pressure; that is, reaching a point where application/service memory is becoming scarce. (This situation might also be called a "highwater mark.") Using the [Actor Eviction Service can help with this, which you will learn about under the Actors chapter](/xoom-actors#automatic-eviction-of-seldom-used-actors).
Recall that a `Grid` is a specialization (extension) of `Stage`. When a `Grid` is instantiated, its construction process [forces the eviction service to be enabled](/xoom-actors#stage-directory-eviction-service) on its behalf. This is accomplished by using either a default configuration or the one configured through the XOOM Actors plugin configuration, but the `enabled` flag is force-set to `true` regardless of what is configured by default (suggested disabled). Note that this has no effect on other `Stage` instances, such as the default `Stage`. To reiterate, the forced enablement is performed only for a `Grid` as it is being newly instantiated, and it will remain in effect for the lifetime of the `Grid`.
# Exchange
Using the VLINGO XOOM message and event exchange across Bounded Contexts.
This **XOOM LATTICE** component provides an `Exchange` abstraction over Publish-Subscribe messaging for exchanges or topics. This is a means to publish messages to exchanges/topics inside or outside your current application/service, and to subscribe to such messages. The `Exchange` provides translators from internal to external message types, and from external to internal message types.
## Understanding the Exchange
There are a few key abstractions. The following subsections describe each.
### Exchange
The `Exchange` itself is the primary protocol. It defines a message exchange, such as a queue or topic, through which any number of related `ExchangeSender`, `ExchangeReceiver`, and `ExchangeAdapter` components are registered, and messages are sent. The protocol is defined as follows.
```java
public interface Exchange {
void close();
T channel();
T connection();
String name();
Exchange register(final Covey covey);
void send(final L local);
}
```
The defined behaviors are described next.
```java
void close();
```
Close the `Exchange` and any underlying resources. Given that the `Exchange` is backed by some middleware messaging mechanism, and connections and other allocated resources to the mechanism are closed.
```java
T channel();
```
Answers the underlying channel, which is implementation dependent. The `T` type is a parameter that determines the dynamic cast to the runtime type.
```java
T connection();
```
Answers the underlying connection, which is implementation dependent. The `T` type is a parameter that determines the dynamic cast to the runtime type.
```java
String name();
```
Answers the name of this `Exchange` as a `String`.
```java
Exchange register(final Covey covey);
```
Registers a `Covey` with the `Exchange`. A `Covey` is a set of `Exchange` components used to send, receive, and translate messages. The `Covey` is explained in a below subsection.
```java
void send(final L local);
```
Sends the `local` message to the `Exchange` after first adapting it to an `Exchange`-compatible message. Any given message has three forms:
1. Local—The type used by the local system to represent the message sent or received
2. External—The type the message will have when it is received on the external service
3. Exchange—The type used to transport the message on the Exchange from sender to receiver(s). The Exchange type holds an instance of the External type.
#### ConnectionSettings
The `ConnectionSettings` is a configuration for making a connection to the underlying messaging mechanism, including information for the host, port, virtual host, and user.
```java
public class ConnectionSettings {
public final String hostName;
public final String password;
public final int port;
public final String username;
public final String virtualHost;
...
}
```
There are also a number of factory methods for creating the value state.
#### Covey
A covey by definition is a group or set. We use a `Covey` as a set of `Exchange` components used for translating, sending, and receiving messages. A given `Exchange` will have one `Covey` for each local message type, either as a sender or a receiver of that message type.
```java
public class Covey {
public ExchangeAdapter adapter;
public ExchangeReceiver receiver;
public ExchangeSender sender;
public final Class localClass;
public final Class externalClass;
public final Class exchangeClass;
...
}
```
The `adapter` is an `ExchangeAdapter` that is capable of adapting messages to their three forms, Local, External, and Exchange.
The `receiver` is an `ExchangeReceiver` of messages of local type, meaning that the `ExchangeAdapter` has already adapted the incoming message to the local type.
The `sender` is an `ExchangeSender` of messages of exchange type through the `Exchange`, meaning that the `ExchangeAdapter` has already adapted the local message to an outgoing type.
Each of the `Class` instances is the type of a message form: `localClass`, `externalClass`, `exchangeClass`.
### Queue
A `Queue` is just a specialized `Exchange`. It is expected that a `Queue` is not a fanout type but one that is point-to-point. Being point-to-point does not prevent the receiver end from enlisting multiple`Queue` competing consumers. The `Queue` protocol is identical to the `Exchange`.
### ExchangeSender
A sender of messages to an `Exchange` or `Queue`.
```java
public interface ExchangeSender {
void send(final E message);
}
```
The single protocol operation is as follows.
```java
void send(final E message);
```
Sends the `E` exchange typed message through the underlying exchange or queue, meaning that the `ExchangeAdapter` has already adapted the local message to an outgoing type.
From this it may be apparent that the `Exchange#send()` does not actually send the message. Instead it dispatches the local message through the `Forwarder` for translation to the exchange type, and then the `Forwarder` dispatches the message to the `ExchangeSender`.
#### Forwarder
The forwarder of all local and exchange messages, forwarding local messages through an `ExchangeSender` and exchange messages through the `ExchangeReceiver`. It is the `Forwarder` that holds the `Covey` instances in behalf of the `Exchange` or `Queue`, and thus manages translation from local to exchange types and from exchange to local types.
#### MessageParameters
A builder of message parameters and set of metadata attributes, any number of which are common to associate with messages as parameters. These are to be used as appropriate or ignored if unneeded. The chosen parameters are built using the fluent interface.
```java
public class MessageParameters {
public static enum DeliveryMode { Durable, Transient }
public static enum Priority { High, Normal, Medium, Low, P0, P1, P2, P3, P4, P5, P6, P7, P8, P9 }
private String applicationId;
private String contentEncoding;
private String contentType;
private String correlationId;
private String deliveryId;
private DeliveryMode deliveryMode;
private String exchangeName;
private Map headers;
private String messageId;
private String other1;
private String other2;
private String other3;
private Priority priority;
private String queueName;
private boolean redeliver;
private String replyTo;
private String returnAddress;
private List routing;
private long timestamp;
private long timeToLive;
private String tag;
private String typeCode;
private String typeName;
private String userId;
...
}
```
There are factory methods and builder methods, as well as public accessors for each parameter. Many of the metadata parameters are common to AMQP, but may also be useful for any type of messaging protocol.
### ExchangeReceiver
A receiver of messages from an `Exchange`, which may be implemented for each unique message type. The message type received has already been mapped and adapted from the exchange-typed message, and this is in the form of a local message.
```java
public interface ExchangeReceiver {
void receive(final L message);
}
```
The single protocol operation is as follows.
```java
void receive(final L message);
```
The implementor receives the delivered `L` local typed message from the `Exchange`. The message is of local type `L` having already been mapped and adapted from the exchange-typed message.
### ExchangeAdapter
Adapts local messages of type `L` to exchange messages of type `EX` that hold external type `E`. This may involve mapping, in which case the underlying implementation must arrange for an `ExchangeMapper` to be registered and used. Note that the L and E types may be different between `ExchangeAdapter` and `ExchangeMapper`.
```java
public interface ExchangeAdapter {
L fromExchange(final EX exchangeMessage);
EX toExchange(final L localMessage);
boolean supports(final Object exchangeMessage);
}
```
The parameters of `L`, `E`, and `EX` are the local form, the external form, and the exchange form types, respectively. The operations of this protocol work as follows.
```java
L fromExchange(final EX exchangeMessage);
```
Answers the `L` typed local message from the `exchangeMessage` of type `EX`.
```java
EX toExchange(final L localMessage);
```
Answers the `EX` typed exchange message from the `localMessage` of type `L`.
```java
boolean supports(final Object exchangeMessage);
```
Answers whether or not the adapter supports the `exchangeMessage`. This is used by the `Forwarder` to find the `Covey` used for the type of `exchangeMessage`.
#### ExchangeMapper
Supports mapping a local type message to external type, and a external type message to local type.
```java
public interface ExchangeMapper {
E localToExternal(final L local);
L externalToLocal(final E external);
}
```
The parameters of `L` and `E` are the local form type and the external form type, respectively. The mapper operations are used as follows.
```java
E localToExternal(final L local);
```
Answers the external typed message given the local typed message.
```java
L externalToLocal(final E external);
```
Answers the local typed message given the external typed message.
## Usage
This section demonstrates how to use the `Exchange`. It provides a very simple usage example based on the RabbitMQ implementation.
To use the RabbitMQ implementation you first get connection to an `Exchange`.
```java
final Exchange exchange =
ExchangeFactory.fanOutInstance(
settings(),
"test-fanout",
true);
```
This factory method is specific to the RabbitMQ implementation. The `settings()` is defined as:
```java
private ConnectionSettings settings() {
return ConnectionSettings.instance(
"localhost",
ConnectionSettings.UndefinedPort,
"/",
"guest",
"guest");
}
```
The connection is to RabbitMQ on `localhost` and uses the default port by passing the value of `UndefinedPort`, which is `-1`. The `virtualHost` is `"/"` and the `username` and `password` are both `"guest"`.
Now that the `Exchange` is open we can register a `Covey` to handle a given set of message types.
```java
exchange
.register(Covey.of(
new MessageSender(exchange.connection()),
new TextMessageReceiver(),
new TextExchangeAdapter(),
String.class,
String.class,
Message.class));
```
To keep the example simple, both the local and external message types are `String`. The exchange message type is `Message`, which is a specialized RabbitMQ type.
```java
package io.vlingo.lattice.exchange.rabbitmq;
import io.vlingo.lattice.exchange.MessageParameters;
public class Message {
public final MessageParameters messageParameters;
public final byte[] payload;
public Message(final byte[] payload, final MessageParameters messageParameters) {
this.payload = payload;
this.messageParameters = messageParameters;
}
public Message(final String payload, final MessageParameters messageParameters) {
this.payload = payload.getBytes();
this.messageParameters = messageParameters;
}
public String payloadAsText() {
return new String(payload);
}
}
```
The `Message` holds a `byte[] payload` and an instance of `MessageParameters` as metadata. The `Message` may be constructed using a `byte[]` or a `String`, which is converted to a `byte[]`, along with `MessageParameters`.
Now here is more specific detail on the `Covey` registration on the `Exchange`. The `MessageSender` is a predefined implementation of `ExchangeSender` specifically for RabbitMQ. You instantiate the `MessageSender` with the `Exchange`'s connection.
The `TextMessageReceiver` and `TextExchangeAdapter` are specifically for `String` messages. The `TextMessageReceiver` is implemented as follows.
```java
public class TextMessageReceiver implements ExchangeReceiver {
public TextMessageReceiver() { }
@Override
public void receive(final String message) {
...
}
}
```
Your `receive()` method will apply the message as appropriate for your service/application. The following is the `TextExchangeAdapter`.
```java
public class TextExchangeAdapter implements ExchangeAdapter