Embedded Cassandra

https://nosan.github.io/embedded-cassandra
Admin
Embedded Cassandra is a Java library that provides an easy way to start and stop Apache Cassandra...
Tokens:3,835
Snippets:72
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Define CQL Schema

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Example CQL script for creating a keyspace.

```sql
CREATE KEYSPACE test WITH REPLICATION = { 'class' : 'SimpleStrategy', 'replication_factor' : 1 };
```

--------------------------------

### Start Shared Cassandra in JUnit Tests

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Invoke the start method within a @BeforeAll lifecycle hook to initialize the shared instance.

```java
@BeforeAll
public static void startCassandra() {
    SharedCassandra.start();
}
```

--------------------------------

### Start and Stop Cassandra Instance

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Programmatically manage the lifecycle of a Cassandra instance and execute CQL scripts.

```java
Cassandra cassandra = new CassandraBuilder().build();
cassandra.start();
try {
    Settings settings = cassandra.getSettings();
    try (CqlSession session = CqlSession.builder()
            .addContactPoint(new InetSocketAddress(settings.getAddress(), settings.getPort()))
            .withLocalDatacenter("datacenter1")
            .build()) {
        CqlScript.ofClassPath("schema.cql").forEachStatement(session::execute);
    }
}
finally {
    cassandra.stop();
}
```

--------------------------------

### Add Working Directory Resource

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Add additional files, such as configuration properties or certificates, to the working directory. The example shows adding 'cassandra-rackdc.properties' from the classpath.

```java
new CassandraBuilder()
        .addWorkingDirectoryResource(new ClassPathResource("cassandra-rackdc.properties"),
                "conf/cassandra-rackdc.properties");
```

--------------------------------

### Customize Cassandra Working Directory

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Implement a customizer to modify the working directory before Cassandra starts. This allows for adding specific files or configurations.

```java
new CassandraBuilder()
        .addWorkingDirectoryCustomizers(new WorkingDirectoryCustomizer() {

            @Override
            public void customize(Path workingDirectory, Version version) throws IOException {
                //Custom logic
            }
        }).build();
```

--------------------------------

### Set Startup System Properties

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Pass system properties to the Cassandra process. The -D prefix is added automatically.

```java
new CassandraBuilder()
        .addSystemProperty("cassandra.native_transport_port", 9042)
        .addSystemProperty("cassandra.jmx.local.port", 7199)
        .build();
```

--------------------------------

### Configure Working Directory

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Set the directory used as $CASSANDRA_HOME. Defaults to a temporary directory.

```java
new CassandraBuilder()
        .workingDirectory(() -> Files.createTempDirectory("apache-cassandra-"))
        .build();
```

--------------------------------

### Initialize Working Directory with Skip Existing Strategy

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Configure the working directory initializer to use a specific copy strategy, such as skipping existing files, to avoid overwriting them.

```java
new CassandraBuilder()
        .workingDirectoryInitializer(new DefaultWorkingDirectoryInitializer(new WebCassandraDirectoryProvider(),
                DefaultWorkingDirectoryInitializer.CopyStrategy.SKIP_EXISTING))
        .build();
```

--------------------------------

### Configure Authentication and Authorization

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Set up authentication and authorization for Cassandra using `PasswordAuthenticator` and `CassandraAuthorizer`. The `cassandra.superuser_setup_delay_ms` system property is set to 0 to create a superuser immediately.

```java
new CassandraBuilder()
        .addConfigProperty("authenticator", "PasswordAuthenticator")
        .addConfigProperty("authorizer", "CassandraAuthorizer")
        .addSystemProperty("cassandra.superuser_setup_delay_ms", 0) __**(1)**
        .build();
```

--------------------------------

### Initialize Cassandra Working Directory

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Define a strategy for initializing the working directory, ensuring all necessary Cassandra files are present after the init method is invoked.

```java
new CassandraBuilder()
        .workingDirectoryInitializer(new WorkingDirectoryInitializer() {

            @Override
            public void init(Path workingDirectory, Version version) throws IOException {
                //Custom logic
            }
        })
        .build();
```

--------------------------------

### Set Configuration File

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Provide a custom configuration file path.

```java
new CassandraBuilder()
        .configFile(new ClassPathResource("cassandra.yaml"))
        .build();
```

--------------------------------

### Load CQL Statements from Resources

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Execute CQL statements by loading them from file system resources using `CqlScript.ofResource` or `CqlDataSet.ofResources` for multiple files.

```java
CqlScript.ofResource(new FileSystemResource(new File("schema.cql"))).forEachStatement(session::execute);

CqlDataSet.ofResources(new FileSystemResource(new File("schema.cql")),
        new FileSystemResource(new File("V1__table.cql"))).forEachStatement(session::execute);
```

--------------------------------

### Build Embedded Cassandra from Source

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Use the Maven Wrapper to build the project. Requires JDK 11.

```bash
$ ./mvnw clean verify
```

--------------------------------

### Configure Client SSL Encryption

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Enable client SSL communication by configuring client encryption options, including keystore and truststore paths and passwords. Requires `server.keystore` and `server.truststore` resources.

```java
ClassPathResource keystore = new ClassPathResource("server.keystore");
ClassPathResource truststore = new ClassPathResource("server.truststore");
new CassandraBuilder()
        .addWorkingDirectoryResource(keystore, "conf/server.keystore")
        .addWorkingDirectoryResource(truststore, "conf/server.truststore")
        .addConfigProperty("client_encryption_options.enabled", true)
        .addConfigProperty("client_encryption_options.require_client_auth", true)
        .addConfigProperty("client_encryption_options.optional", false)
        .addConfigProperty("client_encryption_options.keystore", "conf/server.keystore")
        .addConfigProperty("client_encryption_options.truststore", "conf/server.truststore")
        .addConfigProperty("client_encryption_options.keystore_password", "123456")
        .addConfigProperty("client_encryption_options.truststore_password", "123456")
        // Use a dedicated SSL port if necessary
        .addConfigProperty("native_transport_port_ssl", 9142)
        .build();
```

--------------------------------

### Define JVM Options

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Pass custom JVM arguments to the Cassandra process.

```java
new CassandraBuilder()
        .addJvmOptions("-Xmx512m")
        .build();
```

--------------------------------

### Load CQL Statements from Classpath

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Execute CQL statements by loading them from the classpath using `CqlScript.ofClassPath` or `CqlDataSet.ofClassPaths` for multiple files.

```java
CqlScript.ofClassPath("schema.cql").forEachStatement(session::execute);

CqlDataSet.ofClassPaths("schema.cql", "V1__table.cql", "V2__table.cql").forEachStatement(session::execute);
```

--------------------------------

### Configure Cassandra Version

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Specify the Cassandra version to use. Defaults to 5.0.6.

```java
new CassandraBuilder()
        .version("5.0.0")
        .build();
```

--------------------------------

### Configure Simple Seed Provider

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Configure the `SimpleSeedProvider` to specify seed nodes for cluster discovery. Supports adding seeds by hostname and port, with port 0 indicating automatic allocation or use of `storage_port` for Cassandra 4.x.x.

```java
new CassandraBuilder()
        .configure(new SimpleSeedProviderConfigurator()
                .addSeeds("localhost", "127.0.0.1")
                //for Cassandra >= 4.x.x
                .addSeed("localhost", 7199)
                .addSeed("localhost", 0)) __**(1)**
        .build();
```

--------------------------------

### Set Environment Variables

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Define environment variables for the Cassandra process.

```java
new CassandraBuilder()
        .addEnvironmentVariable("JAVA_HOME", System.getProperty("java.home"))
        .build();
```

--------------------------------

### Add Libraries to Cassandra Classpath

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Include custom libraries in Cassandra's classpath by adding them as working directory resources using `ClassPathResource`.

```java
new CassandraBuilder()
        .addWorkingDirectoryResource(new ClassPathResource("lib.jar"), "lib/lib.jar")
        .build();
```

--------------------------------

### Set Cassandra Startup Timeout

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Configure the duration Embedded Cassandra will wait for the instance to be ready to accept connections. The default is 2 minutes.

```java
new CassandraBuilder()
        .startupTimeout(Duration.ofMinutes(1))
        .build();
```

--------------------------------

### Configure Cassandra Logger

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Specify a logger instance to consume Cassandra's STDOUT and STDERR outputs. Defaults to LoggerFactory.getLogger(Cassandra.class).

```java
new CassandraBuilder()
        .logger(LoggerFactory.getLogger("Cassandra"))
        .build();
```

--------------------------------

### Preserve Cassandra Working Directory

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Configure the working directory destroyer to do nothing, effectively preserving the working directory after the Cassandra instance is stopped.

```java
new CassandraBuilder()
        .workingDirectoryDestroyer(WorkingDirectoryDestroyer.doNothing())
        .build();
```

--------------------------------

### Implement a Shared Cassandra Instance

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Use this class to maintain a single Cassandra instance across multiple test classes. Register a shutdown hook to ensure the instance stops automatically after tests complete.

```java
public final class SharedCassandra {

    private static final Cassandra CASSANDRA = new CassandraBuilder()
            //          ... additional configuration
            .registerShutdownHook(true) __**(1)**
            .build();

    private SharedCassandra() {
    }

    public static synchronized void start() {
        CASSANDRA.start();
    }

    public static synchronized void stop() {
        CASSANDRA.stop();
    }

    public static synchronized boolean isRunning() {
        return CASSANDRA.isRunning();
    }

    public static synchronized Settings getSettings() {
        return CASSANDRA.getSettings();
    }

}
```

--------------------------------

### Handle JDK21 Security Manager Deprecation

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Configure the CassandraBuilder with a system property to allow the security manager when running on JDK21.

```text
ERROR [main] 2024-02-27 20:08:26,984 CassandraDaemon.java:897 - Exception encountered during startup
java.lang.UnsupportedOperationException: The Security Manager is deprecated and will be removed in a future release
    at java.base/java.lang.System.setSecurityManager(System.java:429)
    at org.apache.cassandra.security.ThreadAwareSecurityManager.install(ThreadAwareSecurityManager.java:96)
    at org.apache.cassandra.service.CassandraDaemon.setup(CassandraDaemon.java:248)
    at org.apache.cassandra.service.CassandraDaemon.activate(CassandraDaemon.java:751)
    at org.apache.cassandra.service.CassandraDaemon.main(CassandraDaemon.java:875)
    at com.github.nosan.embedded.cassandra.DefaultCassandra.await(DefaultCassandra.java:261)
    at com.github.nosan.embedded.cassandra.DefaultCassandra.start(DefaultCassandra.java:97)
```

```java
new CassandraBuilder()
        .addSystemProperty("java.security.manager", "allow").build();
```

--------------------------------

### Destroy Cassandra Working Directory

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Implement a strategy for destroying the working directory. By default, the entire directory is deleted.

```java
new CassandraBuilder()
        .workingDirectoryDestroyer(new WorkingDirectoryDestroyer() {

            @Override
            public void destroy(Path workingDirectory, Version version) throws IOException {
                //Custom logic
            }
        })
        .build();
```

--------------------------------

### Add Maven Dependency

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Include the Embedded Cassandra library in your project's pom.xml.

```xml
<dependencies>
    <dependency>
        <groupId>com.github.nosan</groupId>
        <artifactId>embedded-cassandra</artifactId>
        <version>5.0.3</version>
    </dependency>
</dependencies>
```

--------------------------------

### Override Configuration Properties

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Merge specific properties into the cassandra.yaml configuration.

```yaml
...
storage_port: 7199
native_transport_port: 9042
client_encryption_options:
   enabled: false
   ...
```

```java
new CassandraBuilder()
        .addConfigProperty("native_transport_port", 9000)
        .addConfigProperty("storage_port", 7000)
        .addConfigProperty("client_encryption_options.enabled", true)
        .build();
```

```yaml
...
storage_port: 7000
native_transport_port: 9000
client_encryption_options:
  enabled: true
  ...
```

--------------------------------

### Configure Random Ports for Cassandra

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Allocate random ports for native transport, storage, and JMX by setting the respective system properties to 0. For Cassandra 4.x.x, `SimpleSeedProviderConfigurator` is used with a port of 0.

```java
new CassandraBuilder()
        .addSystemProperty("cassandra.native_transport_port", 0)
        .addSystemProperty("cassandra.storage_port", 0)
        .addSystemProperty("cassandra.jmx.local.port", 0)
        //for Cassandra 4.x.x
        .configure(new SimpleSeedProviderConfigurator("localhost:0"))
        .build();
```

--------------------------------

### Embedded Cassandra Compile Dependencies

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Required Maven dependencies for compiling projects using Embedded Cassandra.

```xml
<dependencies>
    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-compress</artifactId>
        <version>1.28.0</version>
    </dependency>
    <dependency>
        <groupId>org.yaml</groupId>
        <artifactId>snakeyaml</artifactId>
        <version>2.5</version>
    </dependency>
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.5.18</version>
    </dependency>
</dependencies>
```

--------------------------------

### Register Cassandra Shutdown Hook

Source: https://nosan.github.io/embedded-cassandra/5.0.3

Enable or disable the registration of a shutdown hook for the Embedded Cassandra instance. Defaults to true.

```java
new CassandraBuilder()
        .registerShutdownHook(true)
        .build();
```
Tokens:
Raw