CORE-11865: Add strategy to TokenClaimCriteria (#1562)

* Adds a new Strategy enum with RANDOM and PRIORTY values
* Adds strategy property to TokenClaimCriteria

ledger/ledger-utxo/scans/corda-ledger-utxo-5.3.0.yaml

@@ -718,6 +718,12 @@ net.corda.v5.ledger.utxo.observer.UtxoToken:
       default: false
       type: public
       returnType: net.corda.v5.ledger.utxo.observer.UtxoTokenPoolKey
+    getPriority:
+      annotations:
+        - Nullable
+      default: false
+      type: public
+      returnType: Long
     hashCode:
       annotations: []
       default: false
@@ -1244,6 +1250,24 @@ net.corda.v5.ledger.utxo.token.selection.ClaimedToken:
       default: false
       type: public abstract
       returnType: String
+net.corda.v5.ledger.utxo.token.selection.Strategy:
+  annotations: []
+  type: public final class
+  extends: java.lang.Enum
+  implements: []
+  interface: false
+  methods:
+    valueOf:
+      annotations: []
+      default: false
+      type: public static
+      returnType: net.corda.v5.ledger.utxo.token.selection.Strategy
+      params: {}
+    values:
+      annotations: []
+      default: false
+      type: public static
+      returnType: "net.corda.v5.ledger.utxo.token.selection.Strategy[]"
 net.corda.v5.ledger.utxo.token.selection.TokenBalance:
   annotations:
     - DoNotImplement
@@ -1407,6 +1431,12 @@ net.corda.v5.ledger.utxo.token.selection.TokenClaimCriteria:
       default: false
       type: public
       returnType: net.corda.v5.crypto.SecureHash
+    getStrategy:
+      annotations:
+        - Nullable
+      default: false
+      type: public
+      returnType: net.corda.v5.ledger.utxo.token.selection.Strategy
     getSymbol:
       annotations:
         - NotNull
@@ -1446,6 +1476,16 @@ net.corda.v5.ledger.utxo.token.selection.TokenClaimCriteria:
           annotation:
             - Nullable
           type: net.corda.v5.crypto.SecureHash
+    setStrategy:
+      annotations: []
+      default: false
+      type: public
+      returnType: void
+      params:
+        strategy:
+          annotation:
+            - Nullable
+          type: net.corda.v5.ledger.utxo.token.selection.Strategy
     setTagRegex:
       annotations: []
       default: false

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

@@ -0,0 +1,23 @@
+package net.corda.v5.ledger.utxo.token.selection;
+
+/**
+ * Token selection strategy. RANDOM is the default.
+ */
+public enum Strategy {
+    /**
+     * Choose tokens in transaction ID order. As this field is not a sequential value, it has the effect of a pseudo
+     * random order.
+     * <p>
+     * This is the default selection strategy.
+     */
+    RANDOM,
+
+    /**
+     * Choose tokens in priority, then transaction ID order.
+     * <p>
+     * Lower priority values are treated as higher priority. Equal priority values fall back to transaction ID ordering,
+     * behaving the same as RANDOM strategy. Null priority values are sorted to the end, making them the lowest possible
+     * priority.
+     */
+    PRIORITY
+}

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

@@ -59,6 +59,13 @@ public final class TokenClaimCriteria {
     @Nullable
     private SecureHash ownerHash;
 
+    /**
+     * Token selection strategy.
+     * Defaults to RANDOM.
+     */
+    @Nullable
+    private Strategy strategy;
+
     /**
      * Creates a new instance of the {@link TokenClaimCriteria} class.
      *
@@ -74,11 +81,32 @@ public TokenClaimCriteria(
             @NotNull final MemberX500Name notaryX500Name,
             @NotNull final String symbol,
             @NotNull final BigDecimal targetAmount) {
+        this(tokenType, issuerHash, notaryX500Name, symbol, targetAmount, null);
+    }
+
+    /**
+     * Creates a new instance of the {@link TokenClaimCriteria} class.
+     *
+     * @param tokenType      The type of tokens to be selected.
+     * @param issuerHash     The {@link SecureHash} of the issuer of tokens to be selected.
+     * @param notaryX500Name The {@link MemberX500Name} of the notary of the tokens to be selected.
+     * @param symbol         The symbol of the notary of tokens to be selected.
+     * @param targetAmount   The minimum value for the sum of {@link ClaimedToken#getAmount()} for the selected tokens.
+     * @param strategy       The token selection strategy to use.
+     */
+    public TokenClaimCriteria(
+            @NotNull final String tokenType,
+            @NotNull final SecureHash issuerHash,
+            @NotNull final MemberX500Name notaryX500Name,
+            @NotNull final String symbol,
+            @NotNull final BigDecimal targetAmount,
+            @Nullable final Strategy strategy) {
         this.tokenType = tokenType;
         this.issuerHash = issuerHash;
         this.notaryX500Name = notaryX500Name;
         this.symbol = symbol;
         this.targetAmount = targetAmount;
+        this.strategy = strategy;
     }
 
     /**
@@ -165,6 +193,23 @@ public void setOwnerHash(@Nullable final SecureHash ownerHash) {
         this.ownerHash = ownerHash;
     }
 
+    /**
+     * Gets token selection strategy.
+     *
+     * @return Returns token selection strategy {@link Strategy}, or null if none specified.
+     */
+    @Nullable
+    public Strategy getStrategy() {
+        return strategy;
+    }
+
+    /**
+     * Sets a token selection strategy {@link Strategy}, or null to use the default strategy.
+     */
+    public void setStrategy(@Nullable final Strategy strategy) {
+        this.strategy = strategy;
+    }
+
     /**
      * Determines whether the specified object is equal to the current object.
      *
@@ -189,7 +234,8 @@ public boolean equals(@NotNull final TokenClaimCriteria other) {
                 && Objects.equals(other.symbol, symbol)
                 && Objects.compare(other.targetAmount, targetAmount, BigDecimal::compareTo) == 0
                 && Objects.equals(other.tagRegex, tagRegex)
-                && Objects.equals(other.ownerHash, ownerHash);
+                && Objects.equals(other.ownerHash, ownerHash)
+                && Objects.equals(other.strategy, strategy);
     }
 
     /**
@@ -199,7 +245,7 @@ public boolean equals(@NotNull final TokenClaimCriteria other) {
      */
     @Override
     public int hashCode() {
-        return Objects.hash(tokenType, issuerHash, notaryX500Name, symbol, targetAmount, tagRegex, ownerHash);
+        return Objects.hash(tokenType, issuerHash, notaryX500Name, symbol, targetAmount, tagRegex, ownerHash, strategy);
     }
 
     /**
@@ -210,8 +256,8 @@ public int hashCode() {
     @Override
     public String toString() {
         return MessageFormat.format(
-                "TokenClaimCriteria(tokenType={0}, issuerHash={1}, notaryX500Name={2}, symbol={3}, targetAmount={4}, tagRegex={5}, ownerHash={6})",
-                tokenType, issuerHash, notaryX500Name, symbol, targetAmount, tagRegex, ownerHash
+                "TokenClaimCriteria(tokenType={0}, issuerHash={1}, notaryX500Name={2}, symbol={3}, targetAmount={4}, tagRegex={5}, ownerHash={6}, strategy={7})",
+                tokenType, issuerHash, notaryX500Name, symbol, targetAmount, tagRegex, ownerHash, strategy
         );
     }
 }