CORE-17605 - Deprecated TokenClaim.useAndRelease (#1289)

Claimed tokens are now managed differently which makes the method irrelevant. From release 5.1, nothing will happen if the method is called.

gradle.properties

@@ -9,7 +9,7 @@ cordaProductVersion = 5.1.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 = 31
+cordaApiRevision = 32
 
 # Main
 kotlinVersion = 1.8.21

ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/token/selection/TokenClaim.java

@@ -11,15 +11,8 @@
  * Defines a claimed set of tokens returned by a call to {@link TokenSelection#tryClaim(TokenClaimCriteria)}.
  * <p>
  * The claimed {@link ClaimedToken} list is exclusively locked by the flow that made the claim and are
- * unavailable to any other flows.
- * <p>
- * Once a flow has either spent some or all of the claimed tokens, it should call {@link TokenClaim#useAndRelease(List)}
- * to notify the cache which tokens were used.
- * <p>
- * Any unused tokens will be released and made available to other flows.
- * <p>
- * If the flow does not call {@link TokenClaim#useAndRelease(List)}, the tokens will remain locked until the cache
- * receives a consumed notification from the vault or the claim timeout elapses.
+ * unavailable to any other flows. Any unconsumed token that has been claimed by the flow is released and made
+ * available to other flows once the flow terminates either successfully or unsuccessfully.
  */
 @DoNotImplement
 public interface TokenClaim {
@@ -34,9 +27,12 @@ public interface TokenClaim {
 
     /**
      * Removes any used tokens from the cache and unlocks any remaining tokens for other flows to claim.
+     * This method is now deprecated. Claimed tokens are now managed differently which makes the method
+     * irrelevant. From release 5.1, nothing will happen if the method is called.
      *
      * @param usedTokensRefs The {@link List} of {@link StateRef}s to mark as used.
      */
     @Suspendable
+    @Deprecated(since = "5.1", forRemoval = true)
     void useAndRelease(@NotNull List<StateRef> usedTokensRefs);
 }

ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/token/selection/TokenSelection.java

@@ -51,11 +51,7 @@ public interface TokenSelection {
      * // take alternative action.
      * } else {
      * // Tokens we successfully claimed and can now be spent.
-     * val spentTokenRefs = spendTokens(claim.claimedTokens)
-     *
-     * // Release the claim by notifying the cache which tokens where spent. Any unspent
-     * // tokens will be released for other flows to claim.
-     * claim.useAndRelease(spentTokenRefs!!)
+     * spendTokens(claim.claimedTokens)
      * }
      *
      * return "Done"
@@ -83,11 +79,7 @@ public interface TokenSelection {
      * // take alternative action.
      * } else {
      * // Tokens we successfully claimed and can now be spent.
-     * List<StateRef> spentTokenRefs = spendTokens(claim.getClaimedTokens());
-     *
-     * // Release the claim by notifying the cache which tokens where spent. Any unspent
-     * // tokens will be released for other flows to claim.
-     * claim.useAndRelease(spentTokenRefs);
+     * spendTokens(claim.getClaimedTokens());
      * }
      *
      * return "Done";