Merge "A variety of small fixes" into the 1.0 release branch (#1673)

* Minor: improve javadocs in NodeInfo

* Minor: use package descriptions in Kotlin build of api docs too, not just javadocs.

* RPC: make RPCConnection non-internal, as it's a core API. Move docs around so they're on public API not internal API.

* Add an IntelliJ scope that covers the currently supported Corda API.

This is useful when used in combination with the "Highlight public
declarations with missing KDoc" inspection.

* Ironic: upgrade the version of the Gradle plugin that checks for upgraded versions of things.

It had broken due being incompatible with the new versions of Gradle
itself.

* Docs: flesh out javadocs on ServiceHub

* Docs: add @suppress to a few things that were polluting the Dokka docs.

* Docs: mention RPC access in NodeInfo javadoc

.idea/scopes/Corda_API.xml

@@ -0,0 +1,3 @@
+<component name="DependencyValidationManager">
+  <scope name="Corda API" pattern="src[core_main]:*..*&amp;&amp;!src[core_main]:net.corda.core.internal..*||src[rpc_main]:net.corda.client.rpc.*||src[jackson_main]:net.corda.client.jackson.*" />
+</component>

build.gradle

@@ -59,7 +59,7 @@ buildscript {
         classpath "net.corda.plugins:publish-utils:$gradle_plugins_version"
         classpath "net.corda.plugins:quasar-utils:$gradle_plugins_version"
         classpath "net.corda.plugins:cordformation:$gradle_plugins_version"
-        classpath 'com.github.ben-manes:gradle-versions-plugin:0.13.0'
+        classpath 'com.github.ben-manes:gradle-versions-plugin:0.15.0'
         classpath "org.jetbrains.kotlin:kotlin-noarg:$kotlin_version"
         classpath "org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}"
         classpath "org.ajoberstar:grgit:1.1.0"

client/rpc/src/integration-test/java/net/corda/client/rpc/CordaRPCJavaClientTest.java

@@ -1,6 +1,5 @@
 package net.corda.client.rpc;
 
-import net.corda.client.rpc.internal.RPCClient;
 import net.corda.core.concurrent.CordaFuture;
 import net.corda.core.contracts.Amount;
 import net.corda.core.messaging.CordaRPCOps;
@@ -42,7 +41,7 @@ public class CordaRPCJavaClientTest extends NodeBasedTest {
 
     private StartedNode<Node> node;
     private CordaRPCClient client;
-    private RPCClient.RPCConnection<CordaRPCOps> connection = null;
+    private RPCConnection<CordaRPCOps> connection = null;
     private CordaRPCOps rpcProxy;
 
     private void login(String username, String password) {

client/rpc/src/main/kotlin/net/corda/client/rpc/CordaRPCClient.kt

@@ -11,30 +11,62 @@ import net.corda.nodeapi.config.SSLConfiguration
 import net.corda.nodeapi.internal.serialization.KRYO_RPC_CLIENT_CONTEXT
 import java.time.Duration
 
-/** @see RPCClient.RPCConnection */
-class CordaRPCConnection internal constructor(
-        connection: RPCClient.RPCConnection<CordaRPCOps>
-) : RPCClient.RPCConnection<CordaRPCOps> by connection
+/**
+ * This class is essentially just a wrapper for an RPCConnection<CordaRPCOps> and can be treated identically.
+ *
+ * @see RPCConnection
+ */
+class CordaRPCConnection internal constructor(connection: RPCConnection<CordaRPCOps>) : RPCConnection<CordaRPCOps> by connection
 
-/** @see RPCClientConfiguration */
-data class CordaRPCClientConfiguration(
-        val connectionMaxRetryInterval: Duration
-) {
+/**
+ * Can be used to configure the RPC client connection.
+ *
+ * @property connectionMaxRetryInterval How much time to wait between connection retries if the server goes down. This
+ *           time will be reached via exponential backoff.
+ */
+data class CordaRPCClientConfiguration(val connectionMaxRetryInterval: Duration) {
     internal fun toRpcClientConfiguration(): RPCClientConfiguration {
         return RPCClientConfiguration.default.copy(
                 connectionMaxRetryInterval = connectionMaxRetryInterval
         )
     }
+
     companion object {
+        /**
+         * Returns the default configuration we recommend you use.
+         */
         @JvmStatic
-        val default = CordaRPCClientConfiguration(
-                connectionMaxRetryInterval = RPCClientConfiguration.default.connectionMaxRetryInterval
-        )
+        val default = CordaRPCClientConfiguration(connectionMaxRetryInterval = RPCClientConfiguration.default.connectionMaxRetryInterval)
     }
 }
 
-/** @see RPCClient */
-class CordaRPCClient(
+/**
+ * An RPC client connects to the specified server and allows you to make calls to the server that perform various
+ * useful tasks. Please see the Client RPC section of docs.corda.net to learn more about how this API works. A brief
+ * description is provided here.
+ *
+ * Calling [start] returns an [RPCConnection] containing a proxy that lets you invoke RPCs on the server. Calls on
+ * it block, and if the server throws an exception then it will be rethrown on the client. Proxies are thread safe and
+ * may be used to invoke multiple RPCs in parallel.
+ *
+ * RPC sends and receives are logged on the net.corda.rpc logger.
+ *
+ * The [CordaRPCOps] defines what client RPCs are available. If an RPC returns an [rx.Observable] anywhere in the object
+ * graph returned then the server-side observable is transparently forwarded to the client side here.
+ * *You are expected to use it*. The server will begin sending messages immediately that will be buffered on the
+ * client, you are expected to drain by subscribing to the returned observer. You can opt-out of this by simply
+ * calling the [net.corda.client.rpc.notUsed] method on it.
+ *
+ * You don't have to explicitly close the observable if you actually subscribe to it: it will close itself and free up
+ * the server-side resources either when the client or JVM itself is shutdown, or when there are no more subscribers to
+ * it. Once all the subscribers to a returned observable are unsubscribed or the observable completes successfully or
+ * with an error, the observable is closed and you can't then re-subscribe again: you'll have to re-request a fresh
+ * observable with another RPC.
+ *
+ * @param hostAndPort The network address to connect to.
+ * @param configuration An optional configuration used to tweak client behaviour.
+ */
+class CordaRPCClient @JvmOverloads constructor(
         hostAndPort: NetworkHostAndPort,
         sslConfiguration: SSLConfiguration? = null,
         configuration: CordaRPCClientConfiguration = CordaRPCClientConfiguration.default,
@@ -55,10 +87,24 @@ class CordaRPCClient(
             KRYO_RPC_CLIENT_CONTEXT
     )
 
+    /**
+     * Logs in to the target server and returns an active connection. The returned connection is a [java.io.Closeable]
+     * and can be used with a try-with-resources statement. If you don't use that, you should use the
+     * [RPCConnection.notifyServerAndClose] or [RPCConnection.forceClose] methods to dispose of the connection object
+     * when done.
+     *
+     * @param username The username to authenticate with.
+     * @param password The password to authenticate with.
+     * @throws RPCException if the server version is too low or if the server isn't reachable within a reasonable timeout.
+     */
     fun start(username: String, password: String): CordaRPCConnection {
         return CordaRPCConnection(rpcClient.start(CordaRPCOps::class.java, username, password))
     }
 
+    /**
+     * A helper for Kotlin users that simply closes the connection after the block has executed. Be careful not to
+     * over-use this, as setting up and closing connections takes time.
+     */
     inline fun <A> use(username: String, password: String, block: (CordaRPCConnection) -> A): A {
         return start(username, password).use(block)
     }

client/rpc/src/main/kotlin/net/corda/client/rpc/RPCConnection.kt

@@ -0,0 +1,38 @@
+package net.corda.client.rpc
+
+import net.corda.core.messaging.RPCOps
+import java.io.Closeable
+
+/**
+ * Holds a [proxy] object implementing [I] that forwards requests to the RPC server. The server version can be queried
+ * via this interface.
+ *
+ * [Closeable.close] may be used to shut down the connection and release associated resources. It is an
+ * alias for [notifyServerAndClose].
+ */
+interface RPCConnection<out I : RPCOps> : Closeable {
+    /**
+     * Holds a synthetic class that automatically forwards method calls to the server, and returns the response.
+     */
+    val proxy: I
+
+    /** The RPC protocol version reported by the server. */
+    val serverProtocolVersion: Int
+
+    /**
+     * Closes this client gracefully by sending a notification to the server, so it can immediately clean up resources.
+     * If the server is not available this method may block for a short period until it's clear the server is not
+     * coming back.
+     */
+    fun notifyServerAndClose()
+
+    /**
+     * Closes this client without notifying the server.
+     *
+     * The server will eventually clear out the RPC message queue and disconnect subscribed observers,
+     * but this may take longer than desired, so to conserve resources you should normally use [notifyServerAndClose].
+     * This method is helpful when the node may be shutting down or have already shut down and you don't want to
+     * block waiting for it to come back, which typically happens in integration tests and demos rather than production.
+     */
+    fun forceClose()
+}

client/rpc/src/main/kotlin/net/corda/client/rpc/internal/RPCClient.kt

@@ -1,5 +1,6 @@
 package net.corda.client.rpc.internal
 
+import net.corda.client.rpc.RPCConnection
 import net.corda.client.rpc.RPCException
 import net.corda.core.crypto.random63BitValue
 import net.corda.core.internal.logElapsedTime
@@ -17,7 +18,6 @@ import net.corda.nodeapi.config.SSLConfiguration
 import org.apache.activemq.artemis.api.core.SimpleString
 import org.apache.activemq.artemis.api.core.TransportConfiguration
 import org.apache.activemq.artemis.api.core.client.ActiveMQClient
-import java.io.Closeable
 import java.lang.reflect.Proxy
 import java.time.Duration
 
@@ -79,12 +79,6 @@ data class RPCClientConfiguration(
     }
 }
 
-/**
- * An RPC client that may be used to create connections to an RPC server.
- *
- * @param transport The Artemis transport to use to connect to the server.
- * @param rpcConfiguration Configuration used to tweak client behaviour.
- */
 class RPCClient<I : RPCOps>(
         val transport: TransportConfiguration,
         val rpcConfiguration: RPCClientConfiguration = RPCClientConfiguration.default,
@@ -101,54 +95,6 @@ class RPCClient<I : RPCOps>(
         private val log = loggerFor<RPCClient<*>>()
     }
 
-    /**
-     * Holds a proxy object implementing [I] that forwards requests to the RPC server.
-     *
-     * [Closeable.close] may be used to shut down the connection and release associated resources.
-     */
-    interface RPCConnection<out I : RPCOps> : Closeable {
-        val proxy: I
-        /** The RPC protocol version reported by the server */
-        val serverProtocolVersion: Int
-
-        /**
-         * Closes this client without notifying the server.
-         * The server will eventually clear out the RPC message queue and disconnect subscribed observers,
-         * but this may take longer than desired, so to conserve resources you should normally use [notifyServerAndClose].
-         * This method is helpful when the node may be shutting down or
-         * have already shut down and you don't want to block waiting for it to come back.
-         */
-        fun forceClose()
-
-        /**
-         * Closes this client gracefully by sending a notification to the server, so it can immediately clean up resources.
-         * If the server is not available this method may block for a short period until it's clear the server is not coming back.
-         */
-        fun notifyServerAndClose()
-    }
-
-    /**
-     * Returns an [RPCConnection] containing a proxy that lets you invoke RPCs on the server. Calls on it block, and if
-     * the server throws an exception then it will be rethrown on the client. Proxies are thread safe and may be used to
-     * invoke multiple RPCs in parallel.
-     *
-     * RPC sends and receives are logged on the net.corda.rpc logger.
-     *
-     * The [RPCOps] defines what client RPCs are available. If an RPC returns an [Observable] anywhere in the object
-     * graph returned then the server-side observable is transparently forwarded to the client side here.
-     * *You are expected to use it*. The server will begin sending messages immediately that will be buffered on the
-     * client, you are expected to drain by subscribing to the returned observer. You can opt-out of this by simply
-     * calling the [net.corda.client.rpc.notUsed] method on it. You don't have to explicitly close the observable if you actually
-     * subscribe to it: it will close itself and free up the server-side resources either when the client or JVM itself
-     * is shutdown, or when there are no more subscribers to it. Once all the subscribers to a returned observable are
-     * unsubscribed or the observable completes successfully or with an error, the observable is closed and you can't
-     * then re-subscribe again: you'll have to re-request a fresh observable with another RPC.
-     *
-     * @param rpcOpsClass The [Class] of the RPC interface.
-     * @param username The username to authenticate with.
-     * @param password The password to authenticate with.
-     * @throws RPCException if the server version is too low or if the server isn't reachable within the given time.
-     */
     fun start(
             rpcOpsClass: Class<I>,
             username: String,

core/src/main/kotlin/net/corda/core/internal/InternalUtils.kt

@@ -235,11 +235,12 @@ fun <T> Class<T>.castIfPossible(obj: Any): T? = if (isInstance(obj)) cast(obj) e
 fun <T> Class<*>.staticField(name: String): DeclaredField<T> = DeclaredField(this, name, null)
 /** Returns a [DeclaredField] wrapper around the declared (possibly non-public) static field of the receiver [KClass]. */
 fun <T> KClass<*>.staticField(name: String): DeclaredField<T> = DeclaredField(java, name, null)
-/** Returns a [DeclaredField] wrapper around the declared (possibly non-public) instance field of the receiver object. */
+/** @suppress Returns a [DeclaredField] wrapper around the declared (possibly non-public) instance field of the receiver object. */
 fun <T> Any.declaredField(name: String): DeclaredField<T> = DeclaredField(javaClass, name, this)
 /**
  * Returns a [DeclaredField] wrapper around the (possibly non-public) instance field of the receiver object, but declared
  * in its superclass [clazz].
+ * @suppress
  */
 fun <T> Any.declaredField(clazz: KClass<*>, name: String): DeclaredField<T> = DeclaredField(clazz.java, name, this)
 

core/src/main/kotlin/net/corda/core/node/NodeInfo.kt

@@ -6,21 +6,35 @@ import net.corda.core.serialization.CordaSerializable
 import net.corda.core.utilities.NetworkHostAndPort
 
 /**
- * Info about a network node that acts on behalf of some form of contract party.
- * @param legalIdentitiesAndCerts is a non-empty list, where the first identity is assumed to be the default identity of the node.
+ * Information about a network node that acts on behalf of some party. NodeInfos can be found via the network map
+ * cache, accessible from a [net.corda.core.node.services.NetworkMapCache]. They are also available via RPC
+ * using the [net.corda.core.messaging.CordaRPCOps.networkMapSnapshot] method.
+ *
+ * @property addresses An ordered list of IP addresses/hostnames where the node can be contacted.
+ * @property legalIdentitiesAndCerts A non-empty list, where the first identity is assumed to be the default identity of the node.
+ * @property platformVersion An integer representing the set of protocol features the node supports. See the docsite
+ *           for information on how the platform is versioned.
+ * @property serial An arbitrary number incremented each time the NodeInfo is changed. This is analogous to the same
+ *           concept in DNS.
  */
-// TODO We currently don't support multi-IP/multi-identity nodes, we only left slots in the data structures.
 @CordaSerializable
 data class NodeInfo(val addresses: List<NetworkHostAndPort>,
                     val legalIdentitiesAndCerts: List<PartyAndCertificate>,
                     val platformVersion: Int,
                     val serial: Long
 ) {
+    // TODO We currently don't support multi-IP/multi-identity nodes, we only left slots in the data structures.
     init {
         require(legalIdentitiesAndCerts.isNotEmpty()) { "Node should have at least one legal identity" }
     }
 
     @Transient private var _legalIdentities: List<Party>? = null
+
+    /**
+     * An ordered list of legal identities supported by this node. The node will always have at least one, so if you
+     * are porting code from earlier versions of Corda that expected a single party per node, just use the first item
+     * in the returned list.
+     */
     val legalIdentities: List<Party> get() {
         return _legalIdentities ?: legalIdentitiesAndCerts.map { it.party }.also { _legalIdentities = it }
     }

core/src/main/kotlin/net/corda/core/node/ServiceHub.kt

@@ -6,6 +6,7 @@ import net.corda.core.crypto.Crypto
 import net.corda.core.crypto.SignableData
 import net.corda.core.crypto.SignatureMetadata
 import net.corda.core.crypto.TransactionSignature
+import net.corda.core.flows.ContractUpgradeFlow
 import net.corda.core.identity.AbstractParty
 import net.corda.core.identity.AnonymousParty
 import net.corda.core.identity.Party
@@ -22,10 +23,13 @@ import java.time.Clock
 /**
  * Subset of node services that are used for loading transactions from the wire into fully resolved, looked up
  * forms ready for verification.
- *
- * @see ServiceHub
  */
 interface ServicesForResolution {
+    /**
+     * An identity service maintains a directory of parties by their associated distinguished name/public keys and thus
+     * supports lookup of a party given its key, or name. The service also manages the certificates linking confidential
+     * identities back to the well known identity (i.e. the identity in the network map) of a party.
+     */
     val identityService: IdentityService
 
     /** Provides access to storage of arbitrary JAR files (which may contain only data, no code). */
@@ -44,17 +48,42 @@ interface ServicesForResolution {
 }
 
 /**
- * A service hub simply vends references to the other services a node has. Some of those services may be missing or
- * mocked out. This class is useful to pass to chunks of pluggable code that might have need of many different kinds of
- * functionality and you don't want to hard-code which types in the interface.
+ * A service hub is the starting point for most operations you can do inside the node. You are provided with one
+ * when a class annotated with [CordaService] is constructed, and you have access to one inside flows. Most RPCs
+ * simply forward to the services found here after some access checking.
  *
- * Any services exposed to flows (public view) need to implement [SerializeAsToken] or similar to avoid their internal
- * state from being serialized in checkpoints.
+ * The APIs are organised roughly by category, with a few very important top level APIs available on the ServiceHub
+ * itself. Inside a flow, it's safe to keep a reference to services found here on the stack: checkpointing will do the
+ * right thing (it won't try to serialise the internals of the service).
+ *
+ * In unit test environments, some of those services may be missing or mocked out.
  */
 interface ServiceHub : ServicesForResolution {
+    // NOTE: Any services exposed to flows (public view) need to implement [SerializeAsToken] or similar to avoid
+    // their internal state from being serialized in checkpoints.
+
+    /**
+     * The vault service lets you observe, soft lock and add notes to states that involve you or are relevant to your
+     * node in some way.
+     */
     val vaultService: VaultService
+    /** The vault query service lets you select and track states that correspond to various criteria. */
     val vaultQueryService: VaultQueryService
+    /**
+     * The key management service is responsible for storing and using private keys to sign things. An
+     * implementation of this may, for example, call out to a hardware security module that enforces various
+     * auditing and frequency-of-use requirements.
+     *
+     * You don't normally need to use this directly. If you have a [TransactionBuilder] and wish to sign it to
+     * get a [SignedTransaction], look at [signInitialTransaction].
+     */
     val keyManagementService: KeyManagementService
+    /**
+     * The [ContractUpgradeService] is responsible for securely upgrading contract state objects according to
+     * a specified and mutually agreed (amongst participants) contract version.
+     *
+     * @see ContractUpgradeFlow to understand the workflow associated with contract upgrades.
+     */
     val contractUpgradeService: ContractUpgradeService
 
     /**
@@ -64,9 +93,27 @@ interface ServiceHub : ServicesForResolution {
      */
     val validatedTransactions: TransactionStorage
 
+    /**
+     * A network map contains lists of nodes on the network along with information about their identity keys, services
+     * they provide and host names or IP addresses where they can be connected to. The cache wraps around a map fetched
+     * from an authoritative service, and adds easy lookup of the data stored within it. Generally it would be initialised
+     * with a specified network map service, which it fetches data from and then subscribes to updates of.
+     */
     val networkMapCache: NetworkMapCache
+
+    /**
+     * INTERNAL. DO NOT USE.
+     * @suppress
+     */
     val transactionVerifierService: TransactionVerifierService
+
+    /**
+     * A [Clock] representing the node's current time. This should be used in preference to directly accessing the
+     * clock so the current time can be controlled during unit testing.
+     */
     val clock: Clock
+
+    /** The [NodeInfo] object corresponding to our own entry in the network map. */
     val myInfo: NodeInfo
 
     /**
@@ -268,9 +315,12 @@ interface ServiceHub : ServicesForResolution {
     /**
      * Exposes a JDBC connection (session) object using the currently configured database.
      * Applications can use this to execute arbitrary SQL queries (native, direct, prepared, callable)
-     * against its Node database tables (including custom contract tables defined by extending [Queryable]).
+     * against its Node database tables (including custom contract tables defined by extending
+     * [net.corda.core.schemas.QueryableState]).
+     *
      * When used within a flow, this session automatically forms part of the enclosing flow transaction boundary,
      * and thus queryable data will include everything committed as of the last checkpoint.
+     *
      * @throws IllegalStateException if called outside of a transaction.
      * @return A new [Connection]
      */

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

@@ -5,6 +5,7 @@ import net.corda.core.transactions.LedgerTransaction
 
 /**
  * Provides verification service. The implementation may be a simple in-memory verify() call or perhaps an IPC/RPC.
+ * @suppress
  */
 interface TransactionVerifierService {
     /**

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

@@ -7,8 +7,10 @@ import net.corda.core.node.services.vault.PageSpecification
 import net.corda.core.node.services.vault.QueryCriteria
 import net.corda.core.node.services.vault.Sort
 
+/**
+ * The vault query service lets you select and track states that correspond to various criteria.
+ */
 interface VaultQueryService {
-
     // DOCSTART VaultQueryAPI
     /**
      * Generic vault query function which takes a [QueryCriteria] object to define filters,

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

@@ -149,7 +149,6 @@ class Vault<out T : ContractState>(val states: Iterable<StateAndRef<T>>) {
  * Note that transactions we've seen are held by the storage service, not the vault.
  */
 interface VaultService {
-
     /**
      * Prefer the use of [updates] unless you know why you want to use this instead.
      *

docs/build.gradle

@@ -10,6 +10,7 @@ dokka {
     outputDirectory = file("${rootProject.rootDir}/docs/build/html/api/kotlin")
     processConfigurations = ['compile']
     sourceDirs = files('../core/src/main/kotlin', '../client/jfx/src/main/kotlin', '../client/mock/src/main/kotlin', '../client/rpc/src/main/kotlin', '../node-api/src/main/kotlin', '../finance/src/main/kotlin', '../client/jackson/src/main/kotlin', '../testing/node-driver/src/main/kotlin', '../testing/test-utils/src/main/kotlin')
+    includes = ['packages.md']
     jdkVersion = 8
 
     externalDocumentationLink {