ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2024-12-19 04:57:58 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge pull request #4705 from corda/cais-docs-cordapp-tutorial

Browse Source 
Updating the docs for tutorial cordapp to reflect Spring Boot changes
This commit is contained in:
Cais Manai 2019-02-06 11:13:24 +00:00 committed by GitHub
commit 0e770bbb85
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 73 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

139
docs/source/tutorial-cordapp.rst
View File

@ -59,6 +59,22 @@ The example CorDapp has the following structure:
.. sourcecode:: none .. sourcecode:: none
. .
├── clients
│   └── src
│   └── main
│   └── kotlin
│   └── com.example.server
│   ├── MainController.kt
│   ├── NodeRPCConnection.kt
│   └── Server.kt
│   ├── resources
│   ├── public
│   ├── js
│   └── angular-module.js
│   └── index.html
│   └── application.properties
│ └── build.gradle
│  
├── config ├── config
│   ├── dev │   ├── dev
│   │   └── log4j2.xml │   │   └── log4j2.xml
@ -77,32 +93,26 @@ The example CorDapp has the following structure:
│   │   └── example │   │   └── example
│   │   └── DriverBasedTests.java │   │   └── DriverBasedTests.java
│   ├── main │   ├── main
│   │   ├── java │   │   ── java
│   │   │   └── com │   │      └── com
│   │   │   └── example │   │      └── example
│   │   │   ├── api │   │      ├── api
│   │   │   │   └── ExampleApi.java │   │      │   └── ExampleApi.java
│   │   │   ├── client │   │      ├── client
│   │   │   │   └── ExampleClientRPC.java │   │      │   └── ExampleClientRPC.java
│   │   │   ├── contract │   │      ├── contract
│   │   │   │   └── IOUContract.java │   │      │   └── IOUContract.java
│   │   │   ├── flow │   │      ├── flow
│   │   │   │   └── ExampleFlow.java │   │      │   └── ExampleFlow.java
│   │   │   ├── plugin │   │      ├── plugin
│   │   │   │   └── ExamplePlugin.java │   │      │   └── ExamplePlugin.java
│   │   │   ├── schema │   │      ├── schema
│   │   │   │   ├── IOUSchema.java │   │      │   ├── IOUSchema.java
│   │   │   │   └── IOUSchemaV1.java │   │      │   └── IOUSchemaV1.java
│   │   │   └── state │   │      └── state
│   │   │   └── IOUState.java │   │      └── IOUState.java
│   │   └── resources │   │ 
│   │   ├── META-INF │   │  
│   │   │   └── services
│   │   │   └── net.corda.webserver.services.WebServerPluginRegistry
│   │   └── exampleWeb
│   │   ├── index.html
│   │   └── js
│   │   └── angular-module.js
│   └── test │   └── test
│   └── java │   └── java
│   └── com │   └── com
@ -134,11 +144,10 @@ The key files and directories are as follows:
* **gradle** contains the gradle wrapper, which allows the use of Gradle without installing it yourself and worrying * **gradle** contains the gradle wrapper, which allows the use of Gradle without installing it yourself and worrying
about which version is required about which version is required
* **lib** contains the Quasar jar which rewrites our CorDapp's flows to be checkpointable * **lib** contains the Quasar jar which rewrites our CorDapp's flows to be checkpointable
* **clients** contains the source code for spring boot integration
* **java-source** contains the source code for the example CorDapp written in Java * **java-source** contains the source code for the example CorDapp written in Java
* **java-source/src/main/java** contains the source code for the example CorDapp * **java-source/src/main/java** contains the source code for the example CorDapp
* **java-source/src/main/resources** contains the certificate store, some static web content to be served by the
nodes and the WebServerPluginRegistry file
* **java-source/src/test/java** contains unit tests for the contracts and flows, and the driver to run the nodes * **java-source/src/test/java** contains unit tests for the contracts and flows, and the driver to run the nodes
via IntelliJ via IntelliJ
@ -185,9 +194,9 @@ Building the example CorDapp
├── additional-node-infos // ├── additional-node-infos //
├── certificates ├── certificates
├── corda.jar // The Corda node runtime ├── corda.jar // The Corda node runtime
├── corda-webserver.jar // The development node webserver runtime
├── cordapps // The node's CorDapps ├── cordapps // The node's CorDapps
│   ├── corda-finance-3.2-corda.jar │   ├── corda-finance-contracts-4.0-corda.jar
│   ├── corda-finance-workflows-4.0-corda.jar
│   └── cordapp-example-0.1.jar │   └── cordapp-example-0.1.jar
├── drivers ├── drivers
├── logs ├── logs
@ -202,11 +211,15 @@ Building the example CorDapp
Running the example CorDapp Running the example CorDapp
^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^
Start the nodes by running the following command from the root of the ``cordapp-example`` folder: Start the nodes and Spring Boot servers by running the following command from the root of the ``cordapp-example`` folder:
* Unix/Mac OSX: ``kotlin-source/build/nodes/runnodes`` * Unix/Mac OSX: ``kotlin-source/build/nodes/runnodes``
* Windows: ``call kotlin-source\build\nodes\runnodes.bat`` * Windows: ``call kotlin-source\build\nodes\runnodes.bat``
Each Spring Boot server needs to be started in it's own terminal, replace X with A, B and C
* Unix/Mac OSX: ``./gradlew runPartyXServer``
* Windows: ``gradlew.bat runPartyXServer``
.. warning:: On Unix/Mac OSX, do not click/change focus until all seven additional terminal windows have opened, or some .. warning:: On Unix/Mac OSX, do not click/change focus until all seven additional terminal windows have opened, or some
nodes may fail to start. nodes may fail to start.
@ -234,19 +247,11 @@ For each node, the ``runnodes`` script creates a node tab/window:
Welcome to the Corda interactive shell. Welcome to the Corda interactive shell.
Useful commands include 'help' to see what is available, and 'bye' to shut down the node. Useful commands include 'help' to see what is available, and 'bye' to shut down the node.
Fri Mar 02 17:34:02 GMT 2018>>> Fri Mar 02 17:34:02 GMT 2018>>>
For every node except the notary, the script also creates a webserver terminal tab/window:
.. sourcecode:: none
Logs can be found in /Users/username/Desktop/cordapp-example/kotlin-source/build/nodes/PartyA/logs/web
Starting as webserver: localhost:10007
Webserver started up in 42.02 sec
It usually takes around 60 seconds for the nodes to finish starting up. To ensure that all the nodes are running, you It usually takes around 60 seconds for the nodes to finish starting up. To ensure that all the nodes are running, you
can query the 'status' end-point located at ``http://localhost:[port]/api/status`` (e.g. can query the 'status' end-point located at ``http://localhost:[port]/api/status`` (e.g.
``http://localhost:10007/api/status`` for ``PartyA``). ``http://localhost:50005/api/status`` for ``PartyA``).
Running the example CorDapp from IntelliJ Running the example CorDapp from IntelliJ
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -265,44 +270,44 @@ Interacting with the example CorDapp
Via HTTP Via HTTP
~~~~~~~~ ~~~~~~~~
The nodes' webservers run locally on the following ports: The Spring Boot servers run locally on the following ports:
* PartyA: ``localhost:10007`` * PartyA: ``localhost:50005``
* PartyB: ``localhost:10011`` * PartyB: ``localhost:50006``
* PartyC: ``localhost:10015`` * PartyC: ``localhost:50007``
These ports are defined in each node's node.conf file under ``kotlin-source/build/nodes/NodeX/node.conf``. These ports are defined in ``clients/build.gradle``.
Each node webserver exposes the following endpoints: Each Spring Boot server exposes the following endpoints:
* ``/api/example/me`` * ``/api/example/me``
* ``/api/example/peers`` * ``/api/example/peers``
* ``/api/example/ious`` * ``/api/example/ious``
* ``/api/example/create-iou`` with parameters ``iouValue`` and ``partyName`` which is CN name of a node * ``/api/example/create-iou`` with parameters ``iouValue`` and ``partyName`` which is CN name of a node
There is also a web front-end served from ``/web/example``. There is also a web front-end served from the home web page e.g. ``localhost:50005``.
.. warning:: The content in ``/web/example`` is only available for demonstration purposes and does not implement .. warning:: The content is only available for demonstration purposes and does not implement
anti-XSS, anti-XSRF or other security techniques. Do not use this code in production. anti-XSS, anti-XSRF or other security techniques. Do not use this code in production.
Creating an IOU via the endpoint Creating an IOU via the endpoint
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
An IOU can be created by sending a PUT request to the ``/api/example/create-iou`` endpoint directly, or by using the An IOU can be created by sending a PUT request to the ``/api/example/create-iou`` endpoint directly, or by using the
the web form served from ``/web/example``. the web form served from the home directory.
To create an IOU between PartyA and PartyB, run the following command from the command line: To create an IOU between PartyA and PartyB, run the following command from the command line:
.. sourcecode:: bash .. sourcecode:: bash
curl -X PUT 'http://localhost:10007/api/example/create-iou?iouValue=1&partyName=O=PartyB,L=New%20York,C=US' curl -X PUT 'http://localhost:50005/api/example/create-iou?iouValue=1&partyName=O=PartyB,L=New%20York,C=US'
Note that both PartyA's port number (``10007``) and PartyB are referenced in the PUT request path. This command Note that both PartyA's port number (``50005``) and PartyB are referenced in the PUT request path. This command
instructs PartyA to agree an IOU with PartyB. Once the process is complete, both nodes will have a signed, notarised instructs PartyA to agree an IOU with PartyB. Once the process is complete, both nodes will have a signed, notarised
copy of the IOU. PartyC will not. copy of the IOU. PartyC will not.
Submitting an IOU via the web front-end Submitting an IOU via the web front-end
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To create an IOU between PartyA and PartyB, navigate to ``/web/example``, click the "create IOU" button at the top-left To create an IOU between PartyA and PartyB, navigate to the home directory for the node, click the "create IOU" button at the top-left
of the page, and enter the IOU details into the web-form. The IOU must have a positive value. For example: of the page, and enter the IOU details into the web-form. The IOU must have a positive value. For example:
.. sourcecode:: none .. sourcecode:: none
@ -318,15 +323,15 @@ Assuming all went well, you can view the newly-created IOU by accessing the vaul
*Via the HTTP API:* *Via the HTTP API:*
* PartyA's vault: Navigate to http://localhost:10007/api/example/ious * PartyA's vault: Navigate to http://localhost:50005/api/example/ious
* PartyB's vault: Navigate to http://localhost:10011/api/example/ious * PartyB's vault: Navigate to http://localhost:50006/api/example/ious
*Via web/example:* *Via home page:*
* PartyA: Navigate to http://localhost:10007/web/example and hit the "refresh" button * PartyA: Navigate to http://localhost:50005 and hit the "refresh" button
* PartyB: Navigate to http://localhost:10011/web/example and hit the "refresh" button * PartyB: Navigate to http://localhost:50006 and hit the "refresh" button
The vault and web front-end of PartyC (at ``localhost:10015``) will not display any IOUs. This is because PartyC was The vault and web front-end of PartyC (at ``localhost:50007``) will not display any IOUs. This is because PartyC was
not involved in this transaction. not involved in this transaction.
Via the interactive shell (terminal only) Via the interactive shell (terminal only)
@ -345,13 +350,15 @@ following list:
.. sourcecode:: none .. sourcecode:: none
com.example.flow.ExampleFlow$Initiator com.example.flow.ExampleFlow$Initiator
net.corda.core.flows.ContractUpgradeFlow$Initiator net.corda.core.flows.ContractUpgradeFlow$Authorise
net.corda.core.flows.ContractUpgradeFlow$Initiator net.corda.core.flows.ContractUpgradeFlow$Deauthorise
net.corda.finance.flows.CashExitFlow net.corda.core.flows.ContractUpgradeFlow$Initiate
net.corda.finance.flows.CashIssueAndPaymentFlow net.corda.finance.flows.CashExitFlow
net.corda.finance.flows.CashIssueFlow net.corda.finance.flows.CashIssueAndPaymentFlow
net.corda.finance.flows.CashPaymentFlow net.corda.finance.flows.CashIssueFlow
net.corda.finance.flows.CashPaymentFlow
net.corda.finance.internal.CashConfigDataFlow
Creating an IOU via the interactive shell Creating an IOU via the interactive shell
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^