#882 Schema support for DatabaseMetaData.getProcedures

src/docs/asciidoc/release_notes.adoc

@@ -516,10 +516,14 @@ Firebird 6.0 introduces schemas, and Jaybird 7 provides support for schemas as d
 Changes include:
 
 * `DatabaseMetaData`
+** `getProcedures` now uses the `schemaPattern` to filter by schema, with the following caveats
+*** `schemaPattern` empty will return no rows on Firebird 6.0 and higher (all procedures are in a schema);
+use `null` or `"%"` to match all schemas
+*** `catalog` is (still) ignored if `useCatalogAsPackage` is `false`
 ** `getSchemas()` returns all defined schemas
 ** `getSchemas(String catalog, String schemaPattern)` returns all schemas matching the `LIKE` pattern `schemaPattern`, with the following caveats
 *** `catalog` non-empty will return no rows;
-we recommend to always use `null` for `catalog`.
+we recommend to always use `null` for `catalog`
 *** `schemaPattern` empty will return no rows (there are no schemas with an empty name);
 use `null` or `"%"` to match all schemas
 

src/main/org/firebirdsql/jdbc/FBDatabaseMetaData.java

@@ -8,7 +8,7 @@
  SPDX-FileCopyrightText: Copyright 2005 Michael Romankiewicz
  SPDX-FileCopyrightText: Copyright 2005 Steven Jardine
  SPDX-FileCopyrightText: Copyright 2007 Gabriel Reid
- SPDX-FileCopyrightText: Copyright 2011-2024 Mark Rotteveel
+ SPDX-FileCopyrightText: Copyright 2011-2025 Mark Rotteveel
  SPDX-License-Identifier: LGPL-2.1-or-later
 */
 package org.firebirdsql.jdbc;
@@ -1203,7 +1203,8 @@ public boolean dataDefinitionIgnoredInTransactions() throws SQLException {
     @Override
     public ResultSet getProcedures(String catalog, String schemaPattern, String procedureNamePattern)
             throws SQLException {
-        return GetProcedures.create(getDbMetadataMediator()).getProcedures(catalog, procedureNamePattern);
+        return GetProcedures.create(getDbMetadataMediator())
+                .getProcedures(catalog, schemaPattern, procedureNamePattern);
     }
 
     /**

src/main/org/firebirdsql/jdbc/metadata/GetProcedures.java

@@ -1,5 +1,5 @@
-// SPDX-FileCopyrightText: Copyright 2001-2024 Firebird development team and individual contributors
-// SPDX-FileCopyrightText: Copyright 2022-2024 Mark Rotteveel
+// SPDX-FileCopyrightText: Copyright 2001-2025 Firebird development team and individual contributors
+// SPDX-FileCopyrightText: Copyright 2022-2025 Mark Rotteveel
 // SPDX-License-Identifier: LGPL-2.1-or-later
 package org.firebirdsql.jdbc.metadata;
 
@@ -33,10 +33,12 @@ public abstract class GetProcedures extends AbstractMetadataMethod {
 
     private static final String PROCEDURES = "PROCEDURES";
     private static final String COLUMN_PROCEDURE_NAME = "RDB$PROCEDURE_NAME";
+    private static final String COLUMN_SCHEMA_NAME = "RDB$SCHEMA_NAME";
+    private static final String COLUMN_PACKAGE_NAME = "RDB$PACKAGE_NAME";
 
     private static final RowDescriptor ROW_DESCRIPTOR = DbMetadataMediator.newRowDescriptorBuilder(9)
             .at(0).simple(SQL_VARYING | 1, OBJECT_NAME_LENGTH, "PROCEDURE_CAT", PROCEDURES).addField()
-            .at(1).simple(SQL_VARYING | 1, OBJECT_NAME_LENGTH, "PROCEDURE_SCHEM", "ROCEDURES").addField()
+            .at(1).simple(SQL_VARYING | 1, OBJECT_NAME_LENGTH, "PROCEDURE_SCHEM", PROCEDURES).addField()
             .at(2).simple(SQL_VARYING, OBJECT_NAME_LENGTH, "PROCEDURE_NAME", PROCEDURES).addField()
             .at(3).simple(SQL_VARYING, 31, "FUTURE1", PROCEDURES).addField()
             .at(4).simple(SQL_VARYING, 31, "FUTURE2", PROCEDURES).addField()
@@ -55,34 +57,42 @@ private GetProcedures(DbMetadataMediator mediator) {
     /**
      * @see DatabaseMetaData#getProcedures(String, String, String)
      */
-    public final ResultSet getProcedures(String catalog, String procedureNamePattern) throws SQLException {
+    public final ResultSet getProcedures(String catalog, String schemaPattern, String procedureNamePattern)
+            throws SQLException {
         if ("".equals(procedureNamePattern)) {
             return createEmpty();
         }
 
-        MetadataQuery metadataQuery = createGetProceduresQuery(catalog, procedureNamePattern);
+        MetadataQuery metadataQuery = createGetProceduresQuery(catalog, schemaPattern, procedureNamePattern);
         return createMetaDataResultSet(metadataQuery);
     }
 
     @Override
     final RowValue createMetadataRow(ResultSet rs, RowValueBuilder valueBuilder) throws SQLException {
         String catalog = rs.getString("PROCEDURE_CAT");
+        String schema = rs.getString("PROCEDURE_SCHEM");
         String procedureName = rs.getString("PROCEDURE_NAME");
         return valueBuilder
                 .at(0).setString(catalog)
+                .at(1).setString(schema)
                 .at(2).setString(procedureName)
                 .at(6).setString(rs.getString("REMARKS"))
                 .at(7).setShort(rs.getShort("PROCEDURE_TYPE") == 0 ? procedureNoResult : procedureReturnsResult)
-                .at(8).setString(toSpecificName(catalog, procedureName))
+                .at(8).setString(toSpecificName(catalog, schema, procedureName))
                 .toRowValue(true);
     }
 
-    abstract MetadataQuery createGetProceduresQuery(String catalog, String procedureNamePattern);
+    abstract MetadataQuery createGetProceduresQuery(String catalog, String schemaPattern, String procedureNamePattern);
 
     public static GetProcedures create(DbMetadataMediator mediator) {
         FirebirdSupportInfo firebirdSupportInfo = mediator.getFirebirdSupportInfo();
         // NOTE: Indirection through static method prevents unnecessary classloading
-        if (firebirdSupportInfo.isVersionEqualOrAbove(3)) {
+        if (firebirdSupportInfo.isVersionEqualOrAbove(6)) {
+            if (mediator.isUseCatalogAsPackage()) {
+                return FB6CatalogAsPackage.createInstance(mediator);
+            }
+            return FB6.createInstance(mediator);
+        }else if (firebirdSupportInfo.isVersionEqualOrAbove(3)) {
             if (mediator.isUseCatalogAsPackage()) {
                 return FB3CatalogAsPackage.createInstance(mediator);
             }
@@ -98,6 +108,7 @@ private static final class FB2_5 extends GetProcedures {
         private static final String GET_PROCEDURES_FRAGMENT_2_5 = """
                 select
                   null as PROCEDURE_CAT,
+                  null as PROCEDURE_SCHEM,
                   RDB$PROCEDURE_NAME as PROCEDURE_NAME,
                   RDB$DESCRIPTION as REMARKS,
                   RDB$PROCEDURE_OUTPUTS as PROCEDURE_TYPE
@@ -114,7 +125,7 @@ private static GetProcedures createInstance(DbMetadataMediator mediator) {
         }
 
         @Override
-        MetadataQuery createGetProceduresQuery(String catalog, String procedureNamePattern) {
+        MetadataQuery createGetProceduresQuery(String catalog, String schemaPattern, String procedureNamePattern) {
             Clause procedureNameClause = new Clause(COLUMN_PROCEDURE_NAME, procedureNamePattern);
             String queryText = GET_PROCEDURES_FRAGMENT_2_5
                     + procedureNameClause.getCondition("\nwhere ", "")
@@ -128,6 +139,7 @@ private static final class FB3 extends GetProcedures {
         private static final String GET_PROCEDURES_FRAGMENT_3 = """
                 select
                   null as PROCEDURE_CAT,
+                  null as PROCEDURE_SCHEM,
                   trim(trailing from RDB$PROCEDURE_NAME) as PROCEDURE_NAME,
                   RDB$DESCRIPTION as REMARKS,
                   RDB$PROCEDURE_OUTPUTS as PROCEDURE_TYPE
@@ -146,7 +158,7 @@ private static GetProcedures createInstance(DbMetadataMediator mediator) {
         }
 
         @Override
-        MetadataQuery createGetProceduresQuery(String catalog, String procedureNamePattern) {
+        MetadataQuery createGetProceduresQuery(String catalog, String schemaPattern, String procedureNamePattern) {
             Clause procedureNameClause = new Clause(COLUMN_PROCEDURE_NAME, procedureNamePattern);
             String queryText = GET_PROCEDURES_FRAGMENT_3
                     + procedureNameClause.getCondition("\nand ", "")
@@ -160,12 +172,12 @@ private static final class FB3CatalogAsPackage extends GetProcedures {
         private static final String GET_PROCEDURES_FRAGMENT_3_W_PKG = """
                 select
                   coalesce(trim(trailing from RDB$PACKAGE_NAME), '') as PROCEDURE_CAT,
+                  null as PROCEDURE_SCHEM,
                   trim(trailing from RDB$PROCEDURE_NAME) as PROCEDURE_NAME,
                   RDB$DESCRIPTION as REMARKS,
                   RDB$PROCEDURE_OUTPUTS as PROCEDURE_TYPE
                 from RDB$PROCEDURES""";
 
-        // NOTE: Including RDB$PACKAGE_NAME so index can be used to sort
         private static final String GET_PROCEDURES_ORDER_BY_3_W_PKG =
                 "\norder by RDB$PACKAGE_NAME nulls first, RDB$PROCEDURE_NAME";
 
@@ -178,16 +190,16 @@ private static GetProcedures createInstance(DbMetadataMediator mediator) {
         }
 
         @Override
-        MetadataQuery createGetProceduresQuery(String catalog, String procedureNamePattern) {
+        MetadataQuery createGetProceduresQuery(String catalog, String schemaPattern, String procedureNamePattern) {
             var clauses = new ArrayList<Clause>(2);
             if (catalog != null) {
                 // To quote from the JDBC API: "" retrieves those without a catalog; null means that the catalog name
                 // should not be used to narrow the search
                 if (catalog.isEmpty()) {
-                    clauses.add(Clause.isNullClause("RDB$PACKAGE_NAME"));
+                    clauses.add(Clause.isNullClause(COLUMN_PACKAGE_NAME));
                 } else {
                     // Exact matches only
-                    clauses.add(Clause.equalsClause("RDB$PACKAGE_NAME", catalog));
+                    clauses.add(Clause.equalsClause(COLUMN_PACKAGE_NAME, catalog));
                 }
             }
             clauses.add(new Clause(COLUMN_PROCEDURE_NAME, procedureNamePattern));
@@ -201,4 +213,91 @@ MetadataQuery createGetProceduresQuery(String catalog, String procedureNamePatte
             return new MetadataQuery(sql, Clause.parameters(clauses));
         }
     }
+
+    private static final class FB6 extends GetProcedures {
+
+        private static final String GET_PROCEDURES_FRAGMENT_6 = """
+                select
+                  null as PROCEDURE_CAT,
+                  trim(trailing from RDB$SCHEMA_NAME) as PROCEDURE_SCHEM,
+                  trim(trailing from RDB$PROCEDURE_NAME) as PROCEDURE_NAME,
+                  RDB$DESCRIPTION as REMARKS,
+                  RDB$PROCEDURE_OUTPUTS as PROCEDURE_TYPE
+                from "SYSTEM".RDB$PROCEDURES
+                where RDB$PACKAGE_NAME is null""";
+
+        // NOTE: Including RDB$PACKAGE_NAME so index can be used to sort
+        private static final String GET_PROCEDURES_ORDER_BY_6 =
+                "\norder by RDB$SCHEMA_NAME, RDB$PACKAGE_NAME, RDB$PROCEDURE_NAME";
+
+        private FB6(DbMetadataMediator mediator) {
+            super(mediator);
+        }
+
+        private static GetProcedures createInstance(DbMetadataMediator mediator) {
+            return new FB6(mediator);
+        }
+
+        @Override
+        MetadataQuery createGetProceduresQuery(String catalog, String schemaPattern, String procedureNamePattern) {
+            var schemaNameClause = new Clause(COLUMN_SCHEMA_NAME, schemaPattern);
+            var procedureNameClause = new Clause(COLUMN_PROCEDURE_NAME, procedureNamePattern);
+            //@formatter:off
+            String queryText = GET_PROCEDURES_FRAGMENT_6
+                    + (Clause.anyCondition(schemaNameClause, procedureNameClause)
+                    ? "\nand " + Clause.conjunction(schemaNameClause, procedureNameClause)
+                    : "")
+                    + GET_PROCEDURES_ORDER_BY_6;
+            //@formatter:on
+            return new MetadataQuery(queryText, Clause.parameters(schemaNameClause, procedureNameClause));
+        }
+    }
+
+    private static final class FB6CatalogAsPackage extends GetProcedures {
+
+        private static final String GET_PROCEDURES_FRAGMENT_6_W_PKG = """
+                select
+                  coalesce(trim(trailing from RDB$PACKAGE_NAME), '') as PROCEDURE_CAT,
+                  trim(trailing from RDB$SCHEMA_NAME) as PROCEDURE_SCHEM,
+                  trim(trailing from RDB$PROCEDURE_NAME) as PROCEDURE_NAME,
+                  RDB$DESCRIPTION as REMARKS,
+                  RDB$PROCEDURE_OUTPUTS as PROCEDURE_TYPE
+                from "SYSTEM".RDB$PROCEDURES""";
+
+        private static final String GET_PROCEDURES_ORDER_BY_6_W_PKG =
+                "\norder by RDB$PACKAGE_NAME nulls first, RDB$SCHEMA_NAME, RDB$PROCEDURE_NAME";
+
+        private FB6CatalogAsPackage(DbMetadataMediator mediator) {
+            super(mediator);
+        }
+
+        private static GetProcedures createInstance(DbMetadataMediator mediator) {
+            return new FB6CatalogAsPackage(mediator);
+        }
+
+        @Override
+        MetadataQuery createGetProceduresQuery(String catalog, String schemaPattern, String procedureNamePattern) {
+            var clauses = new ArrayList<Clause>(3);
+            clauses.add(new Clause(COLUMN_SCHEMA_NAME, schemaPattern));
+            if (catalog != null) {
+                // To quote from the JDBC API: "" retrieves those without a catalog; null means that the catalog name
+                // should not be used to narrow the search
+                if (catalog.isEmpty()) {
+                    clauses.add(Clause.isNullClause(COLUMN_PACKAGE_NAME));
+                } else {
+                    // Exact matches only
+                    clauses.add(Clause.equalsClause(COLUMN_PACKAGE_NAME, catalog));
+                }
+            }
+            clauses.add(new Clause(COLUMN_PROCEDURE_NAME, procedureNamePattern));
+            //@formatter:off
+            String sql = GET_PROCEDURES_FRAGMENT_6_W_PKG
+                    + (Clause.anyCondition(clauses)
+                    ? "\nwhere " + Clause.conjunction(clauses)
+                    : "")
+                    + GET_PROCEDURES_ORDER_BY_6_W_PKG;
+            //@formatter:on
+            return new MetadataQuery(sql, Clause.parameters(clauses));
+        }
+    }
 }

src/main/org/firebirdsql/jdbc/metadata/NameHelper.java

@@ -1,44 +1,88 @@
-// SPDX-FileCopyrightText: Copyright 2023 Mark Rotteveel
+// SPDX-FileCopyrightText: Copyright 2023-2025 Mark Rotteveel
 // SPDX-License-Identifier: LGPL-2.1-or-later
 package org.firebirdsql.jdbc.metadata;
 
 import org.firebirdsql.jdbc.QuoteStrategy;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+import static org.firebirdsql.jaybird.util.StringUtils.isNullOrEmpty;
 
 /**
  * Helper methods for generating object names.
  *
  * @author Mark Rotteveel
  * @since 6
  */
+@NullMarked
 final class NameHelper {
 
     private NameHelper() {
         // no instances
     }
 
+    // TODO Remove once all metadata methods have been rewritten to support schemas
+    @Deprecated
+    static String toSpecificName(@Nullable String catalog, String routineName) {
+        return toSpecificName(catalog, null, routineName);
+    }
+
     /**
      * Generates a name for the {@code SPECIFIC_NAME} column of {@code getFunctions}, {@code getFunctionColumns},
      * {@code getProcedures} and {@code getProcedureColumns}.
+     * <p>
+     * The specific name is generated as follows:
+     * </p>
+     * <ul>
+     * <li>
+     *     <p>For Firebird versions <em>without</em> schema support</p>
+     *     <ul>
+     *         <li>for non-packaged routines, the {@code routineName}</li>
+     *         <li>for packaged routines, both {@code catalog} (package name) and {@code routineName} are transformed to
+     *         quoted identifiers and separated by {@code .} (period)</li>
+     *     </ul>
+     * </li>
+     * <li>
+     *     <p>For Firebird versions <em>with</em> schema support</p>
+     *     <ul>
+     *         <li>for non-packaged routines, both {@code schema} and {@code routineName} are transformed to
+     *         quoted identifiers and separated by {@code .} (period)</li>
+     *         <li>for packaged routines, {@code catalog} (package name), {@code schema} and {@code routineName} are
+     *         transformed to quoted identifiers and separated by {@code .} (period)</li>
+     *     </ul>
+     * </li>
+     * </ul>
      *
      * @param catalog
      *         generally {@code null}, or &mdash; when {@code useCatalogAsPackage = true} &mdash; an empty string (no
      *         package) or a package name
+     * @param schema
+     *         schema name, or {@code null} for Firebird versions without schema support, empty string is handled same
+     *         as {@code null}
      * @param routineName
      *         name of the routine (procedure or function)
-     * @return specific name: for non-packaged routines the {@code routineName}, of packaged routines, both
-     * {@code catalog} (package name) and {@code routineName} are transformed to quoted identifiers and separated by
-     * {@code .} (period)
+     * @return specific name
      */
-    static String toSpecificName(String catalog, String routineName) {
-        if (catalog == null || catalog.isEmpty()) {
+    static String toSpecificName(@Nullable String catalog, @Nullable String schema, String routineName) {
+        if (isNullOrEmpty(catalog) && isNullOrEmpty(schema)) {
             return routineName;
         }
         var quoteStrategy = QuoteStrategy.DIALECT_3;
-        // 5: 4 quotes + 1 separator
-        var sb = new StringBuilder(catalog.length() + routineName.length() + 5);
-        quoteStrategy.appendQuoted(catalog, sb).append('.');
+        // 8: 6 quotes + 2 separators
+        var sb = new StringBuilder(length(catalog) + length(schema) + routineName.length() + 8);
+        if (!isNullOrEmpty(schema)) {
+            quoteStrategy.appendQuoted(schema, sb).append('.');
+        }
+        // this order assumes the catalog actually represents the package name
+        if (!isNullOrEmpty(catalog)) {
+            quoteStrategy.appendQuoted(catalog, sb).append('.');
+        }
         quoteStrategy.appendQuoted(routineName, sb);
         return sb.toString();
     }
 
+    private static int length(@Nullable String value) {
+        return value != null ? value.length() : 0;
+    }
+
 }