[CORDA-682]: Claim Jigsaw module names (#1824)

[CORDA-682] Specify Jigsaw module names for all JAR projects.

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('-', '.')}")
         }
     }
 

client/jackson/build.gradle

@@ -25,6 +25,9 @@ dependencies {
 
 jar {
     baseName 'corda-jackson'
+    manifest {
+        attributes 'Automatic-Module-Name': 'net.corda.client.jackson'
+    }
 }
 
 publish {

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 {

client/mock/build.gradle

@@ -21,6 +21,9 @@ dependencies {
 
 jar {
     baseName 'corda-mock'
+    manifest {
+        attributes 'Automatic-Module-Name': 'net.corda.client.mock'
+    }
 }
 
 publish {

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 {

docs/source/api-index.rst

@@ -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 <key-concepts>`.
-
-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.

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

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 <key-concepts>`.
+
+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.

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 <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 <hello-world-index>`. You may want to refer to the :doc:`API docs <api-index>` along the
+:doc:`Hello, World tutorial <hello-world-index>`. You may want to refer to the :doc:`Modules documentation <corda-modules>` along the
 way.
 
 If you encounter any issues, please see the :doc:`troubleshooting` page, or get in touch with us on the

docs/source/other-index.rst

@@ -7,5 +7,6 @@ Other
    json
    secure-coding-guidelines
    corda-repo-layout
+   corda-modules
    building-the-docs
    codestyle

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) <https://en.wikipedia.org/wiki/Application_binary_interface>`_ stability as well.

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"
 }

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'
+        )
+    }
+}

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'
+        )
+    }
+}

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'
+        )
+    }
 }

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'
+        )
+    }
+}

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'
+        )
+    }
+}

samples/simm-valuation-demo/build.gradle

@@ -117,3 +117,11 @@ publishing {
         }
     }
 }
+
+jar {
+    manifest {
+        attributes(
+                'Automatic-Module-Name': 'net.corda.samples.demos.simmvaluation'
+        )
+    }
+}

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'
+        )
+    }
+}

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'
         )
     }
 }

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'
+        )
+    }
+}

tools/graphs/build.gradle

@@ -79,3 +79,11 @@ task graphs {
         }
     }
 }
+
+jar {
+    manifest {
+        attributes(
+                'Automatic-Module-Name': 'net.corda.tools.graphs'
+        )
+    }
+}

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'
+        )
+    }
+}