#882 Schema support for FBTableStatisticsManager

Author: mrotteveel

devdoc/jdp/jdp-2025-06-schema-support.adoc

@@ -110,11 +110,16 @@ this fulfills the JDBC requirements that a `CallableStatement` is not sensitive
 ** The API of `StoredProcedureMetaData` (internal API) is changed to not report selectability, but to update the `FBProcedureCall` instance with selectability and other information, like identified schema and/or package.
 ** For qualified *and* unambiguous procedure reference, the selectability is cached *per connection*, for unqualified or ambiguous procedure reference, the lookup is performed on each `Connection.prepareCall`, to account for search path changes
 ** Support for packages was missing in the handling of callable statements, and is added, also for older versions
-* TODO: Define effects for management API
+* Effects for management API
 ** `StatisticsManager`
 *** `getTableStatistics` received an overload to also accept a list of schemas (`sts_schema`)
 ** `FBTableStatisticsManager`/`TableStatistics`
-*** TODO: API and internals need to be redesigned to account for schemas
+*** Internally `ObjectReference` is used for the table instead of a String
+*** The key of the map returned by `getTableStatistics()` is a qualified table reference (i.e. `{<table-name> | <quoted-schema>.<quoted-table-name>}`.
+For schemaless tables, the unquoted table name is used as the key for backwards compatibility when used against Firebird 5.0 and older.
+*** `TableStatistics` received two extra accessors:
+**** `schema()` with the schema, or empty string if schemaless (or not found)
+**** `tableReference()` with the qualified table reference (i.e. `[<quoted-schema>.]<quoted-table-name>` (contrary to the key of getTableStatistics, it's always quoted!))
 * TODO: Add information to Jaybird manual
 
 Note to self: use `// TODO Add schema support` in places that you identify need to get/improve schema support, while working on schema support elsewhere

src/docs/asciidoc/release_notes.adoc

@@ -565,6 +565,14 @@ we recommend to always use `null` for `catalog`
 *** `getTableStatistics(String[] tableNames)` was changed to accept varargs (`getTableStatistics(String... tableNames)`)
 *** Added overload `getTableStatistics(List<String> tableNames)` with same behaviour as `getTableStatistics(String... tableNames)`
 *** Added overload `getTableStatistics(List<String> schemas, List<String> tableNames)` -- if `schemas` is non-empty, on Firebird 6.0 and higher, it will restrict the search for tables to the specified schemas
+* `FBTableStatisticsManager` (experimental feature)
+** For schema-bound tables, the key of the map returned by `getTableStatistics()` is a fully qualified and quoted table reference (i.e. `<quoted-schema>.<quoted-table-name>`).
+For schemaless tables (Firebird 5.0 and older, or tables that were not found), the key is still the unquoted `<table-name>`.
+** The static method `toTableReference(String schema, String tableName)` can be used to create a table reference in the same format as the key of the map returned by `getTableStatistics()`.
+The `schema` can be `null` or empty string for schemaless tables (i.e. Firebird 5.0 or older)
+** The `TableStatistics` object received additional accessors:
+*** `schema()` with the schema, or empty string for schemaless (Firebird 5.0 or older) or if the table was not found
+*** `tableReference()` with the fully qualified and quoted table reference (i.e. `[<quoted-schema>.]<quoted-table-name>`)
 
 // TODO add major changes
 

src/main/org/firebirdsql/management/FBTableStatisticsManager.java

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: Copyright 2022-2024 Mark Rotteveel
+// SPDX-FileCopyrightText: Copyright 2022-2025 Mark Rotteveel
 // SPDX-License-Identifier: LGPL-2.1-or-later
 package org.firebirdsql.management;
 
@@ -7,8 +7,11 @@
 import org.firebirdsql.gds.ng.FbExceptionBuilder;
 import org.firebirdsql.gds.ng.InfoProcessor;
 import org.firebirdsql.gds.ng.InfoTruncatedException;
+import org.firebirdsql.jaybird.util.ObjectReference;
 import org.firebirdsql.jdbc.FirebirdConnection;
 import org.firebirdsql.util.Volatile;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import java.sql.Connection;
 import java.sql.DatabaseMetaData;
@@ -17,9 +20,11 @@
 import java.sql.SQLNonTransientException;
 import java.util.HashMap;
 import java.util.Map;
-import java.util.stream.Collectors;
+import java.util.function.Function;
 
+import static java.util.stream.Collectors.toMap;
 import static org.firebirdsql.gds.ISCConstants.*;
+import static org.firebirdsql.jaybird.util.StringUtils.isNullOrEmpty;
 
 /**
  * Provides access to the table statistics of a {@link java.sql.Connection}.
@@ -39,12 +44,13 @@
  * @since 5
  */
 @Volatile(reason = "Experimental")
+@NullMarked
 public final class FBTableStatisticsManager implements AutoCloseable {
 
     private static final int MAX_RETRIES = 3;
 
-    private Map<Integer, String> tableMapping = new HashMap<>();
-    private FirebirdConnection connection;
+    private Map<Integer, ObjectReference> tableMapping = new HashMap<>();
+    private @Nullable FirebirdConnection connection;
     /**
      * Table slack is a number which is used to pad the table count used for calculating the buffer size in an attempt
      * to prevent or fix truncation of the info request. It is incremented when a truncation is handled.
@@ -77,24 +83,31 @@ public static FBTableStatisticsManager of(Connection connection) throws SQLExcep
      * <p>
      * A table is only present in the map if this connection touched it in a way which generated a statistic.
      * </p>
+     * <p>
+     * The method {@link #toKey(String, String)} can be used to produce a key as used for entries in the map.
+     * </p>
      *
-     * @return map from table name to table statistics
+     * @return map from table reference ({@code <table-name>} for schemaless, or
+     * {@code <quoted-schema>.<quoted-table-name>} for schema-bound) to table statistics
      * @throws InfoTruncatedException
      *         if a truncated response is received, after retrying 3 times (total: 4 attempts) while increasing
      *         the buffer size; it is possible that subsequent calls to this method may recover (as that will increase
      *         the buffer size even more)
      * @throws SQLException
      *         if the connection is closed, or if obtaining the statistics failed due to a database access error
+     * @see #toKey(String, String)
      */
     public Map<String, TableStatistics> getTableStatistics() throws SQLException {
         checkClosed();
-        FbDatabase db = connection.getFbDatabase();
+        @SuppressWarnings("DataFlowIssue") FbDatabase db = connection.getFbDatabase();
         InfoTruncatedException lastTruncation;
-        TableStatisticsProcessor tableStatisticsProcessor = new TableStatisticsProcessor();
+        var tableStatisticsProcessor = new TableStatisticsProcessor();
         int attempt = 0;
         do {
             try {
-                return db.getDatabaseInfo(getInfoItems(), bufferSize(getTableCount()), tableStatisticsProcessor);
+                return db.getDatabaseInfo(getInfoItems(), bufferSize(getTableCount()), tableStatisticsProcessor)
+                        .values().stream()
+                        .collect(toMap(FBTableStatisticsManager::toKey, Function.identity()));
             } catch (InfoTruncatedException e) {
                 /* Occurrence of truncation should be rare. It could occur if all tables have all statistics items, and
                    new tables are added after the last updateMapping() call or statistics were previously requested by
@@ -109,6 +122,53 @@ Here, tableSlack is incremented to account for tables removed, while updateTable
         throw lastTruncation;
     }
 
+    /**
+     * Produces a key to the map returned by {@link #getTableStatistics()}.
+     *
+     * @param schema
+     *         schema, or {@code null} or empty string for schemaless
+     * @param tableName
+     *         table name
+     * @return key: {@code <table-name>} for schemaless, or {@code <quoted-schema>.<quoted-table-name>} for schema-bound
+     * @since 7
+     */
+    public static String toKey(@Nullable String schema, String tableName) {
+        return isNullOrEmpty(schema) ? tableName : toKey(ObjectReference.of(schema, tableName));
+    }
+
+    /**
+     * Produces a key to the map returned by {@link #getTableStatistics()}.
+     *
+     * @param tableStatistics
+     *         table statistics object
+     * @return key
+     * @see #toKey(String, String)
+     * @since 7
+     */
+    public static String toKey(TableStatistics tableStatistics) {
+        return toKey(tableStatistics.table());
+    }
+
+    /**
+     * Produces a key to the map returned by {@link #getTableStatistics()}.
+     * <p>
+     * The behaviour is undefined when called with an {@link ObjectReference} of more than two identifiers.
+     * </p>
+     *
+     * @param objectReference
+     *         table object reference
+     * @return key
+     * @see #toKey(String, String)
+     * @since 7
+     */
+    static String toKey(ObjectReference objectReference) {
+        if (objectReference.size() == 1) {
+            return objectReference.first().name();
+        }
+        // We assume object reference is size 2, but this will 'work' even if that assumption is wrong
+        return objectReference.toString();
+    }
+
     /**
      * @return the actual table count (so excluding {@link #tableSlack}).
      */
@@ -132,8 +192,7 @@ private int getTableCount() throws SQLException {
     @Override
     public void close() {
         connection = null;
-        tableMapping.clear();
-        tableMapping = null;
+        tableMapping = Map.of();
     }
 
     private void checkClosed() throws SQLException {
@@ -146,11 +205,12 @@ private void checkClosed() throws SQLException {
     }
 
     private void updateTableMapping() throws SQLException {
-        DatabaseMetaData md = connection.getMetaData();
+        @SuppressWarnings("DataFlowIssue") DatabaseMetaData md = connection.getMetaData();
         try (ResultSet rs = md.getTables(
                 null, null, "%", new String[] { "SYSTEM TABLE", "TABLE", "GLOBAL TEMPORARY" })) {
             while (rs.next()) {
-                tableMapping.put(rs.getInt("JB_RELATION_ID"), rs.getString("TABLE_NAME"));
+                tableMapping.put(rs.getInt("JB_RELATION_ID"),
+                        ObjectReference.of(rs.getString("TABLE_SCHEM"), rs.getString("TABLE_NAME")));
             }
         }
     }
@@ -186,17 +246,17 @@ private static byte[] getInfoItems() {
      * {@link #updateTableMapping()} from this processor.
      * </p>
      */
-    private final class TableStatisticsProcessor implements InfoProcessor<Map<String, TableStatistics>> {
+    private final class TableStatisticsProcessor implements InfoProcessor<Map<ObjectReference, TableStatistics>> {
 
-        private final Map<String, TableStatistics.TableStatisticsBuilder> statisticsBuilders = new HashMap<>();
+        private final Map<ObjectReference, TableStatistics.TableStatisticsBuilder> statisticsBuilders = new HashMap<>();
         private boolean allowTableMappingUpdate = true;
 
         @Override
-        public Map<String, TableStatistics> process(byte[] infoResponse) throws SQLException {
+        public Map<ObjectReference, TableStatistics> process(byte[] infoResponse) throws SQLException {
             try {
                 decodeResponse(infoResponse);
                 return statisticsBuilders.entrySet().stream()
-                        .collect(Collectors.toMap(Map.Entry::getKey, e -> e.getValue().toTableStatistics()));
+                        .collect(toMap(Map.Entry::getKey, e -> e.getValue().toTableStatistics()));
             } finally {
                 statisticsBuilders.clear();
             }
@@ -245,28 +305,27 @@ void processStatistics(int statistic, byte[] buffer, int start, int end) throws
             }
         }
 
-        private String getTableName(Integer tableId) throws SQLException {
-            String tableName = tableMapping.get(tableId);
-            if (tableName == null) {
+        private ObjectReference getTable(Integer tableId) throws SQLException {
+            ObjectReference table = tableMapping.get(tableId);
+            if (table == null) {
                 // mapping empty or out of date (e.g. new table created since the last update)
                 if (allowTableMappingUpdate) {
                     updateTableMapping();
                     // Ensure that if we have multiple tables missing, we don't repeatedly update the table mapping, as
                     // that wouldn't result in new information.
                     allowTableMappingUpdate = false;
-                    tableName = tableMapping.get(tableId);
+                    table = tableMapping.get(tableId);
                 }
-                if (tableName == null) {
+                if (table == null) {
                     // fallback
-                    tableName = "UNKNOWN_TABLE_ID_" + tableId;
+                    table = ObjectReference.of("UNKNOWN_TABLE_ID_" + tableId);
                 }
             }
-            return tableName;
+            return table;
         }
 
         private TableStatistics.TableStatisticsBuilder getBuilder(int tableId) throws SQLException {
-            String tableName = getTableName(tableId);
-            return statisticsBuilders.computeIfAbsent(tableName, TableStatistics::builder);
+            return statisticsBuilders.computeIfAbsent(getTable(tableId), TableStatistics::builder);
         }
     }
 }

src/main/org/firebirdsql/management/TableStatistics.java

@@ -1,10 +1,11 @@
-// SPDX-FileCopyrightText: Copyright 2022-2023 Mark Rotteveel
+// SPDX-FileCopyrightText: Copyright 2022-2025 Mark Rotteveel
 // SPDX-License-Identifier: LGPL-2.1-or-later
 package org.firebirdsql.management;
 
+import org.firebirdsql.jaybird.util.ObjectReference;
 import org.firebirdsql.util.Volatile;
+import org.jspecify.annotations.NullMarked;
 
-import static java.util.Objects.requireNonNull;
 import static org.firebirdsql.gds.ISCConstants.isc_info_backout_count;
 import static org.firebirdsql.gds.ISCConstants.isc_info_delete_count;
 import static org.firebirdsql.gds.ISCConstants.isc_info_expunge_count;
@@ -22,10 +23,11 @@
  * @since 5
  */
 @SuppressWarnings("unused")
+@NullMarked
 @Volatile(reason = "Experimental")
 public final class TableStatistics {
 
-    private final String tableName;
+    private final ObjectReference table;
     private final long readSeqCount;
     private final long readIdxCount;
     private final long insertCount;
@@ -35,9 +37,9 @@ public final class TableStatistics {
     private final long purgeCount;
     private final long expungeCount;
 
-    private TableStatistics(String tableName, long readSeqCount, long readIdxCount, long insertCount, long updateCount,
-            long deleteCount, long backoutCount, long purgeCount, long expungeCount) {
-        this.tableName = requireNonNull(tableName, "tableName");
+    private TableStatistics(ObjectReference table, long readSeqCount, long readIdxCount, long insertCount,
+            long updateCount, long deleteCount, long backoutCount, long purgeCount, long expungeCount) {
+        this.table = table;
         this.readSeqCount = readSeqCount;
         this.readIdxCount = readIdxCount;
         this.insertCount = insertCount;
@@ -49,10 +51,46 @@ private TableStatistics(String tableName, long readSeqCount, long readIdxCount,
     }
 
     /**
-     * @return table name
+     * @return table name (or {@code UNKNOWN_TABLE_ID_<table id>} if the table was not found)
+     * @see #tableReference()
      */
     public String tableName() {
-        return tableName;
+        return table.last().name();
+    }
+
+    /**
+     * @return schema of table (or empty string if schemaless or the table was not found)
+     * @see #tableReference()
+     * @since 7
+     */
+    public String schema() {
+        return table.size() == 2 ? table.first().name() : "";
+    }
+
+    /**
+     * The table reference.
+     * <p>
+     * Contrary to the key used for {@link FBTableStatisticsManager#getTableStatistics()}, the table name is always
+     * quoted, even for schemaless tables. If you want to derive a key for the table from an instance of this class, use
+     * {@link FBTableStatisticsManager#toKey(TableStatistics)}.
+     * </p>
+     *
+     * @return fully qualified and quoted table reference ({@code [<quoted-schema>.]<quoted-table-name>})
+     * @see #tableName()
+     * @see #schema()
+     * @see FBTableStatisticsManager#toKey(TableStatistics)
+     * @since 7
+     */
+    public String tableReference() {
+        return table.toString();
+    }
+
+    /**
+     * @return object reference of the table
+     * @since 7
+     */
+    ObjectReference table() {
+        return table;
     }
 
     /**
@@ -115,7 +153,7 @@ public long expungeCount() {
     @Override
     public String toString() {
         return "TableStatistics{" +
-                "tableName='" + tableName + '\'' +
+                "table='" + table + '\'' +
                 ", readSeqCount=" + readSeqCount +
                 ", readIdxCount=" + readIdxCount +
                 ", insertCount=" + insertCount +
@@ -127,13 +165,13 @@ public String toString() {
                 '}';
     }
 
-    static TableStatisticsBuilder builder(String tableName) {
-        return new TableStatisticsBuilder(tableName);
+    static TableStatisticsBuilder builder(ObjectReference table) {
+        return new TableStatisticsBuilder(table);
     }
 
     static final class TableStatisticsBuilder {
 
-        private final String tableName;
+        private final ObjectReference table;
         private long readSeqCount;
         private long readIdxCount;
         private long insertCount;
@@ -143,8 +181,9 @@ static final class TableStatisticsBuilder {
         private long purgeCount;
         private long expungeCount;
 
-        private TableStatisticsBuilder(String tableName) {
-            this.tableName = tableName;
+        private TableStatisticsBuilder(ObjectReference table) {
+            assert table.size() <= 2 : "table should be an object reference of at most two identifiers";
+            this.table = table;
         }
 
         void addStatistic(int statistic, long value) {
@@ -164,7 +203,7 @@ void addStatistic(int statistic, long value) {
         }
 
         TableStatistics toTableStatistics() {
-            return new TableStatistics(tableName, readSeqCount, readIdxCount, insertCount, updateCount, deleteCount,
+            return new TableStatistics(table, readSeqCount, readIdxCount, insertCount, updateCount, deleteCount,
                     backoutCount, purgeCount, expungeCount);
         }