Extend messaging.rst about service queues

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

@@ -65,14 +65,19 @@ interface NetworkMapCache {
     /** Look up the node info for a legal name. */
     fun getNodeByLegalName(name: String): NodeInfo? = partyNodes.singleOrNull { it.legalIdentity.name == name }
 
-    /** Look up the node info for a composite key. */
+    /**
+     * In general, nodes can advertise multiple identities: a legal identity, and separate identities for each of
+     * the services it provides. In case of a distributed service – run by multiple nodes – each participant advertises
+     * the identity of the *whole group*.
+     */
+
+    /** Look up the node info for a specific peer key. */
     fun getNodeByLegalIdentityKey(compositeKey: CompositeKey): NodeInfo? {
         // Although we should never have more than one match, it is theoretically possible. Report an error if it happens.
         val candidates = partyNodes.filter { it.legalIdentity.owningKey == compositeKey }
         check(candidates.size <= 1) { "Found more than one match for key $compositeKey" }
         return candidates.singleOrNull()
     }
-
     /** Look up all nodes advertising the service owned by [compositeKey] */
     fun getNodesByAdvertisedServiceIdentityKey(compositeKey: CompositeKey): List<NodeInfo> {
         return partyNodes.filter { it.advertisedServices.any { it.identity.owningKey == compositeKey } }
@@ -81,20 +86,6 @@ interface NetworkMapCache {
     /** Returns information about the party, which may be a specific node or a service */
     fun getPartyInfo(party: Party): PartyInfo?
 
-    /**
-     * Given a [party], returns a node advertising it as an identity. If more than one node found the result
-     * is chosen at random.
-     *
-     * In general, nodes can advertise multiple identities: a legal identity, and separate identities for each of
-     * the services it provides. In case of a distributed service – run by multiple nodes – each participant advertises
-     * the identity of the *whole group*. If the provided [party] is a group identity, multiple nodes advertising it
-     * will be found, and this method will return a randomly chosen one. If [party] is an individual (legal) identity,
-     * we currently assume that it will be advertised by one node only, which will be returned as the result.
-     */
-    fun getRepresentativeNode(party: Party): NodeInfo? {
-        return partyNodes.randomOrNull { it.legalIdentity == party || it.advertisedServices.any { it.identity == party } }
-    }
-
     /** Gets a notary identity by the given name. */
     fun getNotary(name: String): Party? {
         val notaryNode = notaryNodes.randomOrNull {

docs/source/messaging.rst

@@ -39,7 +39,6 @@ The network map currently supports:
 * Looking up node for a party
 * Suggesting a node providing a specific service, based on suitability for a contract and parties, for example suggesting
   an appropriate interest rates oracle for a interest rate swap contract. Currently no recommendation logic is in place.
-  The code simply picks the first registered node that supports the required service.
 
 Message queues
 --------------
@@ -58,6 +57,13 @@ for maintenance and other minor purposes.
    creates a bridge from this queue to the peer's ``p2p.inbound`` queue, using the network map service to lookup the
    peer's network address.
 
+:``internal.services.$identity``:
+   These are private queues the node may use to route messages to services. The queue name ends in the base 58 encoding
+   of the service's owning identity key. There is at most one queue per service identity (but note that any one service
+   may have several identities). The broker creates bridges to all nodes in the network advertising the service in
+   question. When a session is initiated with a service counterparty the handshake arrives on this queue, and once a
+   peer is picked the session continues on as normal.
+
 :``internal.networkmap``:
    This is another private queue just for the node which functions in a similar manner to the ``internal.peers.*`` queues
    except this is used to form a connection to the network map node. The node running the network map service is treated