Add comment explaining how Cassandra is used and why we can't do something

simpler with a single column or supercolumn family.

Author: Tom May

plugins/cassandra/src/main/java/org/elasticsearch/cassandra/blobstore/CassandraBlobStore.java

@@ -17,6 +17,47 @@
  * under the License.
  */
 
+/**
+ * The cassandra column families are defined in storage-conf.xml like
+ * this:
+ *    <!-- Key is BlobPath/BlobName.
+ *         Column name is "data".
+ *         Value is blob data. -->
+ *    <ColumnFamily Name="Blobs"/>
+ *                  />
+ *    <!-- Key is BlobPath.
+ *         Column names are BlobNames.
+ *         Value is size as a string. -->
+ *    <ColumnFamily Name="BlobNames"/>
+ *
+ * ElasticSearch needs us to support the following:
+ * 1. Read, write, and delete a blob named by BlobPath + BlobName.
+ * 2. Determine whether a Blob exists.  (Actually this method, blobExists,
+ *    is not referenced in the code.)
+ * 3. Get a list of BlobNames in a BlobPath, with their sizes.
+ * 4. Delete all blobs in a BlobPath.
+ *
+ * Here are a couple ways to store the data, and why they don't work:
+ * A. A single column family with BlobPath as the key and BlobName as the
+ *    column name.  1 and 4 are easy, but getting the sizes for 3 isn't
+ *    possible without fetching the entire blob.  Same with 2.
+ * B. A single supercolumn family with BlobPath as a key and BlobName as
+ *    the supercolumn name, with subcolumns data and size.  1, 2, and 4
+ *    are easy, but fetching the size for 3 requires fetching the entire
+ *    supercolumn, we can't just pick out the size column in a get_slice
+ *    request.
+ *
+ * The storage layout used allows us to do everything we need even though
+ * it's a bit more complicated than A and B because it has two column
+ * families.
+ * X. Storing the blob names and sizes in BlobNames makes 3 possible,
+ *    but complicates 1 since we need to track things in BlobNames.
+ * Y. Using BlobPath/BlobName as the key and storing the data in a column
+ *    makes 2 possible using get_count.
+ * Z. But it complicates 4, which must be done by fetching the BlobPath's
+ *    BlobNames then deleting them.
+ */
+
 package org.elasticsearch.cassandra.blobstore;
 
 import org.elasticsearch.common.blobstore.BlobContainer;