Merge pull request #1250 from corda/merges/july-10-15-51

docs/source/building-a-cordapp-index.rst

@@ -6,6 +6,7 @@ CorDapps
 
    cordapp-overview
    writing-a-cordapp
+   debugging-a-cordapp
    upgrade-notes
    upgrading-cordapps
    cordapp-build-systems

docs/source/conf.py

@@ -66,6 +66,9 @@ release = 'Master'
 # The version for use in the dropdown html.
 html_context = {'version': 'Master'}
 
+# Properties.
+kotlin_version = '1.2.51'
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #

docs/source/debugging-a-cordapp.rst

@@ -0,0 +1,73 @@
+Debugging a CorDapp
+===================
+
+.. contents::
+
+There are several ways to debug your CorDapp.
+
+Using a ``MockNetwork``
+-----------------------
+
+You can attach the `IntelliJ IDEA debugger <https://www.jetbrains.com/help/idea/debugging-code.html>`_ to a
+``MockNetwork`` to debug your CorDapp:
+
+* Define your flow tests as per :doc:`api-testing`
+
+    * In your ``MockNetwork``, ensure that ``threadPerNode`` is set to ``false``
+
+* Set your breakpoints
+* Run the flow tests using the debugger. When the tests hit a breakpoint, execution will pause
+
+Using the node driver
+---------------------
+
+You can also attach the `IntelliJ IDEA debugger <https://www.jetbrains.com/help/idea/debugging-code.html>`_ to nodes
+running via the node driver to debug your CorDapp.
+
+With the nodes in-process
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Define a network using the node driver as per :doc:`tutorial-integration-testing`
+
+    * In your ``DriverParameters``, ensure that ``startNodesInProcess`` is set to ``true``
+
+2. Run the driver using the debugger
+
+3. Set your breakpoints
+
+4. Interact with your nodes. When execution hits a breakpoint, execution will pause
+
+    * The nodes' webservers always run in a separate process, and cannot be attached to by the debugger
+
+With remote debugging
+^^^^^^^^^^^^^^^^^^^^^
+
+1. Define a network using the node driver as per :doc:`tutorial-integration-testing`
+
+    * In your ``DriverParameters``, ensure that ``startNodesInProcess`` is set to ``false`` and ``isDebug`` is set to
+      ``true``
+
+2. Run the driver. The remote debug ports for each node will be automatically generated and printed to the terminal.
+   For example:
+
+.. sourcecode:: none
+
+    [INFO ] 11:39:55,471 [driver-pool-thread-0] (DriverDSLImpl.kt:814) internal.DriverDSLImpl.startOutOfProcessNode -
+        Starting out-of-process Node PartyA, debug port is 5008, jolokia monitoring port is not enabled {}
+
+3. Attach the debugger to the node of interest on its debug port:
+
+    * In IntelliJ IDEA, create a new run/debug configuration of type ``Remote``
+    * Set the run/debug configuration's ``Port`` to the debug port
+    * Start the run/debug configuration in debug mode
+
+4. Set your breakpoints
+
+5. Interact with your node. When execution hits a breakpoint, execution will pause
+
+    * The nodes' webservers always run in a separate process, and cannot be attached to by the debugger
+
+By enabling remote debugging on a node
+--------------------------------------
+
+See :ref:`enabling-remote-debugging`.

docs/source/getting-set-up.rst

@@ -6,7 +6,7 @@ Software requirements
 Corda uses industry-standard tools:
 
 * **Oracle JDK 8 JVM** - minimum supported version **8u171**
-* **IntelliJ IDEA** - supported versions **2017.x** and **2018.x**
+* **IntelliJ IDEA** - supported versions **2017.x** and **2018.x** (with Kotlin plugin version |kotlin_version|)
 * **Git**
 
 We also use Gradle and Kotlin, but you do not need to install them. A standalone Gradle wrapper is provided, and it 
@@ -75,6 +75,7 @@ IntelliJ
 ^^^^^^^^
 1. Visit https://www.jetbrains.com/idea/download/download-thanks.html?code=IIC
 2. Download and run the executable to install IntelliJ Community Edition (use the default settings)
+3. Ensure the Kotlin plugin in Intellij is updated to version |kotlin_version|
 
 Download a sample project
 ^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -155,6 +156,7 @@ IntelliJ
 ^^^^^^^^
 1. Visit https://www.jetbrains.com/idea/download/download-thanks.html?platform=mac&code=IIC
 2. Download and run the executable to install IntelliJ Community Edition (use the default settings)
+3. Ensure the Kotlin plugin in Intellij is updated to version |kotlin_version|
 
 Download a sample project
 ^^^^^^^^^^^^^^^^^^^^^^^^^

docs/source/running-a-node.rst

@@ -64,13 +64,15 @@ The node can optionally be started with the following command-line options:
 * ``--sshd``: Enables SSHD server for node administration
 * ``--version``: Print the version and exit
 
+.. _enabling-remote-debugging:
+
 Enabling remote debugging
 ~~~~~~~~~~~~~~~~~~~~~~~~~
-To enable remote debugging of the node, run the following from the terminal window:
+To enable remote debugging of the node, run the node with the following JVM arguments:
 
 ``java -Dcapsule.jvm.args="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005" -jar corda.jar``
 
-This command line will start the debugger on port 5005 and pause the process awaiting debugger attachment.
+This will allow you to attach a debugger to your node on port 5005.
 
 Starting a node with JMX monitoring enabled
 -------------------------------------------

docs/source/shell.rst

@@ -314,24 +314,24 @@ Examples
 Starting a flow
 ~~~~~~~~~~~~~~~
 
-We would start the ``CashIssue`` flow as follows:
+We would start the ``CashIssueFlow`` flow as follows:
 
 ``flow start CashIssueFlow amount: $1000, issuerBankPartyRef: 1234, notary: "O=Controller, L=London, C=GB"``
 
 This breaks down as follows:
 
 * ``flow start`` is a shell command for starting a flow
-* ``CashIssue`` is the flow we want to start
+* ``CashIssueFlow`` is the flow we want to start
 * Each ``name: value`` pair after that is a flow constructor argument
 
-This command invokes the following ``CashIssue`` constructor:
+This command invokes the following ``CashIssueFlow`` constructor:
 
 .. container:: codeset
 
    .. sourcecode:: kotlin
 
       class CashIssueFlow(val amount: Amount<Currency>,
-                          val issueRef: OpaqueBytes,
+                          val issuerBankPartyRef: OpaqueBytes,
                           val recipient: Party,
                           val notary: Party) : AbstractCashFlow(progressTracker)
 

docs/source/tutorial-cordapp.rst

@@ -444,44 +444,24 @@ The nodes can be configured to communicate as a network even when distributed ac
    value after the nodes have been moved to their individual machines. The initial bootstrapping process requires access to the 
    nodes' databases and if two nodes share the same H2 port, the process will fail.
 
-Testing and debugging
+Testing your CorDapp
----------------------
+--------------------
 
-Testing a CorDapp
-~~~~~~~~~~~~~~~~~
 Corda provides several frameworks for writing unit and integration tests for CorDapps.
 
 Contract tests
-^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~
 You can run the CorDapp's contract tests by running the ``Run Contract Tests - Kotlin`` run configuration.
 
 Flow tests
-^^^^^^^^^^
+~~~~~~~~~~
 You can run the CorDapp's flow tests by running the ``Run Flow Tests - Kotlin`` run configuration.
 
 Integration tests
-^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~
 You can run the CorDapp's integration tests by running the ``Run Integration Tests - Kotlin`` run configuration.
 
-Debugging Corda nodes
+Debugging your CorDapp
-~~~~~~~~~~~~~~~~~~~~~
+----------------------
-Debugging is done via IntelliJ as follows:
 
-1. Start the nodes using the “Run Example CorDapp” run configuration in IntelliJ
+See :doc:`debugging-a-cordapp`.
-
-2. IntelliJ will build and run the CorDapp. The remote debug ports for each node will be automatically generated and
-   printed to the terminal. For example:
-
-.. sourcecode:: none
-
-    [INFO ] 15:27:59.533 [main] Node.logStartupInfo - Working Directory: /Users/joeldudley/cordapp-example/build/20170707142746/PartyA
-    [INFO ] 15:27:59.533 [main] Node.logStartupInfo - Debug port: dt_socket:5007
-
-3. Edit the “Debug CorDapp” run configuration with the port of the node you wish to connect to
-
-4. Run the “Debug CorDapp” run configuration
-
-5. Set your breakpoints and interact with the node you've connected to. When the node hits a breakpoint, execution will
-   pause
-
-   * The node webserver runs in a separate process, and is not attached to by the debugger