Annotations

Using a few lines of code, activate and configure the VLINGO/PLATFORM components.

There's an API defacto standard that developers always deserve freedom of choice in terms of either crafting each part of their own code, or to accelerate the development steps by taking advantage of default configurations and shorthand elements. The VLINGO/PLATFORM aims to provide technical autonomy, no matter the strategy you choose, even allowing the combination of both.

Generally speaking, VLINGO/XOOM annotations fit well when you want more succinct code. From the application initialization to the persistence resources, we provide a brief description of each annotation.

Annotation

Description

@Xoom

Its main purpose is to instantiate and setup essential elements of a VLINGO/PLATFORM application

@ResourceHandlers

Maps and initializes REST resource classes along with its routes

@Persistence

Enables VLINGO/SYMBIO, allowing to set up database parameters, CQRS, and different storage types.

@Projections / @Projection

Determines Domain Events processed by each Projection Actors.

@StateAdapters /

@StateAdapter

Generates default State Adapter for an Entity State

For a practical understanding of annotations, the next section brings more practical details.

@Xoom

It's widely known that the starting point of any Java program is a static main() method. In addition, when creating of a VLINGO/PLATFORM application, we must instantiate World, and pass it to other classes that use it for actors operation. So, that's what the @Xoom annotation mainly provides.

  • An Initializer class with a static main() method, which is the hook for JVM in the application execution

  • Creation of World and Stage with the AddressFactory option, making the Stage instance accessible for classes that request Actor operations directly from it

Besides that, @Xoom takes care of reading the properties file with the Mailbox definition and starts a VLINGO/HTTP server. All of those tasks are achieved simply by annotating a basic class.

@Xoom(name="xoom-app-name")
public class AppInitializer {
}

The application name attribute is the minimal information for running application with @Xoom but there are also other attributes. Here's the full list.

Attribute

Type

Description

Required

name

String

Sets the application name.

Yes

blocking

Boolean

True or false for respectively synchronous or asynchronous actor messaging. The default value is false.

No

addressFactory

Annotation

Sets the AddressFactory type: BASIC, UUID, GRID; and IdentityGenerator type:RANDON, TIME_BASED, NAME_BASED

No

The next code snippet shows the @Xoom attributes with non-default values.

@Xoom(name = "app-name", blocking = true,
addressFactory = @AddressFactory(type = GRID, generator = RANDOM))
public class AppInitializer {
}

Often, application initialization tasks need to be refined by some handwritten code. In the case where this is needed when using the @Xoom annotation, an initializer class may implement the interface io.vlingo.xoom.XoomInitializationAware.

@Xoom(name = "app-name")
public class AppInitializer implements XoomInitializationAware {
@Override
public void onInit(final Stage stage) {
//Here, add some logic that depends on Stage
}
@Override
public Configuration configureServer(final Stage stage, final String[] args) {
//Define a custom server configuration
}
}

@ResourceHandlers

This is a @Xoom-related annotation for REST resources initialization. First, your custom resource class must extend io.vlingo.http.resource.ResourceHandler . This resource class should implement a constructor that takes a Stage instance parameter. The resource class must also implement a routes() method, through which

public class InsuranceResource extends ResourceHandler {
private final Stage stage;
public InsuranceResource (final Stage stage) {
this.stage = stage;
}
public Completes<ObjectResponse<Insurance>> retrieveInsurances() {
// retrieve Insurance instances
}
@Override
public Resource<?> routes() {
return resource("Insurances", get("/insurances").handle(this::retrieveInsurances));
}
}

To wire an instance of a InsuranceResource, annotate the initializer class providing the package containing the REST resource classes.

@Xoom(name = "app-name")
@ResourceHandlers(packages = {"io.vlingo.xoomapp.resources"})
public class AppInitializer {
}

Optionally you may decide to provide a number of resource classes instead of the package name.

@Xoom(name = "app-name")
@ResourceHandlers({InsuranceResource.class, OtherResource.class ...})
public class AppInitializer {
}

As described below, @ResourceHandlers supports two optional attributes, but only one must be set.

Attribute

Type

Description

Required

value

Class <? extends ResourceHandler> []

An array of ResourceHandler subclasses.

No

packages

String []

An array of Java package names that each contains some number of ResourceHandler subclasses.

No

@Persistence

Regarding persistence configuration, through the onInit method, you can choose to manually create the code for the application infrastructure, as in the Helloworld example.

Alternatively, adopt@Persistence for a more succinct way to set up the persistence. By using that annotation, VLINGO/XOOM supports auto-configuration of:

  • The selected Storage Type for the Domain Model;

  • When using CQRS, a State Store for the Query Model and the selected Storage Type for the Command Model;

  • Datasource connection, including schema/tables creation;

The example below shows how to enables persistence auto-configuration.

@Persistence(basePackage = "io.vlingo.xoom.annotation", storageType = STATE_STORE)
public class PersistenceSetup {
}

The next table describes @Persistence attributes:

Attribute

Type

Description

Required

basePackage

String

The project's base package

true

storageType

StorageType

The Storage Type for the Domain / Command model

true

cqrs

Boolean

Using CQRS, two separate stores will be provided for the Command Model and Query Model. The default value is false.

false

The database credentials and other configuration parameters can be informed in three ways:

  • vlingo-xoom.properties

  • Environment variables;

  • Combining both;

The supported properties and environment variables are listed below:

Property Name

Environment Variable

Description

Required

database

VLINGO_XOOM_DATABASE

Database Type*. If IN_MEMORY, other properties are not required.

true

database.name

VLINGO_XOOM_DATABASE_NAME

Schema name.

true

database.driver

VLINGO_XOOM_DATABASE_DRIVER

The qualified class name of JDBC Driver

true

database.url

VLINGO_XOOM_DATABASE_URL

Connection URL

true

database.username

VLINGO_XOOM_DATABASE_USERNAME

Database username

true

database.password

VLINGO_XOOM_DATABASE_PASSWORD

Password

false

database.originator

VLINGO_XOOM_DATABASE_ORIGINATOR

Id for the data origin

true

*Supported Database types: IN_MEMORY, POSTGRES, HSQLDB, MYSQL, YUGA_BYTE.

In case of CQRS, you can inform parameters of the Query Model Database just adding "query" before the word "database". For instance, the property database becomes query.database, the environment variable VLINGO_XOOM_DATABASE becomes VLINGO_XOOM_QUERY_DATABASE.

Here's an example of a database configuration in the vlingo-xoom.properties:

database=POSTGRES
database.name=XOOM_APP_CMD_MODEL
database.driver=org.postgresql.Driver
database.url=jdbc:postgresql://localhost/
database.username=admin
database.password=pwd
database.originator=CMD
query.database=HSQLDB
query.database.name=XOOM_APP_QUERY_MODEL
query.database.driver=org.hsqldb.jdbcDriver
query.database.url=jdbc:hsqldb:mem:
query.database.username=sa
query.database.password=pwd
query.database.originator=QUERY

The following annotations are children of @Persistence and can be only used along with it.

@Projections

When using CQRS, relate the ProjectionActors to its supported events.

@Persistence(...)
@Projections({
@Projection(actor = CustomerProjectionActor.class,
becauseOf = {EventTypes.CustomerRegistered,
EventTypes.CustomerNotified}),
@Projection(actor = ProductProjectionActor.class,
becauseOf = {EventTypes.ProductDelivered,
EventTypes.ProductSoldOut})
})
public class PersistenceSetup {
}

@Projections accepts only a list of @Projection with a pair of attributes:

Attribute

Type

Description

Required

actor

Class<? extends StateStoreProjectionActor>

AProjectionActor class

true

basePackage

Enum [ ]

An Array of supported Domain Events.

true