#882 Add JB_PROCEDURE_SOURCE column to getProcedures

Remove previously added getProcedureSourceCode(String, String) and deprecate getProcedureSourceCode(String) in favour of getProcedures

Author: mrotteveel

src/docs/asciidoc/release_notes.adoc

@@ -532,8 +532,24 @@ Within the limitations and specification of the JDBC API, this method cannot be
 ** `getColumnPrivileges` and `getTablePrivileges` received an additional column, `JB_GRANTEE_SCHEMA`, which is non-``null`` for grantees that are schema-bound (e.g. procedures).
 +
 As this is a non-standard column, we recommend to always retrieve it by name.
-** `getProcedureSourceCode`/`getTriggerSourceCode`/`getViewSourceCode` now also have an overload accepting the schema;
-the overloads without a `schema` parameter, or `schema` is `null` will return the source code of the first match found.
+** `getProcedures` received two additional columns.
++
+As these are non-standard columns, we recommend to always retrieve them by name.
++
+*** `JB_PROCEDURE_TYPE` -- value of column `RDB$PROCEDURE_TYPE`
++
+For the possible values, the following constants were added to `FirebirdDatabaseMetaData`:
++
+**** `jbProcedureTypeUnknown` (`0`)
+**** `jbProcedureTypeSelectable` (`1`)
+**** `jbProcedureTypeExecutable` (`2`).
+*** `JB_PROCEDURE_SOURCE` -- value of column `RDB$PROCEDURE_SOURCE`: the body of the stored procedure;
+this column is `null` for procedures in a package.
+** `getProcedureSourceCode` is deprecated, the recommended replacement is `DatabaseMetaData.getProcedures(String, String, String)`, column `JB_PROCEDURE_SOURCE`.
+** `getTriggerSourceCode`/`getViewSourceCode` now also have an overload accepting the schema;
+the overloads without a `schema` parameter, or `schema` is `null` will return the source code of the first match found (schema order is undefined).
+This behaviour also applies for -- now deprecated -- `getProcedureSourceCode(String)`.
++
 The `schema` parameter is ignored on Firebird 5.0 and older.
 ** `getSchemas()` returns all defined schemas
 ** `getSchemas(String catalog, String schemaPattern)` returns all schemas matching the `LIKE` pattern `schemaPattern`, with the following caveats

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

@@ -1195,6 +1195,8 @@ public boolean dataDefinitionIgnoredInTransactions() throws SQLException {
      *       <li>{@link #jbProcedureTypeExecutable} ({@code 2}) &mdash; executable</li>
      *   </ul>
      * </li>
+     * <li><b>JB_PROCEDURE_SOURCE</b> String =&gt; source of the body of the stored procedure
+     * ({@code RDB$PROCEDURES.RDB$PROCEDURE_SOURCE}); {@code null} for procedures in a package</li>
      * </ol>
      * </p>
      * <p>
@@ -1209,8 +1211,9 @@ public boolean dataDefinitionIgnoredInTransactions() throws SQLException {
      * <li>Column {@code PROCEDURE_CAT} for normal procedures is empty string ({@code ""}) instead of {@code null},
      * for packaged procedures it is the package name</li>
      * <li>Column {@code SPECIFIC_NAME} for packaged procedures will report
-     * {@code <quoted-package-name>.<quoted-procedure-name>} (normal procedures will report the same as column
-     * {@code PROCEDURE_NAME}, the unquoted name)</li></li>
+     * {@code [<quoted-schema-name>.]<quoted-package-name>.<quoted-procedure-name>} (on Firebird 5.0 and older, normal
+     * procedures will report the same as column {@code PROCEDURE_NAME}, the unquoted name, on Firebird 6.0 and higher,
+     * {@code <quoted-schema-name>.<quoted-procedure-name>})</li>
      * </ul>
      */
     @Override
@@ -1870,12 +1873,7 @@ public boolean generatedKeyAlwaysReturned() throws SQLException {
 
     @Override
     public String getProcedureSourceCode(String procedureName) throws SQLException {
-        return getProcedureSourceCode(null, procedureName);
-    }
-
-    @Override
-    public String getProcedureSourceCode(String schema, String procedureName) throws SQLException {
-        return getSourceCode(schema, procedureName, SourceObjectType.PROCEDURE);
+        return getSourceCode(null, procedureName, SourceObjectType.PROCEDURE);
     }
 
     @Override

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

@@ -22,59 +22,52 @@
 @SuppressWarnings("unused")
 public interface FirebirdDatabaseMetaData extends DatabaseMetaData {
 
-    // TODO Add schema support: remove/deprecate getProcedureSourceCode(String) and remove new alternative with schema,
-    //  and instead add a column to getProcedures(..)
-
     /**
      * Firebird procedure type is unknown (value of column {@code JB_PROCEDURE_TYPE} of
      * {@link #getProcedures(String, String, String)})
+     *
+     * @since 7
      */
     int jbProcedureTypeUnknown = 0;
     /**
      * Firebird procedure type is selectable (value of column {@code JB_PROCEDURE_TYPE} of
      * {@link #getProcedures(String, String, String)})
+     *
+     * @since 7
      */
     int jbProcedureTypeSelectable = 1;
     /**
      * Firebird procedure type is executable (value of column {@code JB_PROCEDURE_TYPE} of
      * {@link #getProcedures(String, String, String)})
+     *
+     * @since 7
      */
     int jbProcedureTypeExecutable = 2;
 
     /**
      * Get the source of a stored procedure.
      * <p>
-     * On Firebird 6.0 and higher, it is recommended to use {@link #getProcedureSourceCode(String, String)} instead.
+     * <strong>WARNING</strong>: On Firebird 6.0 and higher, the sources returned are for the first procedure found
+     * (with an undefined schema order!), use {@link DatabaseMetaData#getProcedures(String, String, String)} instead
+     * (column {@code JB_PROCEDURE_SOURCE}).
      * </p>
      *
      * @param procedureName
      *         name of the stored procedure
      * @return source of the stored procedure
      * @throws SQLException
      *         if specified procedure cannot be found
-     * @see #getProcedureSourceCode(String, String)
+     * @deprecated use {@link DatabaseMetaData#getProcedures(String, String, String)}, column
+     * {@code JB_PROCEDURE_SOURCE}; there are currently no plans to remove this method
      */
+    @Deprecated(forRemoval = false, since = "7")
     String getProcedureSourceCode(String procedureName) throws SQLException;
 
-    /**
-     * Get the source of a stored procedure.
-     *
-     * @param schema
-     *         schema of the stored procedure ({@code null} drops the schema from the search; ignored on Firebird 5.0
-     *         and older)
-     * @param procedureName
-     *         name of the stored procedure
-     * @return source of the stored procedure
-     * @throws SQLException
-     *         if specified procedure cannot be found
-     * @since 7
-     */
-    String getProcedureSourceCode(String schema, String procedureName) throws SQLException;
-
     /**
      * Get the source of a trigger.
      * <p>
-     * On Firebird 6.0 and higher, it is recommended to use {@link #getTriggerSourceCode(String, String)} instead.
+     * <strong>WARNING</strong>: On Firebird 6.0 and higher, the sources returned are for the first trigger found
+     * (with an undefined schema order!), use {@link #getTriggerSourceCode(String, String)} instead.
      * </p>
      *
      * @param triggerName
@@ -105,6 +98,10 @@ public interface FirebirdDatabaseMetaData extends DatabaseMetaData {
      * <p>
      * On Firebird 6.0 and higher, it is recommended to use {@link #getViewSourceCode(String, String)} instead.
      * </p>
+     * <p>
+     * <strong>WARNING</strong>: On Firebird 6.0 and higher, the sources returned are for the first view found
+     * (with an undefined schema order!), use {@link #getViewSourceCode(String, String)} instead
+     * </p>
      *
      * @param viewName
      *         name of the view

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

@@ -36,7 +36,7 @@ public abstract sealed class GetProcedures extends AbstractMetadataMethod {
     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(10)
+    private static final RowDescriptor ROW_DESCRIPTOR = DbMetadataMediator.newRowDescriptorBuilder(11)
             .at(0).simple(SQL_VARYING | 1, OBJECT_NAME_LENGTH, "PROCEDURE_CAT", PROCEDURES).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()
@@ -49,6 +49,8 @@ public abstract sealed class GetProcedures extends AbstractMetadataMethod {
             // space for quoted package name, ".", quoted procedure name (assuming no double quotes in name)
             .at(8).simple(SQL_VARYING, 2 * OBJECT_NAME_LENGTH + 5, "SPECIFIC_NAME", PROCEDURES).addField()
             .at(9).simple(SQL_SHORT, 0, "JB_PROCEDURE_TYPE", PROCEDURES).addField()
+            // Field in Firebird is actually a blob, using Integer.MAX_VALUE for length
+            .at(10).simple(SQL_VARYING, Integer.MAX_VALUE, "JB_PROCEDURE_SOURCE", PROCEDURES).addField()
             .toRowDescriptor();
 
     private GetProcedures(DbMetadataMediator mediator) {
@@ -81,6 +83,7 @@ final RowValue createMetadataRow(ResultSet rs, RowValueBuilder valueBuilder) thr
                 .at(7).setShort(rs.getShort("PROCEDURE_TYPE") == 0 ? procedureNoResult : procedureReturnsResult)
                 .at(8).setString(toSpecificName(catalog, schema, procedureName))
                 .at(9).setShort(rs.getShort("JB_PROCEDURE_TYPE"))
+                .at(10).setString(rs.getString("JB_PROCEDURE_SOURCE"))
                 .toRowValue(true);
     }
 
@@ -114,7 +117,8 @@ private static final class FB2_5 extends GetProcedures {
                   RDB$PROCEDURE_NAME as PROCEDURE_NAME,
                   RDB$DESCRIPTION as REMARKS,
                   RDB$PROCEDURE_OUTPUTS as PROCEDURE_TYPE,
-                  RDB$PROCEDURE_TYPE as JB_PROCEDURE_TYPE
+                  RDB$PROCEDURE_TYPE as JB_PROCEDURE_TYPE,
+                  RDB$PROCEDURE_SOURCE as JB_PROCEDURE_SOURCE
                 from RDB$PROCEDURES""";
 
         private static final String GET_PROCEDURES_ORDER_BY_2_5 = "\norder by RDB$PROCEDURE_NAME";
@@ -146,7 +150,8 @@ private static final class FB3 extends GetProcedures {
                   trim(trailing from RDB$PROCEDURE_NAME) as PROCEDURE_NAME,
                   RDB$DESCRIPTION as REMARKS,
                   RDB$PROCEDURE_OUTPUTS as PROCEDURE_TYPE,
-                  RDB$PROCEDURE_TYPE as JB_PROCEDURE_TYPE
+                  RDB$PROCEDURE_TYPE as JB_PROCEDURE_TYPE,
+                  RDB$PROCEDURE_SOURCE as JB_PROCEDURE_SOURCE
                 from RDB$PROCEDURES
                 where RDB$PACKAGE_NAME is null""";
 
@@ -180,7 +185,8 @@ private static final class FB3CatalogAsPackage extends GetProcedures {
                   trim(trailing from RDB$PROCEDURE_NAME) as PROCEDURE_NAME,
                   RDB$DESCRIPTION as REMARKS,
                   RDB$PROCEDURE_OUTPUTS as PROCEDURE_TYPE,
-                  RDB$PROCEDURE_TYPE as JB_PROCEDURE_TYPE
+                  RDB$PROCEDURE_TYPE as JB_PROCEDURE_TYPE,
+                  RDB$PROCEDURE_SOURCE as JB_PROCEDURE_SOURCE
                 from RDB$PROCEDURES""";
 
         private static final String GET_PROCEDURES_ORDER_BY_3_W_PKG =
@@ -228,7 +234,8 @@ private static final class FB6 extends GetProcedures {
                   trim(trailing from RDB$PROCEDURE_NAME) as PROCEDURE_NAME,
                   RDB$DESCRIPTION as REMARKS,
                   RDB$PROCEDURE_OUTPUTS as PROCEDURE_TYPE,
-                  RDB$PROCEDURE_TYPE as JB_PROCEDURE_TYPE
+                  RDB$PROCEDURE_TYPE as JB_PROCEDURE_TYPE,
+                  RDB$PROCEDURE_SOURCE as JB_PROCEDURE_SOURCE
                 from SYSTEM.RDB$PROCEDURES
                 where RDB$PACKAGE_NAME is null""";
 
@@ -268,7 +275,8 @@ private static final class FB6CatalogAsPackage extends GetProcedures {
                   trim(trailing from RDB$PROCEDURE_NAME) as PROCEDURE_NAME,
                   RDB$DESCRIPTION as REMARKS,
                   RDB$PROCEDURE_OUTPUTS as PROCEDURE_TYPE,
-                  RDB$PROCEDURE_TYPE as JB_PROCEDURE_TYPE
+                  RDB$PROCEDURE_TYPE as JB_PROCEDURE_TYPE,
+                  RDB$PROCEDURE_SOURCE as JB_PROCEDURE_SOURCE
                 from SYSTEM.RDB$PROCEDURES""";
 
         private static final String GET_PROCEDURES_ORDER_BY_6_W_PKG =

src/test/org/firebirdsql/jdbc/FBDatabaseMetaDataProceduresTest.java

@@ -388,7 +388,9 @@ private enum ProcedureMetaData implements MetaDataInfo {
         FUTURE3(6, String.class),
         REMARKS(7, String.class),
         PROCEDURE_TYPE(8, Short.class),
-        SPECIFIC_NAME(9, String.class)
+        SPECIFIC_NAME(9, String.class),
+        JB_PROCEDURE_TYPE(10, Short.class),
+        JB_PROCEDURE_SOURCE(11, String.class),
         ;
 
         private final int position;
@@ -410,14 +412,36 @@ public Class<?> getColumnClass() {
         }
     }
 
+    /**
+     * Returns the body of the stored procedure (after the first occurrence of {@code "\nAS\n"} or {@code "\nas\n"}).
+     *
+     * @param procedureSource
+     *         stored procedure source
+     * @return body, or {@code null} if there was no occurrence of the expected token (see above)
+     */
+    private static String extractBody(String procedureSource) {
+        int index = procedureSource.indexOf("\nAS\n");
+        int indexAs = procedureSource.indexOf("\nas\n");
+        if (index == -1) {
+            index = indexAs;
+        } else if (indexAs < index && indexAs != -1) {
+            index = indexAs;
+        }
+
+        if (index == -1) return null;
+        return procedureSource.substring(index + 4);
+    }
+
     private enum ProcedureTestData {
         NORMAL_PROC_NO_RETURN("NORMAL_PROC_NO_RETURN", List.of(CREATE_NORMAL_PROC_NO_RETURN)) {
             @Override
             Map<ProcedureMetaData, Object> getSpecificValidationRules(Map<ProcedureMetaData, Object> rules) {
                 rules.put(ProcedureMetaData.PROCEDURE_NAME, "NORMAL_PROC_NO_RETURN");
                 rules.put(ProcedureMetaData.PROCEDURE_TYPE, DatabaseMetaData.procedureNoResult);
+                rules.put(ProcedureMetaData.JB_PROCEDURE_TYPE, FirebirdDatabaseMetaData.jbProcedureTypeExecutable);
                 rules.put(ProcedureMetaData.SPECIFIC_NAME, ifSchemaElse(
                         ObjectReference.of("PUBLIC", "NORMAL_PROC_NO_RETURN").toString(), "NORMAL_PROC_NO_RETURN"));
+                rules.put(ProcedureMetaData.JB_PROCEDURE_SOURCE, extractBody(CREATE_NORMAL_PROC_NO_RETURN));
                 return rules;
             }
         },
@@ -427,9 +451,11 @@ Map<ProcedureMetaData, Object> getSpecificValidationRules(Map<ProcedureMetaData,
             Map<ProcedureMetaData, Object> getSpecificValidationRules(Map<ProcedureMetaData, Object> rules) {
                 rules.put(ProcedureMetaData.PROCEDURE_NAME, "NORMAL_PROC_WITH_RETURN");
                 rules.put(ProcedureMetaData.PROCEDURE_TYPE, DatabaseMetaData.procedureReturnsResult);
+                rules.put(ProcedureMetaData.JB_PROCEDURE_TYPE, FirebirdDatabaseMetaData.jbProcedureTypeExecutable);
                 rules.put(ProcedureMetaData.REMARKS, "Some comment");
                 rules.put(ProcedureMetaData.SPECIFIC_NAME, ifSchemaElse(
                         ObjectReference.of("PUBLIC", "NORMAL_PROC_WITH_RETURN").toString(), "NORMAL_PROC_WITH_RETURN"));
+                rules.put(ProcedureMetaData.JB_PROCEDURE_SOURCE, extractBody(CREATE_NORMAL_PROC_WITH_RETURN));
                 return rules;
             }
 
@@ -439,8 +465,10 @@ Map<ProcedureMetaData, Object> getSpecificValidationRules(Map<ProcedureMetaData,
             Map<ProcedureMetaData, Object> getSpecificValidationRules(Map<ProcedureMetaData, Object> rules) {
                 rules.put(ProcedureMetaData.PROCEDURE_NAME, "quoted_proc_no_return");
                 rules.put(ProcedureMetaData.PROCEDURE_TYPE, DatabaseMetaData.procedureNoResult);
+                rules.put(ProcedureMetaData.JB_PROCEDURE_TYPE, FirebirdDatabaseMetaData.jbProcedureTypeExecutable);
                 rules.put(ProcedureMetaData.SPECIFIC_NAME, ifSchemaElse(
                         ObjectReference.of("PUBLIC", "quoted_proc_no_return").toString(), "quoted_proc_no_return"));
+                rules.put(ProcedureMetaData.JB_PROCEDURE_SOURCE, extractBody(CREATE_QUOTED_PROC_NO_RETURN));
                 return rules;
             }
         },
@@ -451,8 +479,11 @@ Map<ProcedureMetaData, Object> getSpecificValidationRules(Map<ProcedureMetaData,
                 rules.put(ProcedureMetaData.PROCEDURE_CAT, "WITH$PROCEDURE");
                 rules.put(ProcedureMetaData.PROCEDURE_NAME, "IN$PACKAGE");
                 rules.put(ProcedureMetaData.PROCEDURE_TYPE, DatabaseMetaData.procedureReturnsResult);
+                rules.put(ProcedureMetaData.JB_PROCEDURE_TYPE, FirebirdDatabaseMetaData.jbProcedureTypeExecutable);
                 rules.put(ProcedureMetaData.SPECIFIC_NAME,
                         ObjectReference.of(ifSchemaElse("PUBLIC", ""), "WITH$PROCEDURE", "IN$PACKAGE").toString());
+                // No procedure body for packaged procedures
+                rules.put(ProcedureMetaData.JB_PROCEDURE_SOURCE, null);
                 return rules;
             }
 
@@ -472,8 +503,10 @@ Map<ProcedureMetaData, Object> getSpecificValidationRules(Map<ProcedureMetaData,
                 rules.put(ProcedureMetaData.PROCEDURE_SCHEM, "OTHER_SCHEMA");
                 rules.put(ProcedureMetaData.PROCEDURE_NAME, "PROC_NO_RETURN");
                 rules.put(ProcedureMetaData.PROCEDURE_TYPE, DatabaseMetaData.procedureNoResult);
+                rules.put(ProcedureMetaData.JB_PROCEDURE_TYPE, FirebirdDatabaseMetaData.jbProcedureTypeExecutable);
                 rules.put(ProcedureMetaData.SPECIFIC_NAME,
                         ObjectReference.of("OTHER_SCHEMA", "PROC_NO_RETURN").toString());
+                rules.put(ProcedureMetaData.JB_PROCEDURE_SOURCE, extractBody(CREATE_OTHER_SCHEMA_PROC_NO_RETURN));
                 return rules;
             }