Make RocksDB instance responsible for closing associated ColumnFamilyHandle instances

[alucarded]

• Takes the burden off developer to close ColumnFamilyHandle instances before closing RocksDB instance
• The change is backward-compatible

---

Previously the pattern for working with Column Families was:

try (final ColumnFamilyOptions cfOpts = new ColumnFamilyOptions().optimizeUniversalStyleCompaction()) {

  // list of column family descriptors, first entry must always be default column family
  final List<ColumnFamilyDescriptor> cfDescriptors = Arrays.asList(
      new ColumnFamilyDescriptor(RocksDB.DEFAULT_COLUMN_FAMILY, cfOpts),
      new ColumnFamilyDescriptor("my-first-columnfamily".getBytes(), cfOpts)
  );

  // a list which will hold the handles for the column families once the db is opened
  final List<ColumnFamilyHandle> columnFamilyHandleList =
      new ArrayList<>();

  try (final DBOptions options = new DBOptions()
      .setCreateIfMissing(true)
      .setCreateMissingColumnFamilies(true);
       final RocksDB db = RocksDB.open(options,
           "path/to/do", cfDescriptors,
           columnFamilyHandleList)) {

    try {

      // do something

    } finally {

      // NOTE user must explicitly frees the column family handles before freeing the db
      for (final ColumnFamilyHandle columnFamilyHandle :
          columnFamilyHandleList) {
        columnFamilyHandle.close();
      }
    } // frees the column family options
  }
} // frees the db and the db options

With the changes in this PR, the Java user no longer has to worry about manually closing the Column Families, which allows them to write simpler symmetrical create/free oriented code like this:

try (final ColumnFamilyOptions cfOpts = new ColumnFamilyOptions().optimizeUniversalStyleCompaction()) {

  // list of column family descriptors, first entry must always be default column family
  final List<ColumnFamilyDescriptor> cfDescriptors = Arrays.asList(
      new ColumnFamilyDescriptor(RocksDB.DEFAULT_COLUMN_FAMILY, cfOpts),
      new ColumnFamilyDescriptor("my-first-columnfamily".getBytes(), cfOpts)
  );

  // a list which will hold the handles for the column families once the db is opened
  final List<ColumnFamilyHandle> columnFamilyHandleList =
      new ArrayList<>();

  try (final DBOptions options = new DBOptions()
      .setCreateIfMissing(true)
      .setCreateMissingColumnFamilies(true);
       final RocksDB db = RocksDB.open(options,
           "path/to/do", cfDescriptors,
           columnFamilyHandleList)) {   

        // do something

    } // frees the column family options, then frees the db and the db options
  }
}

NOTE: The changes in this PR are backwards API compatible, which means existing code using the original approach will also continue to function correctly.

[adamretter]

I wonder if we should also implement RocksDB#destroyColumnFamily - which would also close and remove the cf from the list?

I also wonder if we should leave a test for the original approach where you have to manually close the column families and mark it as deprecated, to show that for the time being that is still supported. When this PR is merged we should also likely update the Wiki page about RocksJava object memory management.

Also, perhaps on RocksDB#close we should consider calling ownedColumnFamilies.clear() when we have finishing closing the cfs.

[adamretter]

LGTM just some small changes required

[facebook-github-bot]

@jay-zhuang has imported this pull request. If you are a Facebook employee, you can view this diff on Phabricator.

[facebook-github-bot]

@alucarded has updated the pull request. You must reimport the pull request before landing.

[facebook-github-bot]

@jay-zhuang has imported this pull request. If you are a Facebook employee, you can view this diff on Phabricator.

[facebook-github-bot]

@jay-zhuang merged this pull request in 05fba96.