Updated comments

stockexchange-TokenSDK/contracts/src/main/java/net/corda/examples/stockexchange/states/StockState.java

@@ -32,14 +32,12 @@ public class StockState extends EvolvableTokenType implements StatePersistable {
 
     public StockState(UniqueIdentifier linearId, List<Party> maintainers, String symbol, String name, String currency, BigDecimal dividend, Date exDate, Date payDate) {
         this.linearId = linearId;
-        this.maintainers = maintainers;
         this.symbol = symbol;
         this.name = name;
         this.currency = currency;
         this.dividend = dividend;
         this.exDate = exDate;
         this.payDate = payDate;
-        issuer = maintainers.get(0);
     }
 
     @NotNull

stockexchange-TokenSDK/workflows/src/main/java/net/corda/examples/stockexchange/flows/AnnounceDividend.java

@@ -5,6 +5,7 @@
 import com.r3.corda.lib.tokens.contracts.types.TokenPointer;
 import com.r3.corda.lib.tokens.workflows.flows.evolvable.UpdateEvolvableTokenFlow;
 import com.r3.corda.lib.tokens.workflows.flows.evolvable.UpdateEvolvableTokenFlowHandler;
+import com.r3.corda.lib.tokens.workflows.flows.rpc.UpdateEvolvableToken;
 import net.corda.core.contracts.StateAndRef;
 import net.corda.core.flows.*;
 import net.corda.core.identity.Party;
@@ -19,6 +20,10 @@
 import java.util.Date;
 import java.util.List;
 
+/**
+ * In this flow, the StockState is updated to declare a number of dividend via the built-in flow UpdateEvolvableToken.
+ * The holder of the tokens of the StockState will not be affected.
+ */
 public class AnnounceDividend {
 
     @InitiatingFlow
@@ -41,10 +46,11 @@ public Initiator(String symbol, BigDecimal quantity, Date executionDate, Date pa
         @Suspendable
         public SignedTransaction call() throws FlowException {
 
-            TokenPointer stockPointer = QueryUtilities.queryStockPointer(symbol, getServiceHub());
-            StateAndRef<StockState> stockStateRef = stockPointer.getPointer().resolve(getServiceHub());
+            // Retrieved the unconsumed StockState from the vault
+            StateAndRef<StockState> stockStateRef = QueryUtilities.queryStock(symbol, getServiceHub());
             StockState stock = stockStateRef.getState().getData();
 
+            // Form the output state here
             StockState outputState = new StockState(
                     stock.getLinearId(),
                     stock.getMaintainers(),
@@ -57,19 +63,11 @@ public SignedTransaction call() throws FlowException {
 
             IdentityService identityService = getServiceHub().getIdentityService();
 
-
-            //Get all observers
-            //TODO Update the observers
             List<Party> observers = ObserversUtilities.getLegalIdenties(identityService);
 
-            List<FlowSession> observerSessions = new ArrayList<>();
-            for (Party observer : observers){
-                observerSessions.add(initiateFlow(observer));
-            }
-
             // here use observer approach to send the stock update to exchange and all participants.
             // One of the better design is the participant to request the update before market open by using sendTransactionFlow
-            return subFlow(new UpdateEvolvableTokenFlow(stockStateRef, outputState, ImmutableList.of(), observerSessions));
+            return subFlow(new UpdateEvolvableToken(stockStateRef, outputState, observers));
         }
     }
 

stockexchange-TokenSDK/workflows/src/main/java/net/corda/examples/stockexchange/flows/GetStockUpdate.java

@@ -33,7 +33,7 @@ public SignedTransaction call() throws FlowException {
             session.send(stockState.getSymbol());
 
             // Receive the transaction, checks for the signatures of the state and then record it in vault
-            return subFlow(new ReceiveTransactionFlow(session, true, StatesToRecord.ALL_VISIBLE));
+            return subFlow(new ReceiveTransactionFlow(session, true, StatesToRecord.ONLY_RELEVANT));
         }
     }
 

stockexchange-TokenSDK/workflows/src/main/java/net/corda/examples/stockexchange/flows/IssueMoney.java

@@ -24,9 +24,6 @@ public class IssueMoney extends FlowLogic<SignedTransaction> {
     private Long quantity;
     private Party recipient;
 
-    // Using NetworkmapCache.getNotaryIdentities().get(0) is not encouraged due to multi notary is introduced
-    // private Party notary;
-
     public IssueMoney(String currency, Long amount, Party recipient) {
         this.currency = currency;
         this.quantity = amount;
@@ -37,16 +34,16 @@ public IssueMoney(String currency, Long amount, Party recipient) {
     @Suspendable
     public SignedTransaction call() throws FlowException {
 
-        /* Create an instance of the fiat currency token */
+        // Create an instance of the fiat currency token type
         TokenType token = FiatCurrency.Companion.getInstance(currency);
 
-        /* Create an instance of IssuedTokenType for the fiat currency */
+        // Create an instance of IssuedTokenType which represents the token is issued by this party
         IssuedTokenType issuedTokenType = new IssuedTokenType(getOurIdentity(), token);
 
-        /* Create an instance of FungibleToken for the fiat currency to be issued */
+        // Create an instance of FungibleToken for the fiat currency to be issued
         FungibleToken fungibleToken = new FungibleToken(new Amount<>(quantity, issuedTokenType), recipient, null);
 
-        /* Issue the required amount of the token to the recipient */
+        // Use the build-in flow, IssueTokens, to issue the required amount to the the recipient
         return subFlow(new IssueTokens(ImmutableList.of(fungibleToken), ImmutableList.of(recipient)));
     }
 }

stockexchange-TokenSDK/workflows/src/main/java/net/corda/examples/stockexchange/flows/IssueStock.java

@@ -47,28 +47,33 @@ public IssueStock(String symbol, String name, String currency, int issueVol, Par
     @Suspendable
     public SignedTransaction call() throws FlowException {
 
+        // Sample specific - retrieving the hard-coded observers
         IdentityService identityService = getServiceHub().getIdentityService();
-
         List<Party> observers = ObserversUtilities.getLegalIdenties(identityService);
 
-        // Get a reference of own identity
         Party issuer = getOurIdentity();
 
-        // Construct the output state
+        // Construct the output StockState
         final StockState stockState = new StockState(new UniqueIdentifier(), ImmutableList.of(issuer),
                 symbol, name, currency, BigDecimal.valueOf(0), new Date(), new Date()
                 );
 
+        // The notary provided here will be used in all future actions of this token
         TransactionState<StockState> transactionState = new TransactionState<>(stockState, notary);
 
+        // Using the build-in flow to create an evolvable token type -- Stock
         subFlow(new CreateEvolvableTokens(transactionState, observers));
 
+        // Similar in IssueMoney flow, class of IssuedTokenType represents the stock is issued by the issuer party
         IssuedTokenType issuedStock = new IssuedTokenType(issuer, stockState.toPointer());
 
+        // Create an specified amount of stock with a pointer that refers to the StockState
         Amount<IssuedTokenType> issueAmount = new Amount(new Long(issueVol), issuedStock);
 
+        // Indicate the recipient which is the issuing party itself here
         FungibleToken stockToken = new FungibleToken(issueAmount, getOurIdentity(), null);
 
+        // Finally, use the build-in flow to issue the stock tokens. Observer parties provided here will record a copy of the transactions
         return subFlow(new IssueTokens(ImmutableList.of(stockToken), observers));
     }
 }

stockexchange-TokenSDK/workflows/src/main/java/net/corda/examples/stockexchange/flows/MoveStock.java

@@ -4,6 +4,7 @@
 import com.r3.corda.lib.tokens.contracts.types.TokenPointer;
 import com.r3.corda.lib.tokens.contracts.types.TokenType;
 import com.r3.corda.lib.tokens.workflows.flows.move.MoveFungibleTokensFlow;
+import com.r3.corda.lib.tokens.workflows.flows.rpc.MoveFungibleTokens;
 import com.r3.corda.lib.tokens.workflows.flows.rpc.MoveFungibleTokensHandler;
 import com.r3.corda.lib.tokens.workflows.types.PartyAndAmount;
 
@@ -38,16 +39,14 @@ public Initiator(String symbol, Long quantity, Party recipient) {
         @Suspendable
         public SignedTransaction call() throws FlowException {
 
+            // To get the transferring stock, we can get the StockState from the vault and get it's pointer
             TokenPointer<StockState> stockPointer = QueryUtilities.queryStockPointer(symbol, getServiceHub());
 
-            Amount<TokenType> amount = new Amount<TokenType>(quantity, stockPointer);
+            // With the pointer, we can get the create an instance of transferring Amount
+            Amount<TokenType> amount = new Amount(quantity, stockPointer);
 
-            PartyAndAmount<TokenType> partyAndAmount = new PartyAndAmount<TokenType>(recipient, amount);
-
-            FlowSession session = initiateFlow(recipient);
-
-            //use built in flow for issuing tokens on ledger
-            return subFlow(new MoveFungibleTokensFlow(ImmutableList.of(partyAndAmount), ImmutableList.of(session)));
+            //Use built-in flow for move tokens to the recipient
+            return subFlow(new MoveFungibleTokens(amount, recipient));
         }
     }
 
@@ -63,6 +62,7 @@ public Responder(FlowSession counterSession) {
         @Suspendable
         @Override
         public Unit call() throws FlowException {
+            // Simply use the MoveFungibleTokensHandler as the responding flow
             return subFlow(new MoveFungibleTokensHandler(counterSession));
         }
     }

stockexchange-TokenSDK/workflows/src/main/java/net/corda/examples/stockexchange/flows/QueryStock.java

@@ -2,26 +2,21 @@
 
 import co.paralleluniverse.fibers.Suspendable;
 import com.r3.corda.lib.tokens.contracts.types.TokenPointer;
-import com.r3.corda.lib.tokens.workflows.utilities.FlowUtilitiesKt;
 import com.r3.corda.lib.tokens.workflows.utilities.QueryUtilitiesKt;
 import net.corda.core.contracts.Amount;
 import net.corda.core.contracts.StateAndRef;
-import net.corda.core.flows.*;
-import net.corda.core.identity.AbstractParty;
-import net.corda.core.node.ServiceHub;
-import net.corda.core.node.services.Vault;
-import net.corda.core.node.services.vault.QueryCriteria;
-import net.corda.core.transactions.SignedTransaction;
-import net.corda.core.transactions.WireTransaction;
+import net.corda.core.flows.FlowException;
+import net.corda.core.flows.FlowLogic;
+import net.corda.core.flows.InitiatingFlow;
+import net.corda.core.flows.StartableByRPC;
 import net.corda.core.utilities.ProgressTracker;
 import net.corda.examples.stockexchange.flows.utilities.QueryUtilities;
-import org.slf4j.Logger;
 
 public class QueryStock {
 
-    @StartableByRPC
     @InitiatingFlow
-    public class QueryTokenBalance extends FlowLogic<Amount<TokenPointer>> {
+    @StartableByRPC
+    public static class QueryTokenBalance extends FlowLogic<Amount<TokenPointer>> {
         private final ProgressTracker progressTracker = new ProgressTracker();
         private final String symbol;
 
@@ -37,21 +32,15 @@ public ProgressTracker getProgressTracker() {
         @Override
         @Suspendable
         public Amount<TokenPointer> call() throws FlowException {
-            QueryCriteria generalCriteria = new QueryCriteria.VaultQueryCriteria(Vault.StateStatus.ALL);
-
-            Amount<TokenPointer> amount = null;
-
             TokenPointer stockPointer = QueryUtilities.queryStockPointer(symbol, getServiceHub());
-            if(stockPointer != null)
-                amount = QueryUtilitiesKt.tokenBalance(getServiceHub().getVaultService(), stockPointer);
-
-            return amount;
+            Amount<TokenPointer> a = QueryUtilitiesKt.tokenBalance(getServiceHub().getVaultService(), stockPointer);
+            return a;
         }
     }
 
-    @StartableByRPC
     @InitiatingFlow
-    public class QueryStockDetail extends FlowLogic<String> {
+    @StartableByRPC
+    public static class QueryStockDetail extends FlowLogic<String> {
         private final ProgressTracker progressTracker = new ProgressTracker();
         private final String symbol;
 

stockexchange-TokenSDK/workflows/src/main/java/net/corda/examples/stockexchange/flows/utilities/QueryUtilities.java

@@ -10,7 +10,11 @@
 import java.util.List;
 
 public class QueryUtilities {
-    public static TokenPointer<StockState> queryStockPointer(String symbol, ServiceHub serviceHub){
+
+    /**
+     * Retrieve any unconsumed StockState and filter by the given symbol
+     */
+    public static StateAndRef<StockState> queryStock(String symbol, ServiceHub serviceHub){
         QueryCriteria.VaultQueryCriteria generalCriteria = new QueryCriteria.VaultQueryCriteria(Vault.StateStatus.UNCONSUMED);
 
         List<StateAndRef<StockState>> stateAndRefs = serviceHub.getVaultService().queryBy(StockState.class, generalCriteria).getStates();
@@ -20,6 +24,17 @@ public static TokenPointer<StockState> queryStockPointer(String symbol, ServiceH
                 .filter(sf->sf.getState().getData().getSymbol().equals(symbol)).findAny()
                 .orElseThrow(()-> new IllegalArgumentException("StockState symbol=\""+symbol+"\" not found from vault"));
 
-        return stockStateAndRef.getState().getData().toPointer(StockState.class);
+        return stockStateAndRef;
+    }
+
+    /**
+     * Retrieve any unconsumed StockState and filter by the given symbol
+     * Then return the pointer to this StockState
+     */
+    public static TokenPointer<StockState> queryStockPointer(String symbol, ServiceHub serviceHub){
+
+        StateAndRef<StockState> stockStateStateAndRef = queryStock(symbol, serviceHub);
+
+        return stockStateStateAndRef.getState().getData().toPointer(StockState.class);
     }
 }

stockexchange-TokenSDK/workflows/src/main/java/net/corda/examples/stockexchange/flows/utilities/TempTokenSelectionFactory.java

@@ -5,10 +5,16 @@
 
 /**
  * This is a temporary helping class for getting TokenSelection for Java
+ *
  */
 public class TempTokenSelectionFactory {
 
     public static TokenSelection getTokenSelection(ServiceHub serviceHub){
+        /* The following parameters are default values
+            - maxRetries : 8
+            - retrySleep : 100
+            - retryCap   : 200
+          */
         return new TokenSelection(serviceHub, 8, 100, 200);
     }
 }