Module com.github.nosan.embedded.cassandra
Package com.github.nosan.embedded.cassandra

Class CassandraBuilder

  • public class CassandraBuilder
extends Object
    A builder that can be used to configure and create Cassandra.

    This class is not thread safe and should not be shared across different threads!

    Since:
    4.0.0
    Author:
    Dmytro Nosan
    See Also:
    build(), CassandraBuilderConfigurator

    • Field Detail

      • DEFAULT_VERSION

        public static final Version DEFAULT_VERSION
        Default Cassandra version.

    • Constructor Detail

    • Method Detail

      • name

        public CassandraBuilder name​(String name)
        Sets the Cassandra instance name.

        Defaults to "cassandra-0", "cassandra-1", and so on.

        Parameters:
        name - the Cassandra instance name
        Returns:
        this builder

      • getName

        public String getName()
        Gets the currently configured Cassandra instance name.
        Returns:
        the Cassandra instance name, or null if not configured

      • version

        public CassandraBuilder version​(String version)
        Sets the Cassandra version.

        Defaults to DEFAULT_VERSION.

        Parameters:
        version - the Cassandra version to set
        Returns:
        this builder

      • version

        public CassandraBuilder version​(Version version)
        Sets the Cassandra version.

        Defaults to DEFAULT_VERSION.

        Parameters:
        version - the Cassandra version to be set
        Returns:
        this builder instance

      • getVersion

        public Version getVersion()
        Gets the currently configured Cassandra version.

        Defaults to DEFAULT_VERSION if no version is explicitly set.

        Returns:
        the configured Cassandra version, never null

      • logger

        public CassandraBuilder logger​(org.slf4j.Logger logger)
        Sets the Cassandra logger. This logger will capture and consume Cassandra's stdout and stderr outputs.

        Defaults to LoggerFactory.getLogger(Cassandra.class).

        Parameters:
        logger - the logger to be used for Cassandra
        Returns:
        this builder instance

      • registerShutdownHook

        public CassandraBuilder registerShutdownHook​(boolean registerShutdownHook)
        Specifies whether the created Cassandra instance should have a shutdown hook registered.

        Defaults to true.

        Parameters:
        registerShutdownHook - true to register a shutdown hook, false otherwise
        Returns:
        this builder instance

      • startupTimeout

        public CassandraBuilder startupTimeout​(Duration startupTimeout)
        Sets the startup timeout.

        Defaults to 2 minutes.

        Parameters:
        startupTimeout - the startup timeout
        Returns:
        this builder

      • configFile

        public CassandraBuilder configFile​(Resource configFile)
        Sets the Cassandra configuration file path.

        This is equivalent to: 

         
 addSystemProperty("cassandra.config", configFile);
        Parameters:
        configFile - the path to the Cassandra configuration file, must not be null
        Returns:
        this builder instance

      • workingDirectory

        public CassandraBuilder workingDirectory​(IOSupplier<? extends Path> workingDirectorySupplier)
        Sets the Supplier for the working directory, which will be invoked each time build() is called.

        The supplied directory will be initialized by WorkingDirectoryInitializer and used as the Cassandra home directory.

        At the end of the process, the provided working directory may be fully or partially deleted by WorkingDirectoryDestroyer.

        Defaults to Files.createTempDirectory("").

        Parameters:
        workingDirectorySupplier - the supplier providing the working directory, must not be null
        Returns:
        this builder instance
        See Also:
        IOSupplier.wrap(Supplier)

      • environmentVariables

        public CassandraBuilder environmentVariables​(Map<String,​?> environmentVariables)
        Sets the Cassandra environment variables. This operation will replace any previously configured environment variables.

        Example usage:

        
 Map<String, Object> environmentVariables = new LinkedHashMap<>();
 environmentVariables.put("TZ", "Europe/London");
 builder.environmentVariables(environmentVariables);
        Parameters:
        environmentVariables - a map containing the Cassandra environment variables, must not be null
        Returns:
        this builder instance for method chaining
        See Also:
        addEnvironmentVariable(String, Object), addEnvironmentVariables(Map)

      • addEnvironmentVariable

        public CassandraBuilder addEnvironmentVariable​(String name,
                                               Object value)
        Adds a Cassandra environment variable to the current configuration.

        Example usage:

        
 builder.addEnvironmentVariable("TZ", "Europe/London");
        Parameters:
        name - the name of the Cassandra environment variable, must not be null or empty
        value - the value of the Cassandra environment variable, must not be null
        Returns:
        this builder instance for method chaining
        See Also:
        addEnvironmentVariables(Map), environmentVariables(Map)

      • addEnvironmentVariables

        public CassandraBuilder addEnvironmentVariables​(Map<String,​?> environmentVariables)
        Adds multiple Cassandra environment variables to the current configuration.

        Example usage:

        
 Map<String, Object> environmentVariables = new LinkedHashMap<>();
 environmentVariables.put("TZ", "Europe/London");
 builder.addEnvironmentVariables(environmentVariables);
        Parameters:
        environmentVariables - a map containing Cassandra environment variables, must not be null or empty
        Returns:
        this builder instance for method chaining
        See Also:
        addEnvironmentVariable(String, Object), environmentVariables(Map)

      • systemProperties

        public CassandraBuilder systemProperties​(Map<String,​?> systemProperties)
        Sets the Cassandra native Java Virtual Machine (JVM) system properties. This action replaces any previously configured system properties.

        Example usage:

        
 Map<String, Object> systemProperties = new LinkedHashMap<>();
 systemProperties.put("cassandra.config", new ClassPathResource("cassandra.yaml"));
 systemProperties.put("cassandra.native_transport_port", 9042);
 systemProperties.put("cassandra.jmx.local.port", 7199);
 builder.systemProperties(systemProperties);
        Parameters:
        systemProperties - a map of Cassandra system properties, must not be null or empty
        Returns:
        this builder instance for method chaining
        See Also:
        addSystemProperty(String, Object)

      • addSystemProperty

        public CassandraBuilder addSystemProperty​(String name,
                                          Object value)
        Adds a single Cassandra native Java Virtual Machine (JVM) system property to the current configuration.

        Example usage:

        
 builder.addSystemProperty("cassandra.config", new ClassPathResource("cassandra.yaml"));
 builder.addSystemProperty("user.timezone", "Europe/London");
        Parameters:
        name - the name of the Cassandra system property, must not be null or empty
        value - the value of the Cassandra system property, must not be null
        Returns:
        this builder instance for method chaining
        See Also:
        addSystemProperties(Map)

      • addSystemProperties

        public CassandraBuilder addSystemProperties​(Map<String,​?> systemProperties)
        Adds multiple Cassandra native Java Virtual Machine (JVM) system properties to the current configuration. This method can be used to set or override existing system properties.

        Example usage:

        
 Map<String, Object> systemProperties = new LinkedHashMap<>();
 systemProperties.put("cassandra.config", new ClassPathResource("cassandra.yaml"));
 systemProperties.put("cassandra.native_transport_port", 9042);
 systemProperties.put("cassandra.jmx.local.port", 7199);
 builder.addSystemProperties(systemProperties);
        Parameters:
        systemProperties - a map of Cassandra system properties, must not be null or empty
        Returns:
        this builder instance for method chaining
        See Also:
        addSystemProperty(String, Object)

      • jvmOptions

        public CassandraBuilder jvmOptions​(Collection<String> jvmOptions)
        Sets the Cassandra native Java Virtual Machine (JVM) options. This method replaces any previously configured JVM options with the specified values.

        Example usage:

        
 builder.setJvmOptions(Arrays.asList("-Xmx1024m", "-Xms512m"));
        Parameters:
        jvmOptions - a collection of JVM options to set, must not be null or contain null elements
        Returns:
        this builder instance for method chaining
        See Also:
        jvmOptions(Collection), addJvmOptions(Collection), addJvmOptions(String...)

      • addJvmOptions

        public CassandraBuilder addJvmOptions​(String... jvmOptions)
        Adds Cassandra native Java Virtual Machine (JVM) options to the current configuration. This method appends the specified options to the existing list without replacing them.

        Example usage:

        
 builder.addJvmOptions("-Xmx1024m", "-Xms512m");
        Parameters:
        jvmOptions - the JVM options to add, must not be null or contain null elements
        Returns:
        this builder instance for method chaining
        See Also:
        addJvmOptions(Collection), jvmOptions(Collection), jvmOptions(String...)

      • addJvmOptions

        public CassandraBuilder addJvmOptions​(Collection<String> jvmOptions)
        Adds the specified Cassandra native Java Virtual Machine (JVM) options to the existing configuration. This method appends the given options rather than replacing any previously configured ones.

        Example usage:

        
 builder.addJvmOptions(Arrays.asList("-Xmx2048m", "-Xms1024m"));
        Parameters:
        jvmOptions - a collection of JVM options to add; must not be null or contain null elements
        Returns:
        this builder instance for method chaining
        See Also:
        addJvmOptions(String...), jvmOptions(Collection), jvmOptions(String...)

      • configProperties

        public CassandraBuilder configProperties​(Map<String,​?> configProperties)
        Sets the Cassandra configuration properties to be merged with the properties defined in the `cassandra.yaml` file. Setting this value replaces any previously configured properties.

        For example:

        
 Map<String, Object> properties = new LinkedHashMap<>();
 properties.put("client_encryption_options.enabled", true);
 properties.put("cluster_name", "MyCluster");
 builder.configProperties(properties);
        This will produce the following YAML output: 
         ...
 cluster_name: "MyCluster"
 client_encryption_options:
    enabled: true
    ...
 ...

        Note that this method fully replaces any previously set configuration properties. To add or modify specific properties incrementally, use addConfigProperty(String, Object) or addConfigProperties(Map).

        Parameters:
        configProperties - the Cassandra configuration properties to set; must not be null
        Returns:
        this builder instance for method chaining
        See Also:
        addConfigProperty(String, Object), addConfigProperties(Map)

      • addConfigProperty

        public CassandraBuilder addConfigProperty​(String name,
                                          Object value)
        Sets a single Cassandra configuration property, which will be merged with properties defined in the `cassandra.yaml` file.

        For example:

        
 builder.configProperty("client_encryption_options.enabled", true)
        .configProperty("cluster_name", "MyCluster");

        This will produce the following YAML output:

         ...
 cluster_name: "MyCluster"
 client_encryption_options:
    enabled: true
    ...
 ...

        This method allows for fine-grained updates of individual configuration properties. If multiple updates are needed, consider using addConfigProperties(Map) for efficiency.

        Parameters:
        name - the name of the configuration property (e.g., native_transport_port, client_encryption_options.enabled); must not be null or empty
        value - the value of the configuration property
        Returns:
        this builder instance for method chaining
        See Also:
        addConfigProperties(Map), configProperties(Map)

      • addConfigProperties

        public CassandraBuilder addConfigProperties​(Map<String,​?> configProperties)
        Adds multiple Cassandra configuration properties to the current configuration, merging them with the properties defined in the `cassandra.yaml` file. This method allows for bulk updates of configuration settings.

        For example:

        
 Map<String, Object> properties = new LinkedHashMap<>();
 properties.put("client_encryption_options.enabled", true);
 properties.put("cluster_name", "MyCluster");
 builder.configProperties(properties);

        This will result in the following YAML structure:

         ...
 cluster_name: "MyCluster"
 client_encryption_options:
    enabled: true
    ...
 ...

        Note that this method replaces any previously configured properties with the provided ones. If granular updates are needed, consider using addConfigProperty(String, Object).

        Parameters:
        configProperties - a map of Cassandra configuration properties to add
        Returns:
        this builder instance for method chaining
        See Also:
        addConfigProperty(String, Object), configProperties(Map)

      • addWorkingDirectoryResource

        public CassandraBuilder addWorkingDirectoryResource​(Resource resource,
                                                    String path)
        Copies a resource to a specified target path within the working directory.

        This method is equivalent to the following:

        
 addWorkingDirectoryCustomizers(WorkingDirectoryCustomizer.addResource(resource, path));

        Use this method to place files like configuration files, such as conf/cassandra.yaml, into the appropriate location within the working directory.

        Parameters:
        path - the target path (file only) within the working directory (e.g., conf/cassandra.yaml); must not be null or empty
        resource - the resource to copy; must not be null
        Returns:
        this builder instance for method chaining
        See Also:
        WorkingDirectoryCustomizer.addResource(Resource, String)

      • configure

        public CassandraBuilder configure​(CassandraBuilderConfigurator configurator)
        Applies the specified configurator to customize this builder.

        This method provides a way to modify the builder using the logic defined in the given configurator. Configurators can encapsulate reusable configuration logic, making it easier to apply pre-defined settings to multiple builders.

        Parameters:
        configurator - the configurator to apply to this builder; must not be null
        Returns:
        this builder instance for method chaining
        See Also:
        for an example configurator