CassandraHazelcastStore Extension (Cluster Storage)

The CassandraHazelcastStore extension allows using an Apache Cassandra Database as Cluster Storage.

Using an Apache Cassandra Database as Cluster Storage

To use an Apache Cassandra database as Cluster Storage, you need the following:

  • A single-node or multi-node Platform installation
  • The CassandraHazelcastStore extension
  • An Apache Cassandra database

Follow these installation step to use Cassandra as Cluster Storage:

  1. Follow the installation steps in the System Installation: FNZ Studio 2025 section of the System Installation guide.
  2. After stopping the Platform (all nodes), set up a Cassandra keyspace and configure the Platform to use it as Cluster Storage instead of a file system. To do so, install and configure the CassandraHazelcastStore extension (see extension properties).
  3. Start the Platform and the extension.

Cassandra Keyspace Set-up

Set up a Cassandra keyspace for the Platform. If the user defined in the extension configuration has the privileges to create tables, the tables are created automatically. It is sufficient to run the CREATE KEYSPACE statement, for example using CQL shell:

Copy 
cqlsh> CREATE KEYSPACE appway
         WITH REPLICATION = {'class' : 'SimpleStrategy', 'replication_factor': 2};

To create the tables manually, run the following statement:

Copy 
 $ cqlsh
   cqlsh> CREATE KEYSPACE appway
          WITH REPLICATION = {'class' : 'SimpleStrategy', 'replication_factor': 2};
   cqlsh> use appway;
   cqlsh:appway> CREATE TABLE processinstances                   ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE valuestores                        ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE valuestoretodataentities           ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE dataentities                       ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE piindexdefinitions                 ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE datahandles                        ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE businessobjects                    ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE recentlyusedlists                  ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE commits                            ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE deploymentprofiles                 ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE logstatementlists                  ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE breakpoints                        ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE webapimetricslists                 ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE licenselogentries                  ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE licenselogentrylists               ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE accesslicenses                     ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE users                              ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE groups                             ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE virtualgroups                      ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE projectmessages                    ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE projectfiles                       ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE clusterfiles                       ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE cryptokeys                         ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE cryptopasswords                    ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE datasourceinfos                    ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE mailconfigurations                 ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE workflowmessagequeues              ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE workflowmessages                   ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE discussionmessages                 ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE chatchunks                         ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE chatchunkindexentries              ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE chatunreadinfos                    ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE notificationmessages               ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE notificationinboxes                ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE notificationindexentries           ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE notificationtopics                 ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE startupfiles                       ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE processslas                        ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE dhsavepointlists                   ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE dhstates                           ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE dhdataentitytostates               ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE stories                            ( id ascii PRIMARY KEY, data blob);
                 CREATE TABLE trackedchanges                     ( id ascii PRIMARY KEY, data blob);

CassandraHazelcastStore Extension

The CassandraHazelcastStore extension implements a Hazelcast MapStore, using Cassandra as its backend. To install and configure it, follow the steps below:

  1. Put the file CassandraHazelcastStore.jar into every Data Home's extensions directory (<data-home>/extensions).
  2. Enable the extension to be initialized during system start-up. Edit the file <data-home>/extensions/configuration.xml and add the following property:
    Copy
    ...
     <Adapter name=" CassandraHazelcastStore " state="2" startup="2" priority="0"/>
    ...
  3. Configure the Cassandra cluster to use. Next to the JAR file, create a text file with the name CassandraHazelcastStore.jar.cfg containing the connection configuration.
    Copy
    com.nm.cluster.cassandra.seeds = <IP address(es) of Cassandra cluster>
    Use localhost to connect to a local Cassandra installation. Use one or more remote IP addresses if connecting to a remote Cassandra installation.

CassandraHazelcastStore Extension Properties

To display a list of the configuration properties for this extension, double-click on the extension name:

  • com.nm.cluster.cassandra.seeds — comma-separated list of seed nodes of the Cassandra cluster (see seeds in /etc/Cassandra/cassandra.yaml).
  • com.nm.cluster.cassandra.readTimeoutMillis — read operation timeout for the Cassandra driver (default value: 12s).
  • com.nm.cluster.cassandra.keyspace — keyspace to be used (default value: appway).
  • com.nm.cluster.cassandra.UseAuthentication — set to true if you want to connect to Cassandra using a username/password authentication; otherwise, set to false.
  • com.nm.cluster.cassandra.username — username to be used when connecting to the Cassandra cluster. This property is taken into account only if com.nm.cluster.cassandra.UseAuthentication is set to true.
  • com.nm.cluster.cassandra.password — password to be used when connecting to the Cassandra cluster. This property is taken into account only if com.nm.cluster.cassandra.UseAuthentication is set to true.
  • com.nm.cluster.cassandra.UseSSL — set to true to use SSL encryption between client(s) and server(s); otherwise, set to false.

Cassandra Identity Configuration

Access to the Cassandra cluster can require authentication. The CassandraHazelcastStore extension supports this feature and the credentials used by the extension to connect to the Cassandra cluster can be provided in two different ways:

  • Statically by setting the username and password in the configuration file of the extension. To provide user credentials to the Cassandra cluster, the administrator needs to set the following properties:
    • com.nm.cluster.cassandra.UseAuthentication — Set this property to true, so that the following properties are used.
    • com.nm.cluster.cassandra.username — Contains the username accepted by Cassandra.
    • com.nm.cluster.cassandra.password — Contains the password accepted by Cassandra.
  • Dynamically by setting an identity provider that is external to the extension to provide username and password when the extension starts. If your Cassandra cluster uses security policies where user passwords are changed frequently, using dynamic identity configuration is recommended. The only property that needs to be configured, apart from com.nm.cluster.cassandra.UseAuthentication is:
    • com.nm.cluster.cassandra.identityprovider — Contains the full name of the Java class implementing the IdentityProvider interface e.g. com.client.identityprovider.ClientIdentityProvider.

Creating an Identity Provider for the Extension

The definition of the IdentityProvider interface is provided to the client inside a JAR file, IdentityProvider-x.y.jar. Use this JAR file as a library in the project that is implementing the client identity provider. The identity provider can be implemented in two different ways:

  • As a simple Java project
  • As an extension

The IdentityProvider interface has only one method which needs to be implemented by developers, the signature of the method is: public Identity getIdentity().

The returned class Identity is a marker interface. The implementation of the method needs to return a class implementing Identity. For basic authentication, the only method supported so far is UsernamePasswordIdentity. UsernamePasswordIdentity is defined in the IdentityProvider-x.y.jar and is an immutable class where the two properties, username and password, can be set only by using the constructor. Below is an example of implementation of the interface:

Copy 
package com.client.identityprovider;

import com.nm.identityprovider.Identity;
import com.nm.identityprovider.IdentityProvider;
import com.nm.identityprovider.UsernamePasswordIdentity;

public class ClientIdentityProviderImpl implements IdentityProvider {

    @Override
    public Identity getIdentity() {

        // retrieve username and password
        String username = "cassandraUsername";
        String password = "cassandraPassword";

        return new UsernamePasswordIdentity(username, password);
    }

}

Deploying an Identity Provider

Follow these steps:

  1. Include IdentityProvider-x.y.jar in the classpath of the application server.
  2. (If the identity provider is a simple Java project) Include the JAR file of this project in the classpath as well.
  3. (If the identity provider has been implemented as an extension) The identity provider must startup before the CassandraHazelcastStore extension. To achieve this, set the priority of the identity provider in the extension configuration file to a lower value than the priority of the CassandraHazelcastStore extension.

Start-up Messages

Early during cluster start-up, the Platform connects to the specified Cassandra cluster. You should see messages such as these:

Copy 
2014-08-18 17:57:44,538 INFO  [localhost-startStop-1] com.nm.extensions.cassandrahazelcaststore.CassandraHazelcastStoreAdapter - Connecting to Cassandra cluster: [4] [/10.0.22.14, /10.0.22.13, /10.0.22.12, /10.0.22.11]
2014-08-18 17:57:45,077 INFO  [localhost-startStop-1] com.nm.extensions.cassandrahazelcaststore.CassandraHazelcastStoreAdapter - Connected to Cassandra cluster 'Appway Cluster' on [/10.0.22.14, /10.0.22.12, /10.0.22.13, /10.0.22.11].

You should also see messages specifying which Cassandra MapStore implementation is in use for a specific data type (e.g. Process Instances, Values Stores, etc.):

Copy 
2014-08-18 17:57:45,336 INFO  [localhost-startStop-1] com.nm.cluster.service.ClusterServiceUtils - New Hazelcast MapStore for 'processInstancesMap' configured: CassandraHazelcastStore:com.nm.extensions.cassandrahazelcaststore.CassandraProcessInstanceHzStore
2014-08-18 17:57:45,336 INFO  [localhost-startStop-1] com.nm.cluster.service.ClusterServiceUtils - New Hazelcast MapStore for 'valueStoresMap' configured: CassandraHazelcastStore:com.nm.extensions.cassandrahazelcaststore.CassandraValueStoreHzStore

Viewing Stored Data

Most of the data now resides in the Cassandra cluster. To look at it, you can use e.g. CQL shell:

Copy 
   $ cqlsh <any ip address of cassandra cluster>
   cqlsh> use appway;
   cqlsh> describe keyspace appway;
   cqlsh> select count(*) from businessobjects;
   cqlsh> select id from businessobjects;
   cqlsh> select id, data from businessobjects where id='xyz';

To view the plain text content, use an (online) HexDecoder.