mirror of
https://github.com/corda/corda.git
synced 2024-12-24 07:06:44 +00:00
[CORDA-2560] Add upgrade notes for custom configuration and improve cordapp config… (#4730)
* Add upgrade notes for custom configuration and improve cordapp configuration documentation. * Address review comments * Couple of minor nitpicks
This commit is contained in:
Anthony Keenan
Tommy Lillehagen
parent
39d3012723
commit
aad1ae5945
8
docs/README.md
Normal file
8
docs/README.md
Normal file
@ -0,0 +1,8 @@
|
||||
# Corda Documentation Build
|
||||
|
||||
To run the Corda Documentation build run ``./gradlew makeDocs``
|
||||
|
||||
Note: In order to run the documentation build you will need Docker installed.
|
||||
|
||||
Windows users: If this task fails because Docker can't find make-docsite.sh, go to Settings > Shared Drives in the Docker system tray
|
||||
agent, make sure the relevant drive is shared, and click 'Reset credentials'.
|
||||
@ -24,7 +24,7 @@ from the new features in the latest release.
|
||||
:depth: 3
|
||||
|
||||
Step 1. Switch any RPC clients to use the new RPC library
|
||||
----------------------------------------------------------
|
||||
---------------------------------------------------------
|
||||
|
||||
Although the RPC API is backwards compatible with Corda 3, the RPC wire protocol isn't. Therefore RPC clients like web servers need to be
|
||||
updated in lockstep with the node to use the new version of the RPC library. Corda 4 delivers RPC wire stability and therefore in future you
|
||||
@ -117,7 +117,44 @@ starting from 1.
|
||||
If you use the finance demo app, you should adjust your dependencies so you depend on the finance-contracts
|
||||
and finance-workflows artifacts from your own contract and workflow JAR respectively.
|
||||
|
||||
Step 4. Security: Upgrade your use of FinalityFlow
|
||||
Step 4. Remove any custom configuration from the node.conf
|
||||
----------------------------------------------------------
|
||||
|
||||
CorDapps can no longer access custom configuration items in the ``node.conf`` file. Any custom CorDapp configuration should be added to a
|
||||
CorDapp configuration file. The Node's configuration will not be accessible. CorDapp configuration files should be placed in the
|
||||
`config` subdirectory of the Node's `cordapps` folder. The name of the file should match the name of the JAR of the CorDapp (eg; if your
|
||||
CorDapp is called ``hello-0.1.jar`` the configuration file needed would be ``cordapps/config/hello-0.1.conf``).
|
||||
|
||||
If you are using the ``extraConfig`` of a ``node`` in the ``deployNodes`` Gradle task to populate custom configuration for testing, you will need
|
||||
to make the following change so that:
|
||||
|
||||
.. sourcecode:: groovy
|
||||
|
||||
task deployNodes(type: net.corda.plugins.Cordform, dependsOn: ['jar']) {
|
||||
node {
|
||||
name "O=Bank A,L=London,C=GB"c
|
||||
...
|
||||
extraConfig = [ 'some.extra.config' : '12345' ]
|
||||
}
|
||||
}
|
||||
|
||||
Would become:
|
||||
|
||||
.. sourcecode:: groovy
|
||||
|
||||
task deployNodes(type: net.corda.plugins.Cordform, dependsOn: ['jar']) {
|
||||
node {
|
||||
name "O=Bank A,L=London,C=GB"c
|
||||
...
|
||||
projectCordapp {
|
||||
config "some.extra.config=12345"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
See :ref:`cordapp_configuration_files_ref` for more information.
|
||||
|
||||
Step 5. Security: Upgrade your use of FinalityFlow
|
||||
--------------------------------------------------
|
||||
|
||||
The previous ``FinalityFlow`` API is insecure. It doesn't have a receive flow, so requires counterparty nodes to accept any and
|
||||
@ -231,7 +268,7 @@ You may already be using ``waitForLedgerCommit`` in your responder flow for the
|
||||
Now that it's calling ``ReceiveFinalityFlow``, which effectively does the same thing, this is no longer necessary. The call to
|
||||
``waitForLedgerCommit`` should be removed.
|
||||
|
||||
Step 5. Security: Upgrade your use of SwapIdentitiesFlow
|
||||
Step 6. Security: Upgrade your use of SwapIdentitiesFlow
|
||||
--------------------------------------------------------
|
||||
|
||||
The :ref:`confidential_identities_ref` API is experimental in Corda 3 and remains so in Corda 4. In this release, the ``SwapIdentitiesFlow``
|
||||
@ -239,7 +276,7 @@ has been adjusted in the same way as ``FinalityFlow`` above, to close problems w
|
||||
outside of other flow context. Old code will still work, but it is recommended to adjust your call sites so a session is passed into
|
||||
the ``SwapIdentitiesFlow``.
|
||||
|
||||
Step 6. Possibly, adjust test code
|
||||
Step 7. Possibly, adjust test code
|
||||
----------------------------------
|
||||
|
||||
``MockNodeParameters`` and functions creating it no longer use a lambda expecting a ``NodeConfiguration`` object.
|
||||
@ -290,7 +327,7 @@ For instance, if you have 2 CorDapps containing the packages ``net.corda.example
|
||||
.. note:: If you have any CorDapp code (e.g. flows/contracts/states) that is only used by the tests and located in the same test module, it won't be discovered now.
|
||||
You will need to move them in the main module of one of your CorDapps or create a new, separate CorDapp for them, in case you don't want this code to live inside your production CorDapps.
|
||||
|
||||
Step 7. Security: Add BelongsToContract annotations
|
||||
Step 8. Security: Add BelongsToContract annotations
|
||||
---------------------------------------------------
|
||||
|
||||
In versions of the platform prior to v4, it was the responsibility of contract and flow logic to ensure that ``TransactionState`` objects
|
||||
@ -307,7 +344,7 @@ to be governed by a contract that is either:
|
||||
Learn more by reading ":ref:`implicit_constraint_types`". If an app targets Corda 3 or lower (i.e. does not specify a target version),
|
||||
states that point to contracts outside their package will trigger a log warning but validation will proceed.
|
||||
|
||||
Step 8. Learn about signature constraints and JAR signing
|
||||
Step 9. Learn about signature constraints and JAR signing
|
||||
---------------------------------------------------------
|
||||
|
||||
:doc:`design/data-model-upgrades/signature-constraints` are a new data model feature introduced in Corda 4. They make it much easier to
|
||||
@ -321,8 +358,8 @@ automatically use them if your application JAR is signed. **We recommend all JAR
|
||||
with developer certificates is deployed to a production node, the node will refuse to start. Therefore to deploy apps built for Corda 4
|
||||
to production you will need to generate signing keys and integrate them with the build process.
|
||||
|
||||
Step 9. Security: Package namespace handling
|
||||
--------------------------------------------
|
||||
Step 10. Security: Package namespace handling
|
||||
---------------------------------------------
|
||||
|
||||
Almost no apps will be affected by these changes, but they're important to know about.
|
||||
|
||||
@ -349,7 +386,7 @@ Whilst this feature is optional and not strictly required, it may be helpful to
|
||||
where type names may be taken "as read". You can learn more about this feature and the motivation for it by reading
|
||||
":doc:`design/data-model-upgrades/package-namespace-ownership`".
|
||||
|
||||
Step 10. Consider adding extension points to your flows
|
||||
Step 11. Consider adding extension points to your flows
|
||||
-------------------------------------------------------
|
||||
|
||||
In Corda 4 it is possible for flows in one app to subclass and take over flows from another. This allows you to create generic, shared
|
||||
@ -359,7 +396,7 @@ into shared business logic, but it makes perfect sense to put into a user-specif
|
||||
|
||||
If your flows could benefit from being extended in this way, read ":doc:`flow-overriding`" to learn more.
|
||||
|
||||
Step 11. Possibly update vault state queries
|
||||
Step 12. Possibly update vault state queries
|
||||
--------------------------------------------
|
||||
|
||||
In Corda 4 queries made on a node's vault can filter by the relevancy of those states to the node. As this functionality does not exist in
|
||||
@ -367,7 +404,7 @@ Corda 3, apps will continue to receive all states in any vault queries. However,
|
||||
to the node in question to query for only relevant states. See :doc:`api-vault-query.rst` for more details on how to do this. Not doing this
|
||||
may result in queries returning more states than expected if the node is using observer functionality (see ":doc:`tutorial-observer-nodes.rst`").
|
||||
|
||||
Step 12. Explore other new features that may be useful
|
||||
Step 13. Explore other new features that may be useful
|
||||
------------------------------------------------------
|
||||
|
||||
Corda 4 adds several new APIs that help you build applications. Why not explore:
|
||||
|
||||
@ -289,10 +289,9 @@ Also the best practice is to disable signing by the ``cordapp`` plugin as shown
|
||||
|
||||
Example
|
||||
^^^^^^^
|
||||
Below is a sample of what a CorDapp's Gradle dependencies block might look like. When building your own CorDapp, you
|
||||
should base yourself on the ``build.gradle`` file of the
|
||||
Below is a sample CorDapp Gradle dependencies block. When building your own CorDapp, use the ``build.gradle`` file of the
|
||||
`Kotlin CorDapp Template <https://github.com/corda/cordapp-template-kotlin>`_ or the
|
||||
`Java CorDapp Template <https://github.com/corda/cordapp-template-java>`_.
|
||||
`Java CorDapp Template <https://github.com/corda/cordapp-template-java>`_ as a starting point.
|
||||
|
||||
.. container:: codeset
|
||||
|
||||
@ -358,6 +357,8 @@ At start-up, nodes will load any CorDapps present in their ``cordapps`` folder.
|
||||
CorDapp JAR must be added to the ``<node_dir>/cordapps/`` folder (where ``node_dir`` is the folder in which the node's JAR
|
||||
and configuration files are stored) and the node restarted.
|
||||
|
||||
.. _cordapp_configuration_files_ref:
|
||||
|
||||
CorDapp configuration files
|
||||
---------------------------
|
||||
|
||||
@ -367,11 +368,57 @@ name of the JAR of the CorDapp (eg; if your CorDapp is called ``hello-0.1.jar``
|
||||
Config files are currently only available in the `Typesafe/Lightbend <https://github.com/lightbend/config>`_ config format.
|
||||
These files are loaded when a CorDapp context is created and so can change during runtime.
|
||||
|
||||
CorDapp configuration can be accessed from ``CordappContext::config`` whenever a ``CordappContext`` is available.
|
||||
CorDapp configuration can be accessed from ``CordappContext::config`` whenever a ``CordappContext`` is available. For example:
|
||||
|
||||
There is an example project that demonstrates in ``samples`` called ``cordapp-configuration`` and API documentation in
|
||||
`<api/kotlin/corda/net.corda.core.cordapp/index.html>`_.
|
||||
.. literalinclude:: ../../samples/cordapp-configuration/workflows/src/main/kotlin/net/corda/configsample/GetStringConfigFlow.kt
|
||||
:language: kotlin
|
||||
:start-after: DOCSTART 1
|
||||
:end-before: DOCEND 1
|
||||
|
||||
Using CorDapp configuration with the deployNodes task
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If you want to generate CorDapp configuration when using the ``deployNodes`` Gradle task, then you can use the ``cordapp`` or ``projectCordapp``
|
||||
properties on the node. For example:
|
||||
|
||||
.. sourcecode:: groovy
|
||||
|
||||
task deployNodes(type: net.corda.plugins.Cordform, dependsOn: ['jar']) {
|
||||
nodeDefaults {
|
||||
// this external CorDapp will be included in each project
|
||||
cordapp("$corda_release_group:corda-finance-contracts:$corda_release_version")
|
||||
// this external CorDapp will be included in each project with the given config
|
||||
cordapp("$corda_release_group:corda-finance-workflows:$corda_release_version") {
|
||||
config "issuableCurrencies = [ USD ]"
|
||||
}
|
||||
}
|
||||
node {
|
||||
name "O=Bank A,L=London,C=GB"c
|
||||
...
|
||||
// This adds configuration for another CorDapp project within the build
|
||||
cordapp (project(':my-project:workflow-cordapp')) {
|
||||
config "someStringValue=test"
|
||||
}
|
||||
cordapp(project(':my-project:another-cordapp')) {
|
||||
// Use a multiline string for complex configuration
|
||||
config '''
|
||||
someStringValue=test
|
||||
anotherStringValue=10
|
||||
'''
|
||||
}
|
||||
}
|
||||
node {
|
||||
name "O=Bank B,L=New York,C=US"
|
||||
...
|
||||
// This adds configuration for the default CorDapp for this project
|
||||
projectCordapp {
|
||||
config project.file("src/config.conf")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
There is an example project that demonstrates this in the ``samples`` folder of the Corda Git repository, called ``cordapp-configuration`` .
|
||||
API documentation can be found at `<api/kotlin/corda/net.corda.core.cordapp/index.html>`_.
|
||||
|
||||
Minimum and target platform version
|
||||
-----------------------------------
|
||||
|
||||
@ -11,6 +11,7 @@ import net.corda.core.serialization.CordaSerializable
|
||||
import net.corda.core.transactions.LedgerTransaction
|
||||
import net.corda.core.utilities.ProgressTracker
|
||||
|
||||
// DOCSTART 1
|
||||
@StartableByRPC
|
||||
class GetStringConfigFlow(private val configKey: String) : FlowLogic<String>() {
|
||||
object READING : ProgressTracker.Step("Reading config")
|
||||
@ -23,3 +24,4 @@ class GetStringConfigFlow(private val configKey: String) : FlowLogic<String>() {
|
||||
return config.getString(configKey)
|
||||
}
|
||||
}
|
||||
// DOCEND 1
|
||||
Loading…
Reference in New Issue
Block a user