JarCastingvertx-cassandra
Talk to Cassandra asynchronously from vert.x and run your callbacks on the vert.x event loop.
Getting Started
Add a dependency to vertx-cassandra:
<dependency>
<groupId>com.englishtown.vertx</groupId>
<artifactId>vertx-cassandra</artifactId>
<version>3.2.0</version>
</dependency>
| vertx-cassandra | vert.x | cassandra |
|---|---|---|
| 3.6.0 | 3.5.0 | 3.11 |
| 3.4.0 | 3.3.0 | 3.7 |
| 3.2.0 | 3.2.0 | 3.0 |
| 3.1.0 | 3.1.0 | 2.1 |
| 3.0.0 | 3.0.0 | 2.1 |
Configuration
The main configuration is via the normal config.json file for a Vert.x module.
{
"cassandra": {
"seeds": [<seeds>],
"query": {
"consistency_level": <string>,
"serial_consistency_level": <string>,
"fetch_size": <int>,
},
"policies": {
"load_balancing": {
"name": "<lb_policy_name>",
},
"reconnection": {
"name": "<reconnect_policy_name>"
}
},
"pooling": {
"core_connections_per_host_local": <int>,
"core_connections_per_host_remote": <int>,
"heartbeat_interval_seconds": <int>,
"idle_timeout_seconds": <int>,
"max_queue_size": <int>,
"max_requests_per_connection_local": <int>,
"max_requests_per_connection_remote": <int>,
"max_connections_per_host_local": <int>,
"max_connections_per_host_remote": <int>,
"new_connection_threshold_local": <int>,
"new_connection_threshold_remote": <int>
},
"socket": {
"connect_timeout_millis": <int>,
"read_timeout_millis": <int>,
"keep_alive": <boolean>,
"reuse_address": <boolean>,
"receive_buffer_size": <int>,
"send_buffer_size": <int>,
"so_linger": <int>,
"tcp_no_delay": <boolean>
}
}
}
seeds- an array of string seed IP or host names. At least one seed must be provided.lb_policy_name- (optional) the load balancing policy name. The following values are accepted:- "DCAwareRoundRobinPolicy" - requires string field
local_dcand optional numeric fieldused_hosts_per_remote_dc - Any FQCN such of a class that implements
LoadBalancingPolicy
- "DCAwareRoundRobinPolicy" - requires string field
reconnect_policy_name- (optional) the reconnect policy name. The following values are accepted:- "constant"|"ConstantReconnectionPolicy" - creates a
ConstantReconnectionPolicypolicy. Expects additional numeric fielddelayin ms. - "exponential"|"ExponentialReconnectionPolicy" - creates an
ExponentialReconnectionPolicypolicy. Expects additional numeric fieldsbase_delayandmax_delayin ms.
- "constant"|"ConstantReconnectionPolicy" - creates a
Refer to the Cassandra Java driver documentation for a description of the remaining configuration options.
A sample config looks like:
{
"cassandra": {
"seeds": ["10.0.0.1", "10.0.0.2"],
"policies": {
"load_balancing": {
"name": "DCAwareRoundRobinPolicy",
"local_dc": "LOCAL1",
"used_hosts_per_remote_dc": 1
},
"reconnection": {
"name": "exponential",
"base_delay": 1000,
"max_delay": 10000
}
},
}
}
Overriding with Environment Variables
It is possible to override the seeds and policies section of the configuration using environment variables. The two environment variables are:
CASSANDRA_SEEDS="{ip}|{ip}|{ip}..."
CASSANDRA_LOCAL_DC="{Local DC Name}"
So an example would be:
CASSANDRA_SEEDS="10.0.0.3|10.0.0.4"
CASSANDRA_LOCAL_DC="REMOTE1"
The latter, the CASSANDRA_LOCAL_DC, if used will override the entire load balancing section of the configuration, setting it to DCAwareRoundRobinPolicy, with a used_hosts value of 0 and the local_dc set to whatever is placed in the environment variable.
So the examples given here are akin to having this in the config file:
"seeds": ["10.0.0.3", "10.0.0.4"],
"policies": {
"load_balancing": {
"name": "DCAwareRoundRobinPolicy",
"local_dc": "REMOTE1",
"used_hosts_per_remote_dc": 0
}
}
Defaults
If there is no configuration, neither JSON nor environment variables, the module will default to looking for cassandra at 127.0.0.1 with the Cassandra driver defaults for everything.
How to Use
This module uses HK2 or Guice to provide an implementation of CassandraSession via injection. CassandraSession provides methods that allow statements to be executed, statements to be prepared and for the reading of metadata.
The execution and preparation methods have both synchronous and asynchronous variants. The asynchronous versions take a FutureCallBack class that is updated once the method has finished.
FutureCallback is part of Guava and the JAR is included as part of the Datastax java driver used by this module.
The general best practice is to inject one CassandraSession per verticle.
Promises Variant
There is a promises variant of CassandraSession, which is used by injecting WhenCassandraSession instead. This provides all of the same functionality, but instead of callbacks this class returns promises.
The promises used are from the Englishtown when.java package, which can be found on Github.
If you intend to use this implementation, you must include the when.java dependency in your application as it is not provided by this module.
