docs: add docs/source/example-code module, tutorial on the Client RPC API

docs/source/example-code/build.gradle

@@ -0,0 +1,46 @@
+apply plugin: 'kotlin'
+apply plugin: 'application'
+
+buildscript {
+    repositories {
+        mavenCentral()
+    }
+}
+
+repositories {
+    mavenLocal()
+    mavenCentral()
+    jcenter()
+    maven {
+        url 'http://oss.sonatype.org/content/repositories/snapshots'
+    }
+    maven {
+        url 'https://dl.bintray.com/kotlin/exposed'
+    }
+}
+
+dependencies {
+    compile project(':core')
+    compile project(':client')
+
+    compile "org.graphstream:gs-core:1.3"
+    compile("org.graphstream:gs-ui:1.3") {
+        exclude group: "bouncycastle"
+    }
+}
+
+mainClassName = "com.r3corda.docs.ClientRpcTutorialKt"
+
+task getClientRpcTutorial(type: CreateStartScripts) {
+    dependsOn(classes)
+    mainClassName = "com.r3corda.docs.ClientRpcTutorialKt"
+    applicationName = "client-rpc-tutorial"
+    defaultJvmOpts = []
+    outputDir = new File(project.buildDir, 'scripts')
+    classpath = jar.outputs.files + project.configurations.runtime
+}
+
+applicationDistribution.into("bin") {
+    from(getClientRpcTutorial)
+    fileMode = 0755
+}

docs/source/example-code/src/main/kotlin/com/r3corda/docs/ClientRpcTutorial.kt

@@ -0,0 +1,73 @@
+package com.r3corda.docs
+
+import com.google.common.net.HostAndPort
+import com.r3corda.client.CordaRPCClient
+import org.graphstream.graph.Edge
+import org.graphstream.graph.Node
+import org.graphstream.graph.implementations.SingleGraph
+import java.nio.file.Paths
+import java.util.concurrent.CompletableFuture
+
+/**
+ * This is example code for the Client RPC API tutorial. The START/END comments are important and used by the documentation!
+ */
+
+// START 1
+enum class PrintOrVisualise {
+    Print,
+    Visualise
+}
+
+fun main(args: Array<String>) {
+    if (args.size < 2) {
+        throw IllegalArgumentException("Usage: <binary> <node address> [Print|Visualise]")
+    }
+    val nodeAddress = HostAndPort.fromString(args[0])
+    val printOrVisualise = PrintOrVisualise.valueOf(args[1])
+    val certificatesPath = Paths.get("build/trader-demo/buyer/certificates")
+    // END 1
+
+    // START 2
+    val client = CordaRPCClient(nodeAddress, certificatesPath)
+    client.start()
+    val proxy = client.proxy()
+    // END 2
+
+    // START 3
+    val (transactions, futureTransactions) = proxy.verifiedTransactions()
+    // END 3
+
+    // START 4
+    when (printOrVisualise) {
+        PrintOrVisualise.Print -> {
+            futureTransactions.startWith(transactions).subscribe { transaction ->
+                println("NODE ${transaction.id}")
+                transaction.tx.inputs.forEach { input ->
+                    println("EDGE ${input.txhash} ${transaction.id}")
+                }
+            }
+            CompletableFuture<Unit>().get() // block indefinitely
+        }
+    // END 4
+    // START 5
+        PrintOrVisualise.Visualise -> {
+            val graph = SingleGraph("transactions")
+            transactions.forEach { transaction ->
+                graph.addNode<Node>("${transaction.id}")
+            }
+            transactions.forEach { transaction ->
+                transaction.tx.inputs.forEach { ref ->
+                    graph.addEdge<Edge>("$ref", "${ref.txhash}", "${transaction.id}")
+                }
+            }
+            futureTransactions.subscribe { transaction ->
+                graph.addNode<Node>("${transaction.id}")
+                transaction.tx.inputs.forEach { ref ->
+                    graph.addEdge<Edge>("${ref}", "${ref.txhash}", "${transaction.id}")
+                }
+            }
+            graph.display()
+        }
+    }
+}
+// END 5