diff --git a/build.gradle b/build.gradle index acee113b33..6cfd34fed9 100644 --- a/build.gradle +++ b/build.gradle @@ -116,12 +116,14 @@ allprojects { } } - tasks.withType(Jar) { // Includes War and Ear + tasks.withType(Jar) { task -> + // Includes War and Ear manifest { attributes('Corda-Release-Version': corda_release_version) attributes('Corda-Platform-Version': corda_platform_version) attributes('Corda-Revision': corda_revision) attributes('Corda-Vendor': 'Corda Open Source') + attributes('Automatic-Module-Name': "net.corda.${task.project.name.replaceAll('-', '.')}") } } diff --git a/client/jackson/build.gradle b/client/jackson/build.gradle index bcff947dfb..fadfdf9975 100644 --- a/client/jackson/build.gradle +++ b/client/jackson/build.gradle @@ -25,6 +25,9 @@ dependencies { jar { baseName 'corda-jackson' + manifest { + attributes 'Automatic-Module-Name': 'net.corda.client.jackson' + } } publish { diff --git a/client/jfx/build.gradle b/client/jfx/build.gradle index 867ba2b9f0..aaf1d5fd14 100644 --- a/client/jfx/build.gradle +++ b/client/jfx/build.gradle @@ -57,6 +57,9 @@ task integrationTest(type: Test) { jar { baseName 'corda-jfx' + manifest { + attributes 'Automatic-Module-Name': 'net.corda.client.jfx' + } } publish { diff --git a/client/mock/build.gradle b/client/mock/build.gradle index 1080cf9b7a..b492455b49 100644 --- a/client/mock/build.gradle +++ b/client/mock/build.gradle @@ -21,6 +21,9 @@ dependencies { jar { baseName 'corda-mock' + manifest { + attributes 'Automatic-Module-Name': 'net.corda.client.mock' + } } publish { diff --git a/client/rpc/build.gradle b/client/rpc/build.gradle index d8c61b4a99..bd234e8ee1 100644 --- a/client/rpc/build.gradle +++ b/client/rpc/build.gradle @@ -90,6 +90,9 @@ task smokeTest(type: Test) { jar { baseName 'corda-rpc' + manifest { + attributes 'Automatic-Module-Name': 'net.corda.client.rpc' + } } publish { diff --git a/docs/source/api-index.rst b/docs/source/api-index.rst deleted file mode 100644 index c3486e4cea..0000000000 --- a/docs/source/api-index.rst +++ /dev/null @@ -1,64 +0,0 @@ -API -=== - -This section describes the APIs that are available for the development of CorDapps: - -.. toctree:: - :maxdepth: 1 - - api-states - api-persistence - api-contracts - api-vault-query - api-transactions - api-flows - api-identity - api-service-hub - api-rpc - api-core-types - -Before reading this page, you should be familiar with the :doc:`key concepts of Corda `. - -Internal APIs and stability guarantees --------------------------------------- - -.. warning:: For Corda 1.0 we do not currently provide a stable wire protocol or support for database upgrades. - Additionally, the JSON format produced by the client-jackson module may change in future. - Therefore, you should not expect to be able to migrate persisted data from 1.0 to future versions. - - Additionally, it may be necessary to recompile applications against future versions of the API until we begin offering - ABI stability as well. We plan to do this soon after the release of Corda 1.0. - - Finally, please note that the 1.0 release has not yet been security audited. You should not run it in situations - where security is required. - -As of Corda 1.0, the following modules export public API that we promise to maintain backwards compatibility for, -unless an incompatible change is required for security reasons: - -* core -* client-rpc -* client-jackson - -The following modules don't yet have a completely stable API, but we will do our best to minimise disruption to -developers using them until we are able to graduate them into the public API: - -* the Gradle plugins (cordformation) -* node-driver -* confidential-identities -* test-utils -* client-jfx, client-mock -* finance -* anything under the experimental directory (sub-components here may never graduate) - -We hope to graduate the node-driver, test-utils and confidential-identities modules in the next feature release -after 1.0. The bulk of the Corda API is found in the core module. Other modules should be assumed to be fully internal. - -The web server module will be removed in future: you should build web front-ends for CorDapps using standard frameworks -like Spring Boot, J2EE, Play, etc. - -Code that falls into the following packages namespaces are for internal use only and not for public use: - -* Any package in the ``net.corda`` namespace which contains ``.internal`` -* ``net.corda.node`` - -In the future releases the node upon starting up will reject any CorDapps which uses classes from these packages. \ No newline at end of file diff --git a/docs/source/building-a-cordapp-index.rst b/docs/source/building-a-cordapp-index.rst index e073aef623..12466338ee 100644 --- a/docs/source/building-a-cordapp-index.rst +++ b/docs/source/building-a-cordapp-index.rst @@ -7,6 +7,5 @@ Building a CorDapp cordapp-overview writing-cordapps cordapp-build-systems - api-index flow-cookbook cheat-sheet \ No newline at end of file diff --git a/docs/source/corda-modules.rst b/docs/source/corda-modules.rst new file mode 100644 index 0000000000..0307db092c --- /dev/null +++ b/docs/source/corda-modules.rst @@ -0,0 +1,93 @@ +Corda modules +============= + +This section describes the APIs that are available for the development of CorDapps: + +.. toctree:: + :maxdepth: 1 + + api-states + api-persistence + api-contracts + api-vault-query + api-transactions + api-flows + api-identity + api-service-hub + api-rpc + api-core-types + +Before reading this page, you should be familiar with the :doc:`key concepts of Corda `. + +Internal APIs and stability guarantees +-------------------------------------- + +.. warning:: For Corda 1.0 we do not currently provide a stable wire protocol or support for database upgrades. + Additionally, the JSON format produced by the client-jackson module may change in future. + Therefore, you should not expect to be able to migrate persisted data from 1.0 to future versions. + + Additionally, it may be necessary to recompile applications against future versions of the API until we begin offering + ABI stability as well. We plan to do this soon after the release of Corda 1.0. + + Finally, please note that the 1.0 release has not yet been security audited. You should not run it in situations + where security is required. + +Corda artifacts can be required from Java 9 Jigsaw modules. +From within a ``module-info.java``, you can reference one of the modules e.g., ``requires net.corda.core;``. + +.. warning:: while Corda artifacts can be required from ``module-info.java`` files, they are still not proper Jigsaw modules, + because they rely on the automatic module mechanism and declare no module descriptors themselves. We plan to integrate Jigsaw more thoroughly in the future. + +Corda stable modules +-------------------- + +The following modules have a stable API we commit not to break in following releases, unless an incompatible change is required for security reasons: + +* **Core (net.corda.core)**: core Corda libraries such as crypto functions, types for Corda's building blocks: states, contracts, transactions, attachments, etc. and some interfaces for nodes and protocols +* **Client RPC (net.corda.client.rpc)**: client RPC +* **Client Jackson (net.corda.client.jackson)**: JSON support for client applications + +Corda incubating modules +------------------------ + +The following modules don't yet have a completely stable API, but we will do our best to minimise disruption to +developers using them until we are able to graduate them into the public API: + +* **net.corda.node.driver**: test utilities to run nodes programmatically +* **net.corda.confidential.identities**: experimental support for confidential identities on the ledger +* **net.corda.node.test.utils**: generic test utilities +* **net.corda.finance**: a range of elementary contracts (and associated schemas) and protocols, such as abstract fungible assets, cash, obligation and commercial paper +* **net.corda.client.jfx**: support for Java FX UI +* **net.corda.client.mock**: client mock utilities +* **Cordformation**: Gradle integration plugins + +Corda unstable modules +---------------------- + +The following modules are available but we do not commit to their stability or continuation in any sense: + +* **net.corda.buildSrc**: necessary gradle plugins to build Corda +* **net.corda.node**: core code of the Corda node (eg: node driver, node services, messaging, persistence) +* **net.corda.node.api**: data structures shared between the node and the client module, e.g. types sent via RPC +* **net.corda.samples.network.visualiser**: a network visualiser that uses a simulation to visualise the interaction and messages between nodes on the Corda network +* **net.corda.samples.demos.attachment**: demonstrates sending a transaction with an attachment from one to node to another, and the receiving node accessing the attachment +* **net.corda.samples.demos.bankofcorda**: simulates the role of an asset issuing authority (eg. central bank for cash) +* **net.corda.samples.demos.irs**: demonstrates an Interest Rate Swap agreement between two banks +* **net.corda.samples.demos.notary**: a simple demonstration of a node getting multiple transactions notarised by a distributed (Raft or BFT SMaRt) notary +* **net.corda.samples.demos.simmvaluation**: See our [main documentation site](https://docs.corda.net/initial-margin-agreement.html) regarding the SIMM valuation and agreement on a distributed ledger +* **net.corda.samples.demos.trader**: demonstrates four nodes, a notary, an issuer of cash (Bank of Corda), and two parties trading with each other, exchanging cash for a commercial paper +* **net.corda.node.smoke.test.utils**: test utilities for smoke testing +* **net.corda.node.test.common**: common test functionality +* **net.corda.tools.demobench**: a GUI tool that allows to run Corda nodes locally for demonstrations +* **net.corda.tools.explorer**: a GUI front-end for Corda +* **net.corda.tools.graphs**: utilities to infer project dependencies +* **net.corda.tools.loadtest**: Corda load tests +* **net.corda.verifier**: allows out-of-node transaction verification, allowing verification to scale horizontally +* **net.corda.webserver**: is a servlet container for CorDapps that export HTTP endpoints. This server is an RPC client of the node +* **net.corda.sandbox-creator**: sandbox utilities +* **net.corda.quasar.hook**: agent to hook into Quasar and provide types exclusion lists + +.. warning:: Code inside any package in the ``net.corda`` namespace which contains ``.internal`` or in ``net.corda.node`` for internal use only. + Future releases will reject any CorDapps that use types from these packages. + +.. warning:: The web server module will be removed in future. You should call Corda nodes through RPC from your web server of choice e.g., Spring Boot, Vertx, Undertow. \ No newline at end of file diff --git a/docs/source/getting-set-up.rst b/docs/source/getting-set-up.rst index 95bb99bfc9..1fbe7060b3 100644 --- a/docs/source/getting-set-up.rst +++ b/docs/source/getting-set-up.rst @@ -169,7 +169,7 @@ The best way to check that everything is working fine is by taking a deeper look Next, you should read through :doc:`Corda Key Concepts ` to understand how Corda works. By then, you'll be ready to start writing your own CorDapps. Learn how to do this in the -:doc:`Hello, World tutorial `. You may want to refer to the :doc:`API docs ` along the +:doc:`Hello, World tutorial `. You may want to refer to the :doc:`Modules documentation ` along the way. If you encounter any issues, please see the :doc:`troubleshooting` page, or get in touch with us on the diff --git a/docs/source/other-index.rst b/docs/source/other-index.rst index 7f6fa6ef66..539608be94 100644 --- a/docs/source/other-index.rst +++ b/docs/source/other-index.rst @@ -7,5 +7,6 @@ Other json secure-coding-guidelines corda-repo-layout + corda-modules building-the-docs codestyle \ No newline at end of file diff --git a/docs/source/release-notes.rst b/docs/source/release-notes.rst index 845933db05..3552fc329e 100644 --- a/docs/source/release-notes.rst +++ b/docs/source/release-notes.rst @@ -32,7 +32,7 @@ Our extensive testing frameworks will continue to evolve alongside future Corda we have introduced a new test node driver module to encapsulate all test functionality in support of building standalone node integration tests using our DSL driver. -Please read :doc:`api-index` for complete details. +Please read :doc:`corda-modules` for complete details. .. note:: it may be necessary to recompile applications against future versions of the API until we begin offering `ABI (Application Binary Interface) `_ stability as well. diff --git a/experimental/sandbox/build.gradle b/experimental/sandbox/build.gradle index 53e244815a..2e64b70651 100644 --- a/experimental/sandbox/build.gradle +++ b/experimental/sandbox/build.gradle @@ -30,7 +30,10 @@ task standaloneJar(type: Jar) { } with jar manifest { - attributes 'Main-Class': 'net.corda.sandbox.tools.SandboxCreator' + attributes( + 'Main-Class': 'net.corda.sandbox.tools.SandboxCreator', + 'Automatic-Module-Name': 'net.corda.sandbox.creator' + ) } archiveName "corda-sandbox-creator-${version}.jar" } diff --git a/samples/attachment-demo/build.gradle b/samples/attachment-demo/build.gradle index 170f9e265c..1ca4d85d3d 100644 --- a/samples/attachment-demo/build.gradle +++ b/samples/attachment-demo/build.gradle @@ -102,3 +102,11 @@ task runRecipient(type: JavaExec) { args '--role' args 'RECIPIENT' } + +jar { + manifest { + attributes( + 'Automatic-Module-Name': 'net.corda.samples.demos.attachment' + ) + } +} diff --git a/samples/bank-of-corda-demo/build.gradle b/samples/bank-of-corda-demo/build.gradle index 4da684ed47..dcdbe408d0 100644 --- a/samples/bank-of-corda-demo/build.gradle +++ b/samples/bank-of-corda-demo/build.gradle @@ -143,3 +143,11 @@ task runWebCashIssue(type: JavaExec) { args '--currency' args 'GBP' } + +jar { + manifest { + attributes( + 'Automatic-Module-Name': 'net.corda.samples.demos.bankofcorda' + ) + } +} diff --git a/samples/irs-demo/build.gradle b/samples/irs-demo/build.gradle index d1bd45a246..6d9b908823 100644 --- a/samples/irs-demo/build.gradle +++ b/samples/irs-demo/build.gradle @@ -117,4 +117,9 @@ publishing { jar { from sourceSets.test.output + manifest { + attributes( + 'Automatic-Module-Name': 'net.corda.samples.demos.irs' + ) + } } diff --git a/samples/network-visualiser/build.gradle b/samples/network-visualiser/build.gradle index bad1295dbc..d0ee4ea3e3 100644 --- a/samples/network-visualiser/build.gradle +++ b/samples/network-visualiser/build.gradle @@ -42,3 +42,11 @@ task deployVisualiser(type: FatCapsule) { javaAgents = [configurations.quasar.singleFile.name] } } + +jar { + manifest { + attributes( + 'Automatic-Module-Name': 'net.corda.samples.network.visualiser' + ) + } +} diff --git a/samples/notary-demo/build.gradle b/samples/notary-demo/build.gradle index b2d3f3e341..fbbaa6a9a7 100644 --- a/samples/notary-demo/build.gradle +++ b/samples/notary-demo/build.gradle @@ -66,3 +66,11 @@ task notarise(type: JavaExec) { classpath = sourceSets.main.runtimeClasspath main = 'net.corda.notarydemo.NotariseKt' } + +jar { + manifest { + attributes( + 'Automatic-Module-Name': 'net.corda.samples.demos.notary' + ) + } +} diff --git a/samples/simm-valuation-demo/build.gradle b/samples/simm-valuation-demo/build.gradle index 1d7d654ee8..278608bd77 100644 --- a/samples/simm-valuation-demo/build.gradle +++ b/samples/simm-valuation-demo/build.gradle @@ -117,3 +117,11 @@ publishing { } } } + +jar { + manifest { + attributes( + 'Automatic-Module-Name': 'net.corda.samples.demos.simmvaluation' + ) + } +} diff --git a/samples/trader-demo/build.gradle b/samples/trader-demo/build.gradle index 216405f66f..5d2a1750eb 100644 --- a/samples/trader-demo/build.gradle +++ b/samples/trader-demo/build.gradle @@ -121,3 +121,11 @@ task runSeller(type: JavaExec) { args '--role' args 'SELLER' } + +jar { + manifest { + attributes( + 'Automatic-Module-Name': 'net.corda.samples.demos.trader' + ) + } +} \ No newline at end of file diff --git a/tools/demobench/build.gradle b/tools/demobench/build.gradle index 6a3452b8c9..727a5c8237 100644 --- a/tools/demobench/build.gradle +++ b/tools/demobench/build.gradle @@ -78,7 +78,8 @@ jar { manifest { attributes( 'Main-Class': mainClassName, - 'Class-Path': configurations.runtime.collect { it.getName() }.join(' ') + 'Class-Path': configurations.runtime.collect { it.getName() }.join(' '), + 'Automatic-Module-Name': 'net.corda.tools.demobench' ) } } diff --git a/tools/explorer/build.gradle b/tools/explorer/build.gradle index 3ffc1e543c..9eddf905ca 100644 --- a/tools/explorer/build.gradle +++ b/tools/explorer/build.gradle @@ -65,3 +65,11 @@ task(runSimulationNodes, dependsOn: 'classes', type: JavaExec) { classpath = sourceSets.main.runtimeClasspath args '-S' } + +jar { + manifest { + attributes( + 'Automatic-Module-Name': 'net.corda.tools.explorer' + ) + } +} \ No newline at end of file diff --git a/tools/graphs/build.gradle b/tools/graphs/build.gradle index 5e81dee1c9..01a4da9637 100644 --- a/tools/graphs/build.gradle +++ b/tools/graphs/build.gradle @@ -79,3 +79,11 @@ task graphs { } } } + +jar { + manifest { + attributes( + 'Automatic-Module-Name': 'net.corda.tools.graphs' + ) + } +} \ No newline at end of file diff --git a/tools/loadtest/build.gradle b/tools/loadtest/build.gradle index af7012b2e6..00480419c0 100644 --- a/tools/loadtest/build.gradle +++ b/tools/loadtest/build.gradle @@ -35,3 +35,11 @@ run { systemProperty "consoleLogLevel", System.properties.getProperty('consoleLogLevel') } } + +jar { + manifest { + attributes( + 'Automatic-Module-Name': 'net.corda.tools.loadtest' + ) + } +}