CORE-183242: Vault query custom ordering (#1507)

API changes to add order by clause to custom queries

Co-authored-by: Christian Sailer <[email protected]>

gradle.properties

@@ -5,7 +5,7 @@ cordaProductVersion = 5.2.0
 # NOTE: update this each time this module contains a breaking change
 ## NOTE: currently this is a top level revision, so all API versions will line up, but this could be moved to
 ##   a per module property in which case module versions can change independently.
-cordaApiRevision = 45
+cordaApiRevision = 46
 
 # Main
 kotlin.stdlib.default.dependency = false

ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/query/registration/VaultNamedQueryBuilder.java

@@ -26,6 +26,47 @@ public interface VaultNamedQueryBuilder extends VaultNamedQueryBuilderBase {
     @NotNull
     VaultNamedQueryBuilder whereJson(@NotNull String query);
 
+
+    /**
+     * Sets an ORDER BY expression. The columnExpression needs to evaluate to a value in the vault database, i.e.
+     * either a column name or a JSON expression. The flags string allows to set order by flags, e.g. "ASC",
+     * these will be passed through to the database as is, so be careful with using database vendor specific
+     * flags.
+     * This function can be called multiple times on one VaultNamedQueryBuilder. The order of calls matters - the first
+     * call defines the primary order, and within that the column of the second call will be used etc.
+     *
+     * @param columnExpression SQL expression that results in a value to order by
+     * @param flags ORDER BY flags, e.g. ASC or DESC.
+     * @return A builder instance with the ORDER BY field set.
+     */
+    @NotNull
+    VaultNamedQueryBuilder orderBy( @NotNull String columnExpression, String flags );
+
+    /**
+     * Sets an ORDER BY expression. The columnExpression needs to evaluate to a value in the vault database, i.e.
+     * either a column name or a JSON expression. This is equivalent
+     * to calling `oderBy(columnExpression, null);`
+     * This function can be called multiple times on one VaultNamedQueryBuilder. The order of calls matters - the first
+     * call defines the primary order, and within that the column of the second call will be used etc.
+     *
+     * @param columnExpression SQL expression that results in a value to order by
+     * @return A builder instance with the ORDER BY field set.
+     */
+    @NotNull
+    VaultNamedQueryBuilder orderBy( @NotNull String columnExpression);
+
+
+    /**
+     * Sets a flag to add the appropriate where clause to only select states that are unconsumed as of the time
+     * of the initial query. Use this in favour of adding a `visible_states.consumed is NULL` clause to the
+     * whereJson field. Note that states returned from such a query can still be consumed if they have
+     * been consumed after the initial query was executed.
+     *
+     * @return A builder instance with the unconsumed only flag set.
+     */
+    @NotNull
+    VaultNamedQueryBuilder selectUnconsumedStatesOnly();
+
     /**
      * Sets the filter function of the named query.
      * <p>