[client] List databases return database summary infos.

[loserwang1024]

Purpose

Linked issue: close #2514

Brief change log

Tests

API and Format

Documentation

[wuchong]

@loserwang1024 I left some comments.

[wuchong]

Why make this change? The previous implementation was clearer and safer. The current one doesn’t properly handle the case where the znode does not exist, which can lead to runtime errors or undefined behavior.

[wuchong]

The current implementation still triggers N separate I/O operations—one for each database—which can significantly increase latency. To mitigate this, we can optimize by performing these requests asynchronously in the background.

Specifically, you can:

1. Introduce a new method in ZooKeeperClient:

   getStatsInBackground(Collection<String> paths)

   This method should wrap the existing handleRequestInBackground and use a newly defined ZkGetStatRequest type to fetch stats for multiple paths concurrently. Take getDataInBackground as an example.

2. Then, add a new high-level method:

   List<DatabaseSummary> listDatabaseSummaries(Collection<String> databaseNames)

   which calls getStatsInBackground to retrieve all necessary ZooKeeper stats in parallel and constructs the DatabaseSummary objects efficiently.

This approach reduces end-to-end latency by eliminating sequential I/O and leveraging concurrent background requests.

[wuchong]

Rename the method to listDatabaseSummaries() without any parameters. If user would like only returning database names, they can use listDatabases().

[loserwang1024]

With the ListDatabaseOption option, if we want to support additional capabilities later (such as paginated queries), there's no need to add a new method.

[wuchong]

For legacy clients, this new field will be missing, which typically causes the boolean to default to false. This creates a risk of backward incompatibility: the server might return the full summary instead of just the names, effectively changing the behavior for old clients.

While we could technically work around this by checking request.hasDatabaseNameOnly() && !request.isDatabaseNameOnly(), this logic is counter-intuitive and error-prone.

Suggestion: A better design would be to use bool include_summary instead of database_name_only. So, for legacy clients, the default value (false) and empty value (unset this field) are consistent and correctly imply 'do not include summary,' automatically preserving the existing behavior without requiring complex null-checks.

[wuchong]

I suggest making these fields non-nullable and using primitive types (long and int) instead of their boxed counterparts.

If users need database names, they should call listDatabases() directly—rather than fetching database summaries and then discarding them.

This approach makes the API clearer, more predictable, and deterministic in behavior.