[CORDA-2298] Update trackBy documentation (#4496)

* Update the documentation for trackBy to better indicate that updates are not filtered according to the query criteria
* Add a test that shows the behaviour, which is skipped for now until a solution is implemented.

core/src/main/kotlin/net/corda/core/node/services/VaultService.kt

@@ -390,8 +390,11 @@ interface VaultService {
      *
      * @throws VaultQueryException if the query cannot be executed for any reason.
      *
-     * Notes: the snapshot part of the query adheres to the same behaviour as the [queryBy] function.
-     *        the [QueryCriteria] applies to both snapshot and deltas (streaming updates).
+     * Notes:
+     *    - The snapshot part of the query adheres to the same behaviour as the [queryBy] function.
+     *    - The update part of the query currently only supports query criteria filtering by contract
+     *      type(s) and state status(es). CID-731 <https://r3-cev.atlassian.net/browse/CID-731> proposes
+     *      adding the complete set of [QueryCriteria] filtering.
      */
     @Throws(VaultQueryException::class)
     fun <T : ContractState> _trackBy(criteria: QueryCriteria,

docs/source/api-vault-query.rst

@@ -64,7 +64,8 @@ filter criteria:
 - Use ``queryBy`` to obtain a current snapshot of data (for a given ``QueryCriteria``)
 - Use ``trackBy`` to obtain both a current snapshot and a future stream of updates (for a given ``QueryCriteria``)
   
-.. note:: Streaming updates are only filtered based on contract type and state status (UNCONSUMED, CONSUMED, ALL)
+.. note:: Streaming updates are only filtered based on contract type and state status (UNCONSUMED, CONSUMED, ALL).
+          They will not respect any other criteria that the initial query has been filtered by.
 
 Simple pagination (page number and size) and sorting (directional ordering using standard or custom property
 attributes) is also specifiable. Defaults are defined for paging (pageNumber = 1, pageSize = 200) and sorting

node/src/test/kotlin/net/corda/node/services/vault/NodeVaultServiceTest.kt

@@ -37,10 +37,7 @@ import net.corda.testing.node.MockServices
 import net.corda.testing.node.makeTestIdentityService
 import org.assertj.core.api.Assertions.assertThat
 import org.assertj.core.api.Assertions.assertThatExceptionOfType
-import org.junit.After
-import org.junit.Before
-import org.junit.Rule
-import org.junit.Test
+import org.junit.*
 import rx.observers.TestSubscriber
 import java.math.BigDecimal
 import java.util.*
@@ -857,4 +854,43 @@ class NodeVaultServiceTest {
             vaultService.queryBy<DummyDealContract.State>().states.size
         })
     }
+
+    @Test
+    @Ignore
+    fun `trackByCriteria filters updates and snapshots`() {
+        /*
+         * This test is ignored as the functionality it tests is not yet implemented - see CORDA-2389
+         */
+        fun addCashToVault() {
+            database.transaction {
+                vaultFiller.fillWithSomeTestCash(100.DOLLARS, issuerServices, 1, DUMMY_CASH_ISSUER)
+            }
+        }
+
+        fun addDummyToVault() {
+            database.transaction {
+                vaultFiller.fillWithDummyState()
+            }
+        }
+        addCashToVault()
+        addDummyToVault()
+        val criteria = VaultQueryCriteria(contractStateTypes = setOf(Cash.State::class.java))
+        val data = vaultService.trackBy<ContractState>(criteria)
+        for (state in data.snapshot.states) {
+            assertEquals(Cash.PROGRAM_ID, state.state.contract)
+        }
+
+        val allCash = data.updates.all {
+            it.produced.all {
+                it.state.contract == Cash.PROGRAM_ID
+            }
+        }
+
+        addCashToVault()
+        addDummyToVault()
+        addCashToVault()
+        allCash.subscribe {
+            assertTrue(it)
+        }
+    }
 }