Elassandra is based on a fork of Elasticsearch acting as a plugin for Apache Cassandra :
- The ElassandraDaemon class override the CassandraDaemon class in order to manage Elasticsearch internal services.
- The ElasticSecondaryIndex class implements the Cassandra Index interface to write in Elasticsearch indices.
To achieve these operations, both Cassandra and Elasticsearch requires some modifications located in two forks:
A fork of Apache Cassandra including slight modifications, see (https://github.com/strapdata/cassandra).
A fork of Elasticsearch 5.5.0 (aka Strapdata-Elasticsearch, branch ${version}-strapdata) including modifications in :
- Cluster state management (org.elassandra.cluster.InternalCassandraClusterService override a modified org.elasticsearch.cluster.service.InternalClusterService)
- Gateway to retrieve Elasticsearch metadata on startup (see org.elassandra.gateway)
- Discovery to manage alive cluster members (see org.elassandra.discovery.CassandraDiscovery)
- Fields mappers to manage CQL mapping and Lucene field factory (see org.elasticsearch.index.mapper.core)
- Search requests routing (see org.elassandra.cluster.routing)
As shown below, forked Cassandra and Elasticsearch projects can change independently and changes can be rebased periodically into Strapdata-Cassandra or Elassandra (aka Strapdata-Elasticsearch).
Elassandra contains 2 references to the strapdata-cassandra :
- The Elassandra version 5+ core/pom.xml include a maven dependency on the strapdata-cassandra project
- The Elassandra version 6+ buildSrc/version.properties include a gradle dependency on the strapdata-cassandra project.
- In order to build the elassandra tarball and packages, the elassandra project includes a reference to the strapdata-cassandra as git submodule located in core/cassandra for version 5+ or server/cassandra for version 6+.
Elassandra is an opensource project, contributors are welcome to rise issues or pull requests on both strapdata-cassandra or elassandra github repositories.
When submitting an issue, please make sure that :
- You are testing against the latest version of Elassandra.
- You're not in the case of a known Elassandra limitation, see http://doc.elassandra.io/en/latest/limitations.html.
- Elassandra behavior is abnormally different from the standard Cassandra or Elasticsearch. For example, like Elasticsearch, Elassandra does not display default mappings unless requested, but this is the expected behavior.
It is very helpful if you can provide a test case to reproduce the bug and the associated error logs or stacktrace. See your conf/logback.xml to increase logging level in the logs/system.log file, and run nodetool setlogginglevel to dynamically update your logging level.
Your're welcome to rise an issue on https://github.com/strapdata/elassandra for new feature, describing why and how it should work.
Contributors can clone repositories and follow guidelines from Elasticsearch and Cassandra :
When cloning Elassandra, use git clone --recurse-submodules https://github.com/strapdata/elassandra to clone the strapdata-cassandra submodule and check that your are using the same strapdata-cassandra version in core/pom.xm for elassandra v5.x (or buildSrc/version.properties for v6.x) and in this submodule. Alternatively, this submodule can point to your own cassandra branch, assuming this branch include mandatory modifications to support Elassandra, see strapdata-cassandra for details.
If you forgot the --recurse-submodules when cloning, you can also fetch the cassandra submodule with git submodule update --init and git checkout cassandra-3.x-strapdata to set the strapdata branch.
Then, to build from sources:
-
Elassandra v5.x:
gradle clean assemble -Dbuild.snapshot=false -
Elassandra v6.x:
export JAVA_HOME=/path/to/jdk-10 export CASSANDRA_JAVA_HOME=/path/to/jdk-8 ./gradlew clean assemble -Dbuild.snapshot=false
Note: For elassandra v6.X, javadoc task failed due to https://bugs.java.com/bugdatabase/view_bug.do?bug_id=8194281.
Elassandra documentation is based on sphinx and published on readthedoc.org. Source RestructuredText files are located at Elassandra source documentation. To build the documentation, just run make html from the ${project.dir}/docs/elassandra.
- Test you changes
You can build Elassandra single-node unit tests mixing Elasticsearch and Cassandra CQL/nodetool requests. See Elassandra Testing documentation and existing Elassandra unit tests. For multi-nodes testing, you can use ecm, a fork of ccm running Elassandra.
- Rebase your changes
Like with Elasticsearch, update your local repository with the most recent code from the main Elassandra repository, and rebase your branch on top of the latest master branch. We prefer your initial changes to be squashed into a single commit. Later, if we ask you to make changes, add them as separate commits. This makes them easier to review. As a final step before merging we will either ask you to squash all commits yourself or we'll do it for you.
- Submit a pull request
Finally, push your local changes to your forked copy of the elassandra repository and submit a pull request. In the pull request, choose a title which sums up the changes that you have made, including the issue number (ex: #91 null_value support), and provide details about your changes.
As usual, you should never force push to a publicly shared branch, but add incremental commits.