From 17c654803dab84ad64f1c1cb0ae9c628cdcbd0f3 Mon Sep 17 00:00:00 2001
From: JamesHR3 <45565019+JamesHR3@users.noreply.github.com>
Date: Thu, 3 Jan 2019 16:23:54 +0000
Subject: [PATCH] [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.
---
 .../corda/core/node/services/VaultService.kt  |  7 ++-
 docs/source/api-vault-query.rst               |  3 +-
 .../services/vault/NodeVaultServiceTest.kt    | 44 +++++++++++++++++--
 3 files changed, 47 insertions(+), 7 deletions(-)

diff --git a/core/src/main/kotlin/net/corda/core/node/services/VaultService.kt b/core/src/main/kotlin/net/corda/core/node/services/VaultService.kt
index 55ce1a8284..1abaf49676 100644
--- a/core/src/main/kotlin/net/corda/core/node/services/VaultService.kt
+++ b/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,
diff --git a/docs/source/api-vault-query.rst b/docs/source/api-vault-query.rst
index 7b5c63e2ff..9ac0179a97 100644
--- a/docs/source/api-vault-query.rst
+++ b/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
diff --git a/node/src/test/kotlin/net/corda/node/services/vault/NodeVaultServiceTest.kt b/node/src/test/kotlin/net/corda/node/services/vault/NodeVaultServiceTest.kt
index 04fc2785d2..18b8dd7853 100644
--- a/node/src/test/kotlin/net/corda/node/services/vault/NodeVaultServiceTest.kt
+++ b/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)
+        }
+    }
 }