Clean up API for selecting notaries (#1573)

* Remove getAnyNotary() from network map API.
Change notaryIdentities() signature to return a Party instead of PartyAndCertificate.
Some API doc updates.

* Minor API doc formatting and typo fix

* Update changelog

* Address comments

* Address comments

docs/source/example-code/src/integration-test/kotlin/net/corda/docs/IntegrationTestingTutorial.kt

@@ -56,7 +56,7 @@ class IntegrationTestingTutorial {
 
             // START 4
             val issueRef = OpaqueBytes.of(0)
-            val notaryParty = aliceProxy.notaryIdentities().first().party
+            val notaryParty = aliceProxy.notaryIdentities().first()
             (1..10).map { i ->
                 aliceProxy.startFlow(::CashIssueFlow,
                         i.DOLLARS,

docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java

@@ -125,11 +125,10 @@ public class FlowCookbookJava {
             // We retrieve a notary from the network map.
             // DOCSTART 1
             Party specificNotary = getServiceHub().getNetworkMapCache().getNotary(new CordaX500Name("Notary Service", "London", "UK"));
-            Party anyNotary = getServiceHub().getNetworkMapCache().getAnyNotary();
-            // Unlike the first two methods, ``getNotaryNodes`` returns a
-            // ``List<NodeInfo>``. We have to extract the notary identity of
-            // the node we want.
-            Party firstNotary = getServiceHub().getNetworkMapCache().getNotaryIdentities().get(0).getParty();
+            // Alternatively, we can pick an arbitrary notary from the notary list. However, it is always preferable to
+            // specify which notary to use explicitly, as the notary list might change when new notaries are introduced,
+            // or old ones decommissioned.
+            Party firstNotary = getServiceHub().getNetworkMapCache().getNotaryIdentities().get(0);
             // DOCEND 1
 
             // We may also need to identify a specific counterparty.

docs/source/example-code/src/main/kotlin/net/corda/docs/ClientRpcTutorial.kt

@@ -113,7 +113,7 @@ fun generateTransactions(proxy: CordaRPCOps) {
         sum + state.state.data.amount.quantity
     }
     val issueRef = OpaqueBytes.of(0)
-    val notary = proxy.notaryIdentities().first().party
+    val notary = proxy.notaryIdentities().first()
     val me = proxy.nodeInfo().legalIdentities.first()
     while (true) {
         Thread.sleep(1000)

docs/source/example-code/src/main/kotlin/net/corda/docs/CustomVaultQuery.kt

@@ -20,7 +20,6 @@ import net.corda.finance.flows.AbstractCashFlow
 import net.corda.finance.flows.CashException
 import net.corda.finance.flows.CashIssueFlow
 import net.corda.finance.flows.CashPaymentFlow
-import net.corda.testing.getDefaultNotary
 import java.util.*
 
 // DOCSTART CustomVaultQuery
@@ -133,7 +132,8 @@ object TopupIssuerFlow {
                                 issueTo: Party,
                                 issuerPartyRef: OpaqueBytes): AbstractCashFlow.Result {
             // TODO: pass notary in as request parameter
-            val notaryParty = serviceHub.networkMapCache.getAnyNotary() ?: throw IllegalArgumentException("Couldn't find any notary in NetworkMapCache")
+            val notaryParty = serviceHub.networkMapCache.notaryIdentities.firstOrNull()
+                    ?: throw IllegalArgumentException("Couldn't find any notary in NetworkMapCache")
             // invoke Cash subflow to issue Asset
             progressTracker.currentStep = ISSUING
             val issueCashFlow = CashIssueFlow(amount, issuerPartyRef, notaryParty)

docs/source/example-code/src/main/kotlin/net/corda/docs/FlowCookbook.kt

@@ -104,11 +104,10 @@ object FlowCookbook {
             // We retrieve the notary from the network map.
             // DOCSTART 1
             val specificNotary: Party? = serviceHub.networkMapCache.getNotary(CordaX500Name(organisation = "Notary Service", locality = "London", country = "UK"))
-            val anyNotary: Party? = serviceHub.networkMapCache.getAnyNotary()
-            // Unlike the first two methods, ``getNotaryNodes`` returns a
-            // ``List<NodeInfo>``. We have to extract the notary identity of
-            // the node we want.
-            val firstNotary: Party = serviceHub.networkMapCache.notaryIdentities[0].party
+            // Alternatively, we can pick an arbitrary notary from the notary list. However, it is always preferable to
+            // specify which notary to use explicitly, as the notary list might change when new notaries are introduced,
+            // or old ones decommissioned.
+            val firstNotary: Party = serviceHub.networkMapCache.notaryIdentities.first()
             // DOCEND 1
 
             // We may also need to identify a specific counterparty. We

docs/source/example-code/src/main/kotlin/net/corda/docs/FxTransactionBuildTutorial.kt

@@ -39,7 +39,7 @@ private fun gatherOurInputs(serviceHub: ServiceHub,
     val ourParties = ourKeys.map { serviceHub.identityService.partyFromKey(it) ?: throw IllegalStateException("Unable to resolve party from key") }
     val fungibleCriteria = QueryCriteria.FungibleAssetQueryCriteria(owner = ourParties)
 
-    val notaries = notary ?: serviceHub.networkMapCache.getAnyNotary()
+    val notaries = notary ?: serviceHub.networkMapCache.notaryIdentities.first()
     val vaultCriteria: QueryCriteria = QueryCriteria.VaultQueryCriteria(notary = listOf(notaries as AbstractParty))
 
     val logicalExpression = builder { CashSchemaV1.PersistentCashState::currency.equal(amountRequired.token.product.currencyCode) }

docs/source/example-code/src/main/kotlin/net/corda/docs/WorkflowTransactionBuildTutorial.kt

@@ -17,7 +17,6 @@ import net.corda.core.transactions.SignedTransaction
 import net.corda.core.transactions.TransactionBuilder
 import net.corda.core.utilities.seconds
 import net.corda.core.utilities.unwrap
-import net.corda.testing.chooseIdentity
 
 // Minimal state model of a manual approval process
 @CordaSerializable
@@ -102,7 +101,7 @@ class SubmitTradeApprovalFlow(private val tradeId: String,
         // Manufacture an initial state
         val tradeProposal = TradeApprovalContract.State(tradeId, ourIdentity, counterparty)
         // identify a notary. This might also be done external to the flow
-        val notary = serviceHub.networkMapCache.getAnyNotary()
+        val notary = serviceHub.networkMapCache.notaryIdentities.first()
         // Create the TransactionBuilder and populate with the new state.
         val tx = TransactionBuilder(notary).withItems(
                 StateAndContract(tradeProposal, TRADE_APPROVAL_PROGRAM_ID),