Release notes for M8

Regenerate docs

docs/build/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 1768caf6e5e802b716b72241d5bd1c76
+config: f31fa13a644d2330bb46729777cbb8f7
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/build/html/CLI-vs-IDE.html

@@ -34,9 +34,6 @@
 
 
 
-        <link rel="index" title="Index"
-              href="genindex.html"/>
-        <link rel="search" title="Search" href="search.html"/>
     <link rel="top" title="R3 Corda latest documentation" href="index.html"/>
         <link rel="next" title="Overview" href="key-concepts.html"/>
         <link rel="prev" title="Running the demos" href="running-the-demos.html"/> 

docs/build/html/_sources/clientrpc.txt

@@ -46,6 +46,14 @@ through to the server where the corresponding server-side observables are also u
    a warning printed to the logs and the proxy will be closed for you. But don't rely on this, as garbage
    collection is non-deterministic.
 
+Futures
+-------
+
+A method can also return a ``ListenableFuture`` in its object graph and it will be treated in a similar manner to
+observables, including needing to mark the RPC with the ``@RPCReturnsObservables`` annotation. Unlike for an observable,
+once the single value (or an exception) has been received all server-side resources will be released automatically. Calling
+the ``cancel`` method on the future will unsubscribe it from any future value and release any resources.
+
 Versioning
 ----------
 

docs/build/html/_sources/corda-configuration-file.txt

@@ -82,13 +82,16 @@ path to the node's base directory.
 
 :messagingServerAddress: The address of the ArtemisMQ broker instance. If not provided the node will run one locally.
 
-:webAddress: The host and port on which the node is available for web operations.
+:webAddress: The host and port on which the bundled webserver will listen if it is started.
 
     .. note:: If HTTPS is enabled then the browser security checks will require that the accessing url host name is one
         of either the machine name, fully qualified machine name, or server IP address to line up with the Subject Alternative
         Names contained within the development certificates. This is addition to requiring the ``/config/dev/corda_dev_ca.cer``
         root certificate be installed as a Trusted CA.
 
+    .. note:: The driver will not automatically create a webserver instance, but the Cordformation will. If this field
+              is present the web server will start.
+
 :extraAdvertisedServiceIds: A list of ServiceType id strings to be advertised to the NetworkMapService and thus be available
     when other nodes query the NetworkMapCache for supporting nodes. This can also include plugin services loaded from .jar
     files in the plugins folder. Optionally, a custom advertised service name can be provided by appending it to the service

docs/build/html/_sources/corda-plugins.txt

@@ -34,21 +34,16 @@ of the node internal subsystems.
 extensions to be created, or registered at startup. In particular: 
 
     a. The ``webApis`` property is a list of JAX-RS annotated REST access 
-    classes. These classes will be constructed by the embedded web server 
-    and must have a single argument constructor taking a ``ServiceHub`` 
-    reference. This reference provides access to functions such as querying 
-    for states through the ``VaultService`` interface, or access to the 
-    ``NetworkMapCache`` to identify services on remote nodes. The framework will 
-    provide a database transaction in scope during the lifetime of the web 
-    call, so full access to database data is valid. Unlike 
-    ``servicePlugins`` the ``webApis`` cannot register new protocols, or 
-    initiate threads. (N.B. The intent is to move the Web support into a 
-    separate helper process using the RPC mechanism to control access.) 
+    classes. These classes will be constructed by the bundled web server
+    and must have a single argument constructor taking a ``CordaRPCOps``
+    reference. This will allow it to communicate with the node process
+    via the RPC interface. These web APIs will not be available if the
+    bundled web server is not started.
 
     b. The ``staticServeDirs`` property maps static web content to virtual 
     paths and allows simple web demos to be distributed within the CorDapp 
-    jars. (N.B. The intent is to move the Web support into a separate helper 
-    process using the RPC mechanism to control access.) 
+    jars. These static serving directories will not be available if the
+    bundled web server is not started.
 
     c. The ``requiredFlows`` property is used to declare new protocols in 
     the plugin jar. Specifically the property must return a map with a key 

docs/build/html/_sources/creating-a-cordapp.txt

@@ -12,10 +12,10 @@ App plugins
 To create an app plugin you must you must extend from `CordaPluginRegistry`_. The JavaDoc contains
 specific details of the implementation, but you can extend the server in the following ways:
 
-1. Required flows: Specify which flows will be whitelisted for use in your web APIs.
+1. Required flows: Specify which flows will be whitelisted for use in your RPC calls.
 2. Service plugins: Register your services (see below).
-3. Web APIs: You may register your own endpoints under /api/ of the built-in web server.
-4. Static web endpoints: You may register your own static serving directories for serving web content.
+3. Web APIs: You may register your own endpoints under /api/ of the bundled web server.
+4. Static web endpoints: You may register your own static serving directories for serving web content from the web server.
 5. Registering your additional classes used in RPC.
 
 Services

docs/build/html/_sources/flow-state-machines.txt

@@ -111,8 +111,8 @@ each side.
 
       object TwoPartyTradeFlow {
 
-          class UnacceptablePriceException(val givenPrice: Amount<Currency>) : Exception("Unacceptable price: $givenPrice")
-          class AssetMismatchException(val expectedTypeName: String, val typeName: String) : Exception() {
+          class UnacceptablePriceException(val givenPrice: Amount<Currency>) : FlowException("Unacceptable price: $givenPrice")
+          class AssetMismatchException(val expectedTypeName: String, val typeName: String) : FlowException() {
               override fun toString() = "The submitted asset didn't match the expected type: $expectedTypeName vs $typeName"
           }
 
@@ -241,17 +241,11 @@ Let's implement the ``Seller.call`` method. This will be run when the flow is in
 
 .. container:: codeset
 
-   .. sourcecode:: kotlin
-
-      @Suspendable
-      override fun call(): SignedTransaction {
-          val partialTX: SignedTransaction = receiveAndCheckProposedTransaction()
-          val ourSignature: DigitalSignature.WithKey = computeOurSignature(partialTX)
-          val allPartySignedTx = partialTX + ourSignature
-          val notarySignature = getNotarySignature(allPartySignedTx)
-          val result: SignedTransaction = sendSignatures(allPartySignedTx, ourSignature, notarySignature)
-          return result
-      }
+    .. literalinclude:: ../../finance/src/main/kotlin/net/corda/flows/TwoPartyTradeFlow.kt
+            :language: kotlin
+            :start-after: DOCSTART 4
+            :end-before: DOCEND 4
+            :dedent: 4
 
 Here we see the outline of the procedure. We receive a proposed trade transaction from the buyer and check that it's
 valid. The buyer has already attached their signature before sending it. Then we calculate and attach our own signature so that the transaction is
@@ -265,31 +259,11 @@ Let's fill out the ``receiveAndCheckProposedTransaction()`` method.
 
 .. container:: codeset
 
-   .. sourcecode:: kotlin
-
-      @Suspendable
-      private fun receiveAndCheckProposedTransaction(): SignedTransaction {
-          // Make the first message we'll send to kick off the flow.
-          val myPublicKey = myKeyPair.public.composite
-          val hello = SellerTradeInfo(assetToSell, price, myPublicKey)
-
-          val maybeSTX = sendAndReceive<SignedTransaction>(otherSide, hello)
-
-          maybeSTX.unwrap {
-              // Check that the tx proposed by the buyer is valid.
-              val wtx: WireTransaction = it.verifySignatures(myPublicKey, notaryNode.notaryIdentity.owningKey)
-              logger.trace { "Received partially signed transaction: ${it.id}" }
-
-              // Download and check all the things that this transaction depends on and verify it is contract-valid,
-              // even though it is missing signatures.
-              subFlow(ResolveTransactionsFlow(wtx, otherParty))
-
-              if (wtx.outputs.map { it.data }.sumCashBy(myPublicKey).withoutIssuer() != price)
-                  throw IllegalArgumentException("Transaction is not sending us the right amount of cash")
-
-              return it
-          }
-      }
+    .. literalinclude:: ../../finance/src/main/kotlin/net/corda/flows/TwoPartyTradeFlow.kt
+            :language: kotlin
+            :start-after: DOCSTART 5
+            :end-before: DOCEND 5
+            :dedent: 4
 
 Let's break this down. We fill out the initial flow message with the trade info, and then call ``sendAndReceive``.
 This function takes a few arguments:
@@ -333,20 +307,38 @@ Our "scrubbing" has three parts:
 2. We resolve the transaction, which we will cover below.
 3. We verify that the transaction is paying us the demanded price.
 
+Exception handling
+------------------
+
+Flows can throw exceptions to prematurely terminate their execution. The flow framework gives special treatment to
+``FlowException`` and its subtypes. These exceptions are treated as error responses of the flow and are propagated
+to all counterparties it is communicating with. The receiving flows will throw the same exception the next time they do
+a ``receive`` or ``sendAndReceive`` and thus end the flow session. If the receiver was invoked via ``subFlow`` (details below)
+then the exception can  be caught there enabling re-invocation of the sub-flow.
+
+If the exception thrown by the erroring flow is not a ``FlowException`` it will still terminate but will not propagate to
+the other counterparties. Instead they will be informed the flow has terminated and will themselves be terminated with a
+generic exception.
+
+.. note:: A future version will extend this to give the node administrator more control on what to do with such erroring
+    flows.
+
+Throwing a ``FlowException`` enables a flow to reject a piece of data it has received back to the sender. This is typically
+done in the ``unwrap`` method of the received ``UntrustworthyData``. In the above example the seller checks the price
+and throws ``FlowException`` if it's invalid. It's then up to the buyer to either try again with a better price or give up.
+
 Sub-flows
 ---------
 
 Flows can be composed via nesting. Invoking a sub-flow looks similar to an ordinary function call:
 
 .. container:: codeset
 
-   .. sourcecode:: kotlin
-
-      @Suspendable
-      private fun getNotarySignature(stx: SignedTransaction): DigitalSignature.LegallyIdentifiable {
-          progressTracker.currentStep = NOTARY
-          return subFlow(NotaryFlow.Client(stx))
-      }
+    .. literalinclude:: ../../finance/src/main/kotlin/net/corda/flows/TwoPartyTradeFlow.kt
+            :language: kotlin
+            :start-after: DOCSTART 6
+            :end-before: DOCEND 6
+            :dedent: 4
 
 In this code snippet we are using the ``NotaryFlow.Client`` to request notarisation of the transaction.
 We simply create the flow object via its constructor, and then pass it to the ``subFlow`` method which
@@ -372,18 +364,11 @@ Here's the rest of the code:
 
 .. container:: codeset
 
-   .. sourcecode:: kotlin
-
-      open fun calculateOurSignature(partialTX: SignedTransaction) = myKeyPair.signWithECDSA(partialTX.id)
-
-      @Suspendable
-      private fun sendSignatures(allPartySignedTX: SignedTransaction, ourSignature: DigitalSignature.WithKey,
-                                 notarySignature: DigitalSignature.WithKey): SignedTransaction {
-          val fullySigned = allPartySignedTX + notarySignature
-          logger.trace { "Built finished transaction, sending back to secondary!" }
-          send(otherSide, SignaturesFromSeller(ourSignature, notarySignature))
-          return fullySigned
-      }
+    .. literalinclude:: ../../finance/src/main/kotlin/net/corda/flows/TwoPartyTradeFlow.kt
+            :language: kotlin
+            :start-after: DOCSTART 7
+            :end-before: DOCEND 7
+            :dedent: 4
 
 It's all pretty straightforward from now on. Here ``id`` is the secure hash representing the serialised
 transaction, and we just use our private key to calculate a signature over it. As a reminder, in Corda signatures do
@@ -413,7 +398,7 @@ OK, let's do the same for the buyer side:
          :language: kotlin
          :start-after: DOCSTART 1
          :end-before: DOCEND 1
-         :dedent: 8
+         :dedent: 4
 
 This code is longer but no more complicated. Here are some things to pay attention to:
 
@@ -453,7 +438,6 @@ A flow might declare some steps with code inside the flow class like this:
             :end-before: DOCSTART 1
             :dedent: 4
 
-
     .. sourcecode:: java
 
        private final ProgressTracker progressTracker = new ProgressTracker(
@@ -547,7 +531,7 @@ The flow framework is a key part of the platform and will be extended in major w
 the features we have planned:
 
 * Identity based addressing
-* Exception propagation and management, with a "flow hospital" tool to manually provide solutions to unavoidable
+* Exception management, with a "flow hospital" tool to manually provide solutions to unavoidable
   problems (e.g. the other side doesn't know the trade)
 * Being able to interact with internal apps and tools via RPC
 * Being able to interact with people, either via some sort of external ticketing system, or email, or a custom UI.

docs/build/html/_sources/index.txt

@@ -1,34 +1,31 @@
 Welcome to the Corda documentation!
 ===================================
 
-.. warning:: This build of the docs is from the "|version|" branch, not a milestone release. It may not reflect the
-   current state of the code. `Read the docs for milestone release M7 <https://docs.corda.net/releases/release-M7.0/>`_.
-
-`Corda <https://www.corda.net/>`_ is an open-source distributed ledger platform. The latest *milestone* (i.e. stable) 
-release is M7. The codebase is on `GitHub <https://github.com/corda>`_, and our community can be found on 
+`Corda <https://www.corda.net/>`_ is an open-source distributed ledger platform. The latest *milestone* (i.e. stable)
+release is M8. The codebase is on `GitHub <https://github.com/corda>`_, and our community can be found on
 `Slack <https://slack.corda.net/>`_ and in our `forum <https://discourse.corda.net/>`_.
 
-If you're new to Corda, you should start by learning about its motivating vision and architecture. A good introduction 
-is the `Introduction to Corda webinar <https://vimeo.com/192757743/c2ec39c1e1>`_ and the `Introductory white paper`_. As 
-they become more familiar with Corda, readers with a technical background will also want to dive into the `Technical white paper`_, 
+If you're new to Corda, you should start by learning about its motivating vision and architecture. A good introduction
+is the `Introduction to Corda webinar <https://vimeo.com/192757743/c2ec39c1e1>`_ and the `Introductory white paper`_. As
+they become more familiar with Corda, readers with a technical background will also want to dive into the `Technical white paper`_,
 which describes the platform's envisioned end-state.
 
-Corda is designed so that developers can easily extend its functionality by writing CorDapps 
-(**Cor**\ da **D**\ istributed **App**\ lication\ **s**\ ). Some example CorDapps are available in the Corda repo's 
-`samples <https://github.com/corda/corda/tree/master/samples>`_ directory. To run these yourself, make 
-sure you follow the instructions in :doc:`getting-set-up`, then go to 
+Corda is designed so that developers can easily extend its functionality by writing CorDapps
+(**Cor**\ da **D**\ istributed **App**\ lication\ **s**\ ). Some example CorDapps are available in the Corda repo's
+`samples <https://github.com/corda/corda/tree/master/samples>`_ directory. To run these yourself, make
+sure you follow the instructions in :doc:`getting-set-up`, then go to
 :doc:`running-the-demos`.
 
-If, after running the demos, you're interested in writing your own CorDapps, a template CorDapp is available on 
-`Github <https://github.com/corda/cordapp-template>`_. To get it running, follow the instructions in the 
-`readme <https://github.com/corda/cordapp-template/blob/master/README.md>`_, or watch the 
+If, after running the demos, you're interested in writing your own CorDapps, a template CorDapp is available on
+`Github <https://github.com/corda/cordapp-template>`_. To get it running, follow the instructions in the
+`readme <https://github.com/corda/cordapp-template/blob/master/README.md>`_, or watch the
 `Corda Developers Tutorial <https://vimeo.com/192797322/aab499b152>`_.
 
-From there, you'll be in a position to start extending the example CorDapp yourself (e.g. by writing new states, contracts, 
-and/or flows). For this, you'll want to refer to this docsite, and to the `tutorials <https://docs.corda.net/tutorial-contract.html>`_ 
+From there, you'll be in a position to start extending the example CorDapp yourself (e.g. by writing new states, contracts,
+and/or flows). For this, you'll want to refer to this docsite, and to the `tutorials <https://docs.corda.net/tutorial-contract.html>`_
 in particular. If you get stuck, get in touch on `Slack <https://slack.corda.net/>`_ or the `forum <https://discourse.corda.net/>`_.
 
-Once you're familiar with Corda and CorDapp development, we'd encourage you to get involved in the development of the 
+Once you're familiar with Corda and CorDapp development, we'd encourage you to get involved in the development of the
 platform itself. Find out more about `contributing to Corda <https://github.com/corda/corda/wiki/Corda's-Open-Source-Approach>`_.
 
 .. _`Introductory white paper`: _static/corda-introductory-whitepaper.pdf

docs/build/html/_sources/node-administration.txt

@@ -1,8 +1,9 @@
 Node administration
 ===================
 
-When a node is running, it exposes an embedded database server, an embedded web server that lets you monitor it,
-you can upload and download attachments, access a REST API and so on.
+When a node is running, it exposes an RPC interface that lets you monitor it,
+you can upload and download attachments, access a REST API and so on. A bundled
+Jetty web server exposes the same interface over HTTP.
 
 Logging
 -------

docs/build/html/_sources/node-services.txt

@@ -346,3 +346,11 @@ external legacy systems by insertion of unpacked data into existing
 tables. To enable these features the contract state must implement the 
 ``QueryableState`` interface to define the mappings. 
 
+Node Web Server
+---------------
+
+A web server comes bundled with the node by default, but is not started
+automatically. This web server exposes both RPC backed API calls and
+static content serving. The web server is not automatically started,
+you must explicitly start it in the node driver or define a web port
+in your `Cordformation`_ configuration.